Development environment

Prerequisites

• Node.js 22 or later.
• pnpm. The repo is pnpm-only. npm and yarn refuse to install.
• Docker is optional, for checking migrations against a throwaway Postgres (see Migrations).

Set up

pnpm install
cp .env.example .env

.env lives at the repo root; the app reads it from there. Fill in:

• VITE_SUPABASE_URL, VITE_SUPABASE_PUBLISHABLE_KEY and SUPABASE_SECRET_KEY for the shared dev project
• SUPABASE_ACCESS_TOKEN (your personal token), SUPABASE_PROJECT_REF and SUPABASE_DB_PASSWORD, used by scripts/supa.

The rest are optional. See Environment variables.

Run

pnpm dev        # app on http://localhost:3000 and docs on http://localhost:4321
pnpm dev:app    # app only
pnpm dev:docs   # docs only

pnpm dev first runs scripts/supa-first-run.sh, which migrates a brand-new database (see First-run setup). pnpm dev:app skips it.

The shared dev database

There is no per-branch database

Every developer, on every git branch, uses the same Supabase project, movement-mapping-dev. The Supabase free plan doesn’t support branching.

• ./scripts/supa db push applies migrations to that shared project straight away, from any branch, including main.
• The integration tests create real users and data there.
• ./scripts/supa pnpm dev runs the app against it. Plain pnpm dev does too, as long as .env points at it.

Tell the team before pushing a schema change.

scripts/supa wraps the Supabase CLI. It loads .env, links to SUPABASE_PROJECT_REF, and runs the command you give it. The scripts for real per-branch databases (scripts/supa-create-branch.sh, supa-get-branch-ref.sh) are kept, unused, for when the project moves to a paid plan.

Commands

Command	Does
pnpm check	Biome lint and format check (CI runs this)
pnpm format	Biome auto-format
pnpm lint	Biome lint only
pnpm typecheck	TypeScript across the workspaces
pnpm test	All workspaces’ tests, unit and integration (see Testing)
pnpm build, build:app, build:docs	Build everything, the app, or the docs
./scripts/supa db push (or pnpm db:migrate)	Apply migrations to the shared dev project
pnpm db:new <name>	Create a new migration file
./scripts/supa pnpm api-key:create --org <uuid> --user <email>	Mint a public API key, printed once
pnpm release	Draft the next GitHub release (see Deployment)

Repo layout

apps/app        TanStack Start app (React 19)
  src/routes/            file-based routes; _authed/* need a session; api/* are server routes
  src/server/functions/  server functions, grouped by area
  src/server/middleware/ authMiddleware and orgMiddleware
  src/server/lib/        shared server logic (authz, import/export, maintenance, …)
  src/server/api/v1/     public HTTP API handlers
  src/graph/             pure graph logic (weighting, communities, betweenness)
  src/components/        UI: map-editor, map-visualiser, map-table, map-workspace, home, app-shell
  src/types/graph.ts     the GraphData type shared by Edit and Visualise
apps/docs       this site (Astro Starlight)
packages/       bluesky_to_graph, csv-to-graphml
supabase/       migrations and email templates
scripts/        supa (Supabase wrapper), supa-*.sh, release
render.yaml     Render blueprint

apps/app/README.md has more on the app’s own structure.