Development

Prerequisites

• Docker and Docker Compose v2+
• Node.js 22+
• pnpm (or enable via corepack enable)

Development Setup

Librariarr uses Docker Compose for development to provide a PostgreSQL database and hot-reloading.

1. Clone the repository

   git clone https://github.com/ahembree/librariarr.git
   cd librariarr

2. Create a .env file

   Copy the example and fill in the required values:

   cp .env.example .env

3. Start the dev environment

   pnpm docker:dev

   This builds the dev container, starts PostgreSQL, runs migrations, and starts the Next.js dev server with Turbopack hot-reloading.

4. Open the app

   Navigate to http://localhost:3000

Development Commands

Docker

Command	Description
pnpm docker:dev	Start dev environment (foreground)
pnpm docker:dev:detach	Start dev environment (background)
pnpm docker:dev:down	Stop dev environment
pnpm docker:dev:rebuild	Rebuild containers from scratch
pnpm docker:dev:clean	Stop containers and delete DB volume
pnpm docker:dev:logs	Tail dev container logs

Database

Command	Description
pnpm docker:dev:db:push	Push schema changes (fast iteration, no migration files)
pnpm docker:dev:db:migrate	Run Prisma migrations
pnpm docker:dev:db:studio	Open Prisma Studio (DB browser)
pnpm docker:dev:db:reset	Reset DB completely

Mock Data

Populate the database with fictional media data for testing or taking screenshots without exposing personal data.

Command	Description
pnpm docker:dev:seed	Seed the dev database with mock data

Note

The seed script creates a demo user with username demo and password demo. It also creates 3 media servers (Plex, Jellyfin, Emby) with overlapping libraries to demonstrate multi-server dedup. The script is idempotent — running it again replaces the previous seed data.

Build & Lint

Command	Description
pnpm build	Next.js production build
pnpm lint	ESLint
pnpm exec prisma generate	Regenerate Prisma client (needed after schema changes when DB isn’t available)

Testing

Tests use Vitest with a real PostgreSQL test database (librariarr_test), auto-created by the global setup.

Note

The Docker dev database must be running for integration tests. Start it with pnpm docker:dev or pnpm docker:dev:detach before running tests.

Test Commands

Command	Description
pnpm test	Run full test suite
pnpm test:watch	Watch mode
pnpm test:unit	Unit tests only (no DB needed)
pnpm test:integration	Integration tests only (requires DB)
pnpm test:coverage	Run with coverage report
pnpm exec vitest run tests/path/to/file.test.ts	Run a single test file

Test Structure

• tests/unit/ — Pure logic tests (rules engine, filters, sync detection, formatting, caching, validation schemas)
• tests/integration/ — API route handler tests against a real database with mocked external services

Tech Stack

Technology	Version	Purpose
Next.js	16	App Router framework
React	19	UI library
TypeScript	5	Type safety
PostgreSQL	18	Database
Prisma	7	ORM
Tailwind CSS	v4	Styling (OKLCH color model)
shadcn/ui	—	Component library (new-york style)
Vitest	4	Testing framework

Git Conventions

• Pre-commit hook: Runs pnpm exec eslint --quiet via Husky
• Commit format: Conventional Commits enforced by commitlint
  • feat: add new feature
  • fix(auth): handle expired tokens
  • docs: update installation guide
  • refactor: simplify rule evaluation

Project Structure

src/
├── app/                    # Next.js App Router
│   ├── (authenticated)/    # Protected pages (auth enforced by layout)
│   ├── api/                # API routes
│   ├── login/              # Login page
│   └── onboarding/         # First-time setup
├── components/
│   └── ui/                 # shadcn/ui primitives
├── hooks/                  # Custom React hooks
└── lib/
    ├── auth/               # Session management
    ├── arr/                # Sonarr/Radarr/Lidarr clients
    ├── backup/             # Backup & restore service
    ├── cache/              # In-memory cache
    ├── dedup/              # Multi-server deduplication
    ├── filters/            # Media filter utilities
    ├── jobs/               # Graphile Worker background job queue + scheduler
    ├── plex/               # Plex OAuth and API client
    ├── rules/              # Lifecycle rule engine
    ├── sync/               # Media sync engine
    └── validation.ts       # Zod schemas for API validation