What is Immich?

Immich is a self-hosted photo and video management solution that serves as a powerful alternative to cloud services like Google Photos or Apple Photos. It's part of a "degoogle" strategy; a place to back up, deduplicate, and unify RAW files, processed photos, and videos from various cameras into one cohesive library.

The project is actively developed and slick. I'm looking forward to more advanced photo management features as it matures.

The Problem

I run my blog on Directus and wanted a way to expose photo galleries from my Immich instance directly through my site. I've been manually uploading processed photos to Directus. I wanted to select images from my Immich library from right within the Directus interface.

Building the Extension

Directus has a powerful extension system that allows you to create custom interfaces, endpoints, and more. I built a custom interface extension that:

  1. Connects to Immich's API - Authenticates and fetches album/asset data from your Immich instance
  2. Provides a picker interface - Browse albums and select images without leaving Directus
  3. Stores references - Saves Immich asset IDs so your frontend can fetch the images at render time

The extension consists of:

  • Interface component - A Vue-based picker that displays Immich albums and assets
  • API proxy endpoint - Handles authentication to Immich from the Directus backend
  • Configuration options - Settings for Immich server URL and API key

Implementation Highlights

// The interface stores asset metadata from Immich
interface ImmichAsset {
  id: string;
  deviceAssetId: string;
  thumbhash: string;
  originalFileName: string;
  // ... additional metadata
}

The picker interface allows multi-select for galleries, storing an array of asset references that your frontend can use to construct image URLs.

Using It in Practice

With the extension installed, creating a gallery is straightforward:

  1. Create a new gallery item in Directus
  2. Click the Immich image picker field
  3. Browse your Immich albums or search/filter for specific photos
  4. Select the images you want to include
  5. Save the asset references are stored and ready for your frontend

Frontend Integration

On the frontend (SvelteKit in my case), I fetch the gallery data from Directus and use the stored Immich asset IDs to construct image URLs:

const getImmichImageUrl = (assetId: string, size: 'thumbnail' | 'preview') => {
  return `${IMMICH_URL}/api/assets/${assetId}/${size}`;
};

This approach keeps the source of truth in Immich while letting Directus handle the content management and curation aspects.

What's Next

I'm planning to add:

  • Shared link support - Use Immich's public shared links for unauthenticated access
  • EXIF data display - Pull camera metadata for photo detail pages