Local Setup

Prerequisites

Tool	Version	Notes
Node.js	≥ 24	`nvm install && nvm use` (reads `.nvmrc`) or `brew install node`. Install nvm: `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh \| bash`
pnpm	≥ 10	`npm install -g pnpm`
Docker	any	Docker Desktop or Rancher Desktop (free, works on Apple Silicon)
Trivy	any	`brew install trivy` - required for pre-commit security scan on dependency changes. See aquasecurity/trivy
Gitleaks	any	`brew install gitleaks` - scans staged files for secrets on every commit. Pre-commit blocks if not installed. See gitleaks/gitleaks

Install dependencies

pnpm install

Environment variables

Copy the template and fill in your secrets:

cp .env.local_template .env.local

The key variables to set before the app will run:

Variable	What it is	Where to get it
`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`	Clerk public key	Clerk dashboard → API Keys
`CLERK_SECRET_KEY`	Clerk secret key	Clerk dashboard → API Keys
`DATABASE_URL`	Postgres connection string	Pre-filled for local Docker (`postgresql://postgres:postgres@localhost:5432/app`)

The remaining variables (NEXT_PUBLIC_CLERK_SIGN_IN_URL etc.) are pre-filled in the template and work as-is for local dev.

All environment variables are validated at build time using T3 Env. If a required variable is missing or malformed, the build fails immediately with a clear error message rather than silently producing a broken deployment.

See Authentication Setup for Clerk-specific steps and Database for DB setup.

Start the database

docker compose up -d

Then run migrations (safe to re-run, skips already-applied ones):

pnpm db:migrate

Optionally seed demo data:

pnpm db:seed   # resets example_items to 3 fixed rows

Dev servers

The repo contains two apps: the Next.js app (:3000) and the docs site (:3001).

Command	What starts
`pnpm dev`	App only - `http://localhost:3000`
`pnpm dev:docs`	Docs only - `http://localhost:3001`
`pnpm dev:all`	Both concurrently, colour-coded output

For most work you just need pnpm dev.

Useful commands

pnpm test          # unit tests (Vitest, single pass)
pnpm test:watch    # watch mode
pnpm typecheck     # tsc --noEmit
pnpm lint          # ESLint
pnpm e2e           # Playwright end-to-end (needs pnpm dev running)
pnpm build         # production build

Prefer the Dev Container if you want a zero-setup environment - it pre-installs everything and wires the database automatically.