immich-rtk-query

[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![License: Unlicense][license-shield]][license-url]

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.

$3

* 🔒 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

(back to top)

$3

[![React][React.js]][React-url]
[![Redux][Redux]][Redux-url]
[![TypeScript][TypeScript]][TypeScript-url]

(back to top)

Getting Started

$3

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

$3

Install the package via npm:

``bash
npm install immich-rtk-query
`

Or using yarn:

`bash
yarn add immich-rtk-query
`

Or using pnpm:

`bash
pnpm add immich-rtk-query
`

(back to top)

Usage

$3

First, add the Immich API to your Redux store:

`typescript
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),
})
`

$3

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

`typescript
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

`typescript
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

if (error) return

Error loading assets

return (

{assets?.map((asset) => (

))}

)
}

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

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

export const { useGetMyCustomDataQuery } = extendedApi
`

(back to top)

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).

(back to top)

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

$3

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

`bash
npm run generate
`

To build the package:

`bash
npm run build
`

(back to top)

License

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

(back to top)

Contact

Othneil Drew - LinkedIn

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

(back to top)

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

(back to top)

[contributors-shield]: https://img.shields.io/github/contributors/othneildrew/immich-rtk-query.svg?style=for-the-badge
[contributors-url]: https://github.com/othneildrew/immich-rtk-query/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/othneildrew/immich-rtk-query.svg?style=for-the-badge
[forks-url]: https://github.com/othneildrew/immich-rtk-query/network/members
[stars-shield]: https://img.shields.io/github/stars/othneildrew/immich-rtk-query.svg?style=for-the-badge
[stars-url]: https://github.com/othneildrew/immich-rtk-query/stargazers
[issues-shield]: https://img.shields.io/github/issues/othneildrew/immich-rtk-query.svg?style=for-the-badge
[issues-url]: https://github.com/othneildrew/immich-rtk-query/issues
[license-shield]: https://img.shields.io/github/license/othneildrew/immich-rtk-query.svg?style=for-the-badge
[license-url]: https://github.com/othneildrew/immich-rtk-query/blob/master/LICENSE
[React.js]: https://img.shields.io/badge/React-20232A?style=for-the-badge&logo=react&logoColor=61DAFB
[React-url]: https://reactjs.org/
[Redux]: https://img.shields.io/badge/Redux-593D88?style=for-the-badge&logo=redux&logoColor=white
[Redux-url]: https://redux.js.org/
[TypeScript]: https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white
[TypeScript-url]: https://www.typescriptlang.org/