About The Project

Immich RTK Query is a fully type-safe API client for Immich, the open-source photo and video management platform. This package provides auto-generated TypeScript types and React Query hooks for all Immich API endpoints, making it easy to integrate Immich into your React applications with full type safety and excellent developer experience.

Key Features

• 🔒 Fully Type-Safe - Auto-generated TypeScript types from Immich's OpenAPI specification
• ⚡ React Query Hooks - Use useGetAssetsQuery, useUploadAssetMutation, and more
• 🔄 Automatic Caching - Powered by RTK Query for optimal performance
• 📦 Tree-Shakeable - Import only what you need
• 🎯 Always Up-to-Date - Generated from official Immich API specs

Built With

Getting Started

Prerequisites

This package requires the following peer dependencies:

• React 18.0.0 or higher
• React Redux 8.0.0 or higher
• Redux Toolkit 2.11.2 or higher

Installation

Install the package via npm:

npm install immich-rtk-query

Or using yarn:

yarn add immich-rtk-query

Or using pnpm:

pnpm add immich-rtk-query

Usage

1. Configure Your Redux Store

First, add the Immich API to your Redux store:

import { configureStore } from '@reduxjs/toolkit'
import { immichApi } from 'immich-rtk-query'

export const store = configureStore({
  reducer: {
    [immichApi.reducerPath]: immichApi.reducer,
  },
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware().concat(immichApi.middleware),
})

2. Configure the Base URL and Authentication

Before using the API, configure it with your Immich instance URL and authentication. Call configureImmichApi before your app starts:

import { configureImmichApi, immichApi } from 'immich-rtk-query'

// Configure the API with your Immich instance
configureImmichApi({
  baseUrl: 'https://your-immich-instance.com/api',
  prepareHeaders: (headers, { getState }) => {
    // Add authentication
    const apiKey = localStorage.getItem('immich-api-key')
    if (apiKey) {
      headers.set('x-api-key', apiKey)
    }
    return headers
  },
  // All fetchBaseQuery options are supported:
  credentials: 'include', // Include cookies
  // mode: 'cors',
  // cache: 'no-cache',
  // etc.
})

// Then set up your store
export const store = configureStore({
  reducer: {
    [immichApi.reducerPath]: immichApi.reducer,
  },
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware().concat(immichApi.middleware),
})

Note:

• Call configureImmichApi once, before rendering your app
• All fetchBaseQuery options are supported (baseUrl, prepareHeaders, credentials, headers, mode, cache, etc.)
• The base API uses baseUrl: '/' by default if not configured

3. Use the Hooks in Your Components

import {
  useGetAllAssetsQuery,
  useUploadAssetMutation,
  useCreateAlbumMutation,
} from 'immich-rtk-query'

function MyPhotosComponent() {
  // Fetch assets with automatic caching and refetching
  const { data: assets, isLoading, error } = useGetAllAssetsQuery({
    take: 100,
  })

  // Mutations for creating/updating data
  const [uploadAsset, { isLoading: isUploading }] = useUploadAssetMutation()
  const [createAlbum] = useCreateAlbumMutation()

  const handleUpload = async (file: File) => {
    try {
      await uploadAsset({
        assetData: file,
        // ... other upload parameters
      }).unwrap()
    } catch (err) {
      console.error('Upload failed:', err)
    }
  }

  if (isLoading) return <div>Loading...</div>
  if (error) return <div>Error loading assets</div>

  return (
    <div>
      {assets?.map((asset) => (
        <img key={asset.id} src={asset.thumbnailUrl} alt={asset.originalFileName} />
      ))}
    </div>
  )
}

4. Advanced: Custom Endpoints

You can inject custom endpoints into the API:

import { immichApi } from 'immich-rtk-query'

const extendedApi = immichApi.injectEndpoints({
  endpoints: (builder) => ({
    getMyCustomData: builder.query({
      query: () => '/custom-endpoint',
    }),
  }),
})

export const { useGetMyCustomDataQuery } = extendedApi

Roadmap

• [x] Auto-generate TypeScript types from Immich OpenAPI spec
• [x] Generate React Query hooks
• [x] Support for all Immich API endpoints
• [x] Add usage examples repository
• [ ] Add integration tests
• [ ] Support for custom transformers
• [ ] Automatic updates when Immich API changes

See the open issues for a full list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Development

To regenerate the API types from the latest Immich OpenAPI specification:

npm run generate

To build the package:

npm run build

License

This is free and unencumbered software released into the public domain. See LICENSE for more information.

Contact

Othneil Drew - LinkedIn

Project Link: https://github.com/othneildrew/immich-rtk-query

Acknowledgments

• Immich - The amazing open-source photo management platform
• RTK Query - Powerful data fetching and caching
• RTK Query Codegen - OpenAPI code generation for RTK Query
• Best-README-Template - README template