Type-safe RTK Query API client for Immich photo management platform
npm install 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]
A type-safe RTK Query API client for the Immich photo management platform
Explore the docs ยป
Report Bug
ยท
Request Feature
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.
* ๐ 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
[![React][React.js]][React-url]
[![Redux][Redux]][Redux-url]
[![TypeScript][TypeScript]][TypeScript-url]
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
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
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),
})
`
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 appfetchBaseQuery
- All options are supported (baseUrl, prepareHeaders, credentials, headers, mode, cache, etc.)baseUrl: '/'
- The base API uses by default if not configured
`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
return (
$3
You can inject custom endpoints into the API:
`typescript
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$3
To regenerate the API types from the latest Immich OpenAPI specification:
`bash
npm run generate
`To build the package:
`bash
npm run build
`
License
This is free and unencumbered software released into the public domain. See
LICENSE` for more information.Othneil Drew - LinkedIn
Project Link: https://github.com/othneildrew/immich-rtk-query
* 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
[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/