Skip to content

Prepare an isolated development environment

Local development uses a repository-owned Supabase stack and synthetic fixtures. Shared functional checks use the separately declared application environment. Preparing one does not require resetting, seeding or borrowing credentials from the other.

The current repository pins Supabase CLI 2.116.0; use its Make targets rather than an unrelated globally installed CLI. Use Node.js 24, Python 3.11 or later and Docker as declared in the development guide. CI’s Python image is a separate declared execution input.

Read the repository working agreement, current status, architecture and development guide. Check open PRs and git worktree list; reuse the worktree for this task. New worktrees belong under ~/worktrees/, with one writer. Do not continue a merged branch.

Each worktree owns its dependencies. Do not symlink node_modules from another checkout. Create the backend virtual environment using the development guide and install its runtime/development requirements. For frontend dependencies use the documented npm ci --legacy-peer-deps. The handbook has a separate dependency root and uses npm ci under docs/system.

  1. Select the intended branch and inspect changes before installing or starting anything. Record which local services and ports are already in use.
  2. Install worktree dependencies with the documented versions. Keep runtime credentials out of the checkout. Before hermetic backend tests, check that runtime dotenv files and symlinks are absent and clear provider inputs. Preserve the committed synthetic frontend test configuration.
  3. Run make start from the repository root. The repository CLI applies its migrations to its own local stack. Use make status locally to obtain that stack’s settings; it can print local keys, so do not paste its output into evidence.
  4. If the task needs a fresh synthetic dataset, run make dev-data. This performs reset and seed; it destroys local data. It is not required just to build documentation and must never target the shared environment or a restored customer dataset.
  5. Start the API and frontend using the daily commands. The documented API port is 8110; frontend Vite uses 3000 with a strict port. Use a deliberate TOOLORA_DEV_PORT override and matching CORS/preflight settings if necessary. Keep local Auth origins consistently on 127.0.0.1.
  6. Run make preflight and the focused checks for the changed surface. If schema changes exist, create a forward migration with make migration, then regenerate types with make types.
Observation Expected result Does not establish
Local stack startup Repository migrations apply to the owned local project Shared schema parity or recovered data
Synthetic seed Reproducible fixture companies and actors Completeness of historical imports
Preflight Declared dependencies, ports and service prerequisites are usable A successful business journey
Hermetic backend suite Synthetic/local inputs without runtime secret loading Provider acceptance
Documentation build Local HTML, search and assets Application publication

A busy strict frontend port is a failure to resolve, not permission to let Vite silently choose another port. A dotenv symlink is still runtime configuration and must not be followed by a hermetic suite. Missing Docker health or a migration mismatch requires diagnosis before resetting anything.

Database seed, reset and automated checks obtain their target from the stack’s status, not an ambient database URL. Upgrade rehearsal refuses unrelated host/port/database values. Do not broaden that routing interface to make a test easier to invoke.

For a synthetic project edit, verify the intended actor, company and saved result through the actual changed path. A successful preflight only makes that check possible. Test levels explains the evidence boundaries.

Shared browser checks follow the saved-session procedure and persistent Vi Målar identities only when the changed flow requires them. Environment constraints include real Fortnox effects: never test final attest/export/send or an approval that queues payroll in Vi Målar. Configuration identities and schema release describe the separate authorized runtime procedures.