Local setup in five commands

The web app and api run as plain Node dev servers; the only service you need from Docker is Postgres. Everything here is the same flow the repository README documents and the build logs verified.

Prerequisites

Node 22+ and npm 10+ — enforced by the engines field in the root package.json.
Docker with Compose — used here only to run Postgres 16. Any Postgres 16 you can reach works if you adjust DATABASE_URL.

Setup

1. Copy the environment template. The root .env feeds docker compose:

shell

cp .env.example .env

2. Start Postgres 16 (the compose db service publishes localhost:5432):

shell

docker compose up -d db

3. Create apps/api/.env for the api process and Prisma (this file is git-ignored). Minimum contents:

apps/api/.env

DATABASE_URL=postgresql://pacfully:pacfully@localhost:5432/pacfully
JWT_SECRET=change-me-to-a-long-random-string

4. Install dependencies and create the tables:

shell

npm install
npm run db:migrate   # prisma migrate dev — applies the init migration

5. Run both dev servers, one per terminal:

shell

npm run dev:api   # Fastify (tsx watch) on http://localhost:4000
npm run dev:web   # Next.js on http://localhost:3000

Verify it works

Health check

curl http://localhost:4000/health
# {"status":"ok"}

End-to-end: register and call a protected route

curl -X POST http://localhost:4000/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"correct horse battery","name":"You"}'
# → 201 { "user": {…}, "token": "<jwt>" }   (the token is valid for 7 days)

curl http://localhost:4000/auth/me \
  -H "Authorization: Bearer <jwt>"
# → 200 { "user": { "id": "…", "email": "you@example.com", … } }

Open http://localhost:3000 for the product. The editor works without any account — try http://localhost:3000/editor.

Useful scripts while you work

Command	What it does
npm run typecheck	tsc --noEmit across all workspaces — the bar every change must clear
npm run db:generate	Regenerate the Prisma client after schema changes
npm run db:migrate	Create and apply a new dev migration
npm run db:studio	Open Prisma Studio against your local database
npm run build	Build shared → api (prisma generate + tsc) → web (next build)
npm run clean	Remove .next and dist output directories

Where each .env file is read

The root .env is read by docker compose for variable interpolation. The api process and Prisma read apps/api/.env. The web app needs no api configuration: with NEXT_PUBLIC_API_URL unset it calls the same-origin /api path, which the dev server rewrites to http://localhost:4000. Set the variable only to reach an api on another origin — it is inlined at build/dev-server start, so restart dev:web after changing it.

Continue to Docker deployment →