Appearance
Developer Onboarding
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.