Development Guide

Relevant source files

• .github/mise.toml
• deployment/mise.toml
• docs/docs/api.md
• docs/docs/developer/database-migrations.md
• docs/docs/developer/devcontainers.md
• docs/docs/developer/pr-checklist.md
• docs/docs/developer/setup.md
• docs/docs/developer/testing.md
• docs/mise.lock
• docs/mise.toml
• e2e/mise.toml
• mise.lock
• mise.toml
• mobile/android/fastlane/metadata/android/en-US/changelogs/8.txt
• mobile/ios/.gitignore
• mobile/ios/Signing.xcconfig
• package.json
• packages/e2e-auth-server/package.json
• packages/plugin-sdk/package.json
• packages/scripts/package.json
• pnpm-lock.yaml
• server/mise.toml
• web/README.md
• web/mise.toml

This guide provides an overview of the development environment, tooling, and workflows for contributing to Immich. It covers the monorepo structure, task runner system, common development tasks, and the relationship between different build tools. For specific topics, see Development Environment Setup for local setup instructions, Monorepo Tooling for pnpm workspace details, Build System for Docker builds, CI/CD Pipeline for GitHub Actions workflows, Testing for test execution, and Code Generation for auto-generated code.

Development Stack

Immich uses a polyglot development stack organized as a monorepo. The primary technologies and tools are:

Technology	Usage	Version
Node.js	JavaScript runtime for server, web, CLI	24.15.0
pnpm	Package manager with workspace support	11.13.1
TypeScript	Primary language for server and web	6.0.2
Flutter	Mobile application framework	Managed via mise
Python	Machine learning service	3.x
mise	Task runner and tool version manager	Latest
Docker	Containerization and deployment	Latest

The monorepo is managed using pnpm workspaces, with mise providing a unified task interface across all packages.

Sources: mise.toml18-19 pnpm-lock.yaml104 package.json11 mise.toml27

Monorepo Package Structure

The monorepo contains several core packages and supporting directories. TypeScript packages use the workspace:* protocol to reference local dependencies. The pnpm-lock.yaml file at the root manages all dependencies across packages.

Sources: pnpm-lock.yaml115-122 mise.toml3-15 packages/plugin-sdk/package.json33

Task Runner System (mise)

Immich uses mise as a unified task runner. The root mise.toml defines a monorepo configuration with task inheritance and tool version management.

The monorepo configuration at mise.toml1-15 enables task discovery across packages. Root-level tasks often orchestrate complex workflows like generating the OpenAPI SDKs or managing Docker environments.

Common Task Patterns

Tasks can be invoked using mise run <task-name> or mise //<package>:<task-name>.

Task	Scope	Purpose
dev	Root	Starts development environment using docker-compose.dev.yml mise.toml91-96
open-api	Root	Syncs server OpenAPI spec and generates TS/Dart SDKs mise.toml75-84
plugins	Root	Installs and builds all plugin-related workspace packages mise.toml50-54
clean	Root	Recursively removes node_modules, dist, and build folders mise.toml172-181
sdk:build	Package	Compiles the @immich/sdk package mise.toml161-163
checklist	Package	Runs all quality checks (lint, test, format) for a specific package docs/docs/developer/pr-checklist.md17-72

Sources: mise.toml42-181 docs/docs/developer/pr-checklist.md1-82

Development Workflow

A typical development workflow involves:

1. Setup: Run mise plugins and mise sdk:build to prepare shared packages mise.toml50-161
2. Development: Use mise dev to start the local stack via Docker Compose with hot-reloading docs/docs/developer/setup.md47-53 mise.toml91
3. OpenAPI: If API changes are made, run mise open-api to update the TypeScript and Dart SDKs mise.toml75
4. Quality: Run unit tests and linting via the package-specific checklist task, such as mise //server:checklist or mise //web:checklist docs/docs/developer/pr-checklist.md17-43
5. Database: Generate migrations when entities change in server/src/infra/src/entities docs/docs/developer/pr-checklist.md79-81

Package-Specific Development

Server and Web

The server and web components are developed in tandem. The server's OpenAPI specification is used by oazapfts to generate the @immich/sdk mise.toml58 which is then consumed by the web application.

Mobile Package

The mobile package uses Flutter and includes extensive code generation tasks:

• mise //mobile:translation - Generates translation files docs/docs/developer/setup.md99-123
• mise //mobile:codegen - Auto-generates files using build_runner docs/docs/developer/pr-checklist.md51

Machine Learning

The machine learning service includes tasks for linting (ruff), type checking (mypy), and unit testing (pytest) docs/docs/developer/pr-checklist.md64-73

Code Quality and CI/CD

Static Analysis

Immich employs strict static analysis:

• TypeScript: ESLint and Prettier are used across the monorepo pnpm-lock.yaml150-161
• Dart: Static analysis via Dart Analyzer and DCM (Dart Code Metrics) docs/docs/developer/pr-checklist.md52 docs/docs/developer/setup.md151-155
• Python: ruff for linting and formatting, mypy for type checking docs/docs/developer/pr-checklist.md66-68

Automated Testing

The test suite includes:

• Unit Tests: Executed via vitest for Node.js packages pnpm-lock.yaml201-203 docs/docs/developer/testing.md7
• E2E Tests: Playwright is used for browser-based end-to-end testing pnpm-lock.yaml123-125 docs/docs/developer/testing.md10-27
• Mobile Tests: Unit tests for the Flutter application docs/docs/developer/pr-checklist.md54

Sources: docs/docs/developer/pr-checklist.md1-82 docs/docs/developer/testing.md1-37

Next Steps

For detailed information on specific development topics:

• Setting up local environment and mise: See Development Environment Setup
• Managing monorepo dependencies and workspaces: See Monorepo Tooling
• Understanding multi-stage Docker builds: See Build System
• Exploring GitHub Actions and release logic: See CI/CD Pipeline
• Running and writing tests: See Testing
• Using OpenAPI and code generation: See Code Generation