Local development
Run the Next.js application on your host against a local PostgreSQL database.
Edit on GitHubYou can run the application on your host while PostgreSQL runs locally or in the repository's development compose stack. The Docker quickstart runs both application and database in containers. This page covers a host-run Next.js process, which provides hot reload.
Prerequisites and configuration
Use Node 20 from .nvmrc. package.json accepts Node >=20 <23 and pnpm >=10. Install the package manager version named in package.json, then install dependencies:
pnpm installThe package prepare script activates .githooks/ as the local Git hooks path.
Create a root .env for your own development settings without committing it. Set DATABASE_URL to a writable PostgreSQL database, NEXTAUTH_SECRET for sessions and NEXTAUTH_URL to the address where you run the application. Configure provider client values if you plan to test GitHub or Google sign-in. The local compose database is tea_dev with user tea_user on host port 5432. The separate postgres-test service is on host port 5433 for integration tests. Avoid pointing tests at your development database.
Initialise the database
Start PostgreSQL, generate the Prisma client, apply the checked-in SQL migrations and seed sample data if wanted:
docker compose -f docker-compose.local.yml up -d postgres
pnpm exec prisma generate
pnpm exec prisma migrate deploy
pnpm exec tsx prisma/seed/dev-seed.tsCreate an empty development database before applying migrations. The repository does not use prisma migrate dev to generate migrations. prisma.config.ts and the migration directory are the places to inspect if generation or deployment fails.
For sample cases and accounts, run prisma/seed/dev-seed.ts after migrations. It first reads prisma/seed/.credentials if present, then falls back to SEED_USER_PASSWORD; a leftover credentials file takes priority. Do not commit that file. The seed skips reseeding when it finds the existing chris account. If you do not want sample data, you can run the application against an empty migrated database and register an account through the browser.
Run and check the application
The development server uses the current dev script, next dev, and serves the application at http://localhost:3000 with the default Next.js port. Use the package scripts for routine work:
pnpm dev
pnpm lint
pnpm typecheck
pnpm test:unit
pnpm test:integration
pnpm buildpnpm format applies formatting changes. pnpm test:coverage:check is the coverage run used by CI. The integration suite needs its dedicated PostgreSQL test service and setup.
Outside CI, pnpm test:e2e runs prisma migrate reset --force and reseeds whatever database DATABASE_URL names. Run it only against a disposable database, after checking that URL.
The code style guide gives the intended use of each check.
Troubleshooting
If the server cannot connect to PostgreSQL, check the host, port and database named by DATABASE_URL, then confirm the database is running and migrated. The application uses DB_POOL_TIMEOUT_MS to limit how long a request waits for a connection, with a default of 5000 ms. If sign-in fails, check the provider settings and session URL for the route you are using. Read the application log rather than assuming that a build-time warning proves a runtime connection failure.