Development environment

Prerequisites

• Node.js ≥ 22
• pnpm — this repo is pnpm-only. npm and yarn are blocked via the engines field and engine-strict, so they fail.
• Docker is optional (only needed if you want to validate migrations against a throwaway Postgres locally).

Install & run

pnpm install
cp .env.example .env     # set your Supabase parent project ref + access token

pnpm dev                 # app + docs concurrently → http://localhost:3000 / :4321
pnpm dev:app             # just the app
pnpm dev:docs            # just these docs

To work against your git branch’s own Supabase branch, run database and app commands through the wrapper (see Branching):

./scripts/supa db push   # migrate THIS branch's Supabase branch
./scripts/supa pnpm dev  # run the app pointed at THIS branch's Supabase branch

Repo layout

apps/app    TanStack Start application (Router + Query, React 19)
apps/docs   this Astro Starlight site
packages/   shared internal packages (added as they emerge)
supabase/   schema migrations (app + network) and config
scripts/    operational scripts (supa: branch-aware Supabase wrapper)

Everyday commands

Command	What it does
pnpm check	Biome lint + format check (the CI gate)
pnpm format	Biome auto-format
pnpm typecheck	TypeScript across workspaces
pnpm build	Build app + docs
pnpm test (from apps/app)	Server-function security-boundary tests — needs live Supabase env, so run via ./scripts/supa pnpm test on a feature branch
pnpm db:migrate	scripts/supa db push — migrate this git branch’s Supabase branch (refuses protected branches)
pnpm db:new <name>	Create a new migration

Conventions

Lint/format is Biome (one config at the repo root — no ESLint/Prettier). All @tanstack/* and visualisation dependencies are exact-pinned for supply-chain safety; don’t loosen them to ranges. See Architecture decisions for the why.