This document describes the automated code generation systems in Immich. Code generation is used extensively across the codebase to maintain type safety, reduce boilerplate, and ensure consistency between server and client implementations.
Immich uses multiple code generation systems:
build_runner.All code generation is managed through mise tasks defined in the root and platform-specific configurations mise.toml42-89
The OpenAPI specification serves as the single source of truth for all API contracts. Two separate client SDKs are generated from this specification: a TypeScript SDK for web/CLI and a Dart SDK for mobile. The server-side enums and schemas are often mapped directly to the OpenAPI specification using Zod metadata, such as AssetTypeSchema mapping to AssetTypeEnum server/src/enum.ts45
OpenAPI Generation Flow
Sources: server/src/enum.ts45-46 mobile/openapi/lib/api.dart2-11 mise.toml56-74
The TypeScript SDK is generated using the oazapfts tool and resides in the packages/sdk workspace. It provides a complete set of types and a fetch-based client for interacting with the Immich API.
| Aspect | Details |
|---|---|
| Generator | oazapfts mise.toml23 |
| Output | packages/sdk/src/fetch-client.ts mise.toml58 |
| Package Name | @immich/sdk package.json121 |
| Mise Task | open-api-typescript mise.toml56-61 |
The generation task utilizes --optimistic, --argumentStyle=object, and --useEnumType flags to ensure the generated code matches Immich's coding standards mise.toml58
Sources: mise.toml23-61 pnpm-lock.yaml120-122
The mobile application uses a Dart client generated with the OpenAPI Generator. This client includes an ApiClient class mobile/openapi/lib/api_client.dart13 that handles authentication and API invocation.
Key Components:
ApiKeyAuth, OAuth, and HttpBearerAuth mobile/openapi/lib/api.dart27-31open-api-dart task executes generate-dart-sdk.sh mise.toml63-73The generated code is organized into a library openapi.api mobile/openapi/lib/api.dart11 and uses part files to manage the large number of DTOs and API classes mobile/openapi/lib/api.dart34-70
Sources: mobile/openapi/lib/api.dart11-70 mobile/openapi/lib/api_client.dart13-145 mise.toml63-73
The mobile application relies heavily on build_runner for various generation tasks, as seen in its dependencies mobile/pubspec.lock156-163
Immich Mobile uses auto_route for navigation and drift for the local database. These require a generation step to produce the routing table and database access objects.
auto_route_generator mobile/pubspec.lock60-67For high-performance or platform-specific features, Immich uses Pigeon to generate type-safe bridges between Dart and native code (Swift/Kotlin). Examples include:
BackgroundWorkerLockApi are bridged to native implementations mobile/lib/main.dart24 mobile/lib/main.dart53.g.swift files generated for Connectivity, PermissionApi, LocalImages, and RemoteImages mobile/ios/Runner.xcodeproj/project.pbxproj21-35Mobile Generation Entities
Sources: mobile/pubspec.lock60-67 mobile/lib/main.dart24-53 mobile/ios/Runner.xcodeproj/project.pbxproj19-37
Immich uses easy_localization and codegen_loader for managing internationalization mobile/lib/main.dart8-21
codegen_loader.g.dart is generated to provide a structured way to access these translations in a type-safe manner mobile/lib/main.dart20Sources: mobile/lib/main.dart8-21 mobile/lib/main.dart54-56
The root mise.toml provides the following primary tasks for developers to synchronize generated code:
| Task | Description |
|---|---|
open-api | Orchestrates the full API generation (TS and Dart) mise.toml75-84 |
open-api-typescript | Generates the TS SDK using oazapfts mise.toml56-61 |
open-api-dart | Generates the Mobile SDK using openapi-generator-cli mise.toml63-73 |
sql | Synchronizes the SQL schema for the server mise.toml86-89 |
plugins | Builds the plugin SDKs and core packages mise.toml50-54 |
Sources: mise.toml50-89
Refresh this wiki
This wiki was recently refreshed. Please wait 5 days to refresh again.