Appearance
Developer Onboarding
STALE COMMANDS — npm run dev does not exist at the repo root (2026-08-08)
The command table and env-var names below are the retired Vite SPA's. Concretely wrong today: there is no root dev, build or preview (the root is a workspace orchestrator and each app owns its own dev server), npm test is not Vitest, and the client reads EXPO_PUBLIC_*, not VITE_SUPABASE_*.
| You want | Actually run |
|---|---|
| The merchant app | cd apps/mobile && npm start (Metro), or npm run android / npm run ios |
| The web app | cd apps/web && npm run dev |
| Tests | npm run test at the root — jest-expo + node --test via workspaces |
| Gates | npm run lint · type-check · check:readmes · check:parity · check:sql · check:design · check:docs · e2e:quick |
| This portal | npm run docs:dev |
The prerequisites section below is still accurate and still mandatory. The authoritative command list is CLAUDE.md § Commands.
Day-one setup to get the app, the backend, and this portal running locally.
Prerequisites (verify & bootstrap before any build/deploy step)
Do not proceed with a step whose tool is absent. Install/enable whatever is missing per-OS.
| Tool | Why | Notes |
|---|---|---|
git + GitHub CLI (gh) | source + PRs | |
| Node 22 + npm | app build/test | .nvmrc pins 22; use nvm/nvm-windows. |
| Deno | Edge Function tests / deno check | npm run test:ef. |
| Supabase CLI | local DB, migrations, EF deploy | npx supabase. |
| Docker Desktop | local Supabase stack, E2E stack, local SonarQube | |
| wrangler | Cloudflare Pages | a devDependency. |
| Playwright browsers | E2E (planned) | npx playwright install --with-deps chromium. |
Install missing tools via winget/choco/scoop (Windows), Homebrew (macOS), or official installers.
First run
bash
nvm use # Node 22
npm install
npm run dev # app on http://localhost:3000.env.test (committed, dummy values only) supplies VITE_SUPABASE_URL / VITE_SUPABASE_ANON_KEY so the Supabase client doesn't throw under test. For a real dev run you need the DEV project's VITE_SUPABASE_* in .env.local — see Environment Strategy.
Everyday commands
| Command | Purpose |
|---|---|
npm run dev | Vite dev server (port 3000). |
npm run build | Generates public/llms.txt, then vite build → dist/. |
npm run type-check | tsc --noEmit (project-wide). |
npm run lint | ESLint --quiet (project-wide). |
npm run lint:fix | ESLint --fix, scoped to digital-menu. |
npm test | Full Vitest suite. |
npm run test:watch | Vitest watch mode. |
npm run test:coverage | Coverage (70% lines / 80% functions). |
npm run test:ef | Deno edge-function tests. |
npm run functions:deploy -- --project-ref <ref> | Deploy Edge Functions (explicit ref required). |
Run a single test file: npx vitest run path/to/file.test.tsx.
Planned scripts (added by later phases):
test:db(pgTAP),e2e:*(Playwright).
Running this portal locally
The docs are a separate, internal-only VitePress app under documentation/portal/. They are never part of the production build.
bash
# one-time:
npm --prefix documentation/portal install
# from repo root:
npm run docs:gen # regenerate auto-generated reference pages (EF index)
npm run docs:dev # serve the portal locally
npm run docs:build # build static HTML (offline-viewable)Mental model in 30 seconds
Where to read next
- Data Access Strategy — the one hard rule.
- Tier System — how the codebase is organised.
- Backend / Edge Functions — the EF model + shared kit.
- Coding Standards — what reviewers enforce.
- Adding a Feature — the end-to-end recipe.