Local development

This page takes a fresh machine to a running Hub in about fifteen minutes. It assumes Node 22+ (the CI matrix tests 22 and 24), Docker for Postgres, and a checkout of the repository.

Get the database running

The repo expects PostgreSQL on port 5433 — deliberately not the default 5432, so a host Postgres doesn't collide with it:

docker run -d --name youngo-pg \
  -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=youngo_dev \
  -p 5433:5432 postgres:16

Configure the environment

Create .env.local (gitignored — never commit it):

DATABASE_URL=postgres://postgres:postgres@localhost:5433/youngo_dev
PAYLOAD_SECRET=<any long random string>
APP_BASE_URL=http://localhost:3000
# Optional: SMTP_*, VAPID_* for mail/push, SENTRY_DSN for error reporting

Generate VAPID keys if you want push locally: node scripts/setup/generate-vapid-keys.mjs.

Install, migrate, seed

npm install
npm run migrate     # applies the full migration chain to the empty DB
npm run seed        # provisions baseline structure — no fabricated members
npm run dev         # http://localhost:3000

npm run seed creates the scaffolding a fresh deployment needs (policy structure, baseline records) — it does not invent people. The repository carries no member data; test accounts are created by the test harness or provisioned against a specific environment. See Data and migrations for why.

If npm run dev misbehaves after dependency or generated-type changes, npm run devsafe clears .next first.

Verify the setup

npm run lint        # eslint — 0 errors expected; warnings are known debt
npm run build       # production build; also runs type generation

The test suites

Two suites, both needing the dev server and the migrated database:

npm run test:int    # vitest — integration specs against the running app
npm run test:e2e    # playwright — browser flows

Tests provision their own accounts and content, so they can run against a dev database without leaving residue you care about. Watch out for the login rate limiter: after several failed or rapid test runs it will start refusing logins — restarting npm run dev clears the in-memory budget. Testing covers the suites in depth.

Regenerating types and the import map

Payload generates TypeScript types from the collections:

npm run generate:types       # refresh src/payload-types.ts after schema changes
npm run generate:importmap   # refresh the Payload import map

CI checks that committed types match the schema — if you changed a collection and forgot generate:types, the drift check will catch it.

Everyday commands

Command	Purpose
npm run dev / devsafe	Dev server / dev server after clearing .next
npm run migrate	Apply pending migrations
npm run seed	Provision baseline structure
npm run lint	ESLint across the repo
npm run format / format:check	Prettier write / check
npm run build	Production build + typecheck
npm run test:int / test:e2e	Integration / browser suites
npm run sync:mcp	Write project MCP servers into local agent configs

Agent tooling (optional)

If you work with AI coding agents, two extras wire them into the project:

npx skills experimental_install   # restore .agents/skills into your agent
# add HINDSIGHT_API_KEY to .env.local (ask a maintainer for the bank key)
npm run sync:mcp                  # writes memory + hub-content into agent configs

sync:mcp is idempotent — re-run it after pulling changes to scripts/agent/sync-mcp.mjs. Its outputs are gitignored, so never hand-edit or commit them. Agent tools covers the setup in detail.

Common setup failures

• ECONNREFUSED 5433 — the Docker container isn't running: docker start youngo-pg.
• Migrations fail partway — check DATABASE_URL points at the database you think it does; the chain is designed to run top-to-bottom on an empty schema.
• PAYLOAD_SECRET missing — Payload refuses to start without it.
• Ports 3000/18080 taken — a previous dev server or the MCP smoke server is still alive.