Development environment

Run the backend and web apps locally, execute tests, database scripts, and deployment commands.

3 min read

Warning

Use this page once prerequisites (see Quick start) and backend / web configurations are in place. The sections below assume you run commands from the repository root unless noted.

Backend local development

You can work from the monorepo root (using scripts defined in the root package.json that delegate to backend/) or change into backend/ and run the same scripts locally. Pick one style and stick with it.

Cron jobs (expired refresh tokens)

Some backend features rely on scheduled jobs backed by pg_cron on Supabase. For example, the `user-auth` module periodically removes expired rows from `public.refresh_tokens` (every Saturday at **3:30 AM GMT**). If you deploy to Supabase Cloud and cron is not enabled, those jobs won’t run even if migrations are pushed. See Database & migrations for pg_cron setup and migration-push commands.

Start the API — runs the backend dev server (tsx watch on app.ts with NODE_ENV=development).

pnpm backend:dev

Tests — Jest unit, integration, and e2e suites for the backend package.

pnpm backend:test:unit
pnpm backend:test:integration
pnpm backend:test:e2e

Aggregate SQL migrations — builds the combined migration output used by the repo (see backend/scripts/aggregate_migrations_all.mjs).

pnpm backend:db:aggregate-migrations-all

Generate TypeScript types from local Supabase — writes generated table types for the backend (local supabase CLI).

pnpm backend:db:typegen

Production-linked Supabase — there is no root alias for these; call the backend package from the root with pnpm --filter:

pnpm --filter ./backend db:production:typegen
pnpm --filter ./backend db:production:push-db

Change directory — run the following from backend/ after installing dependencies from the repo root (pnpm install at the root).

cd backend

Start the API — same behavior as pnpm backend:dev from the root.

pnpm dev

Tests — Jest unit, integration, and e2e suites.

pnpm test:unit
pnpm test:integration
pnpm test:e2e

Aggregate SQL migrations

pnpm db:aggregate-migrations-all

Generate TypeScript types from local Supabase — equivalent to pnpm backend:db:typegen at the root.

pnpm db:local:typegen

Production-linked Supabase — generate types against the linked remote project and push schema changes.

pnpm db:production:typegen
pnpm db:production:push-db

Frontend local development

Warning

Run the backend API before the web app so local pages can call your API. In a separate terminal, start the API from the repository root with pnpm backend:dev (or cd backend then pnpm dev), then use the commands below for the frontend.

You can work from the monorepo root (using web:* and pnpm --filter ./web … scripts) or change into web/ and run package scripts there.

Start the SvelteKit app — runs icon generation then the Vite dev server (pnpm web:dev in the root package.json).

pnpm web:dev

Tests — Vitest unit tests for the web package.

pnpm --filter ./web test:unit

Preview production build — serves the last vite build output locally (build from web/ first if you need a fresh bundle).

pnpm --filter ./web preview

Change directory — run the following from web/ after installing dependencies from the repo root.

cd web

Start the app — same behavior as pnpm web:dev from the root.

pnpm dev

Tests

pnpm test:unit

Preview production build

pnpm preview

Deployment

These commands are run from the repository root (they are defined in the root package.json and delegate into backend/ or web/).

Backend JS bundle — runs tsup in backend/ to produce the bundled API output used for deploys.

pnpm --filter ./backend build:js

Deploy backend to Vercel — invokes the Vercel CLI with backend/ as the working directory.

pnpm vercel:deploy:backend

Deploy web to Vercel — invokes the Vercel CLI with web/ as the working directory.

pnpm vercel:deploy:web

Next Steps

Project architecture

Monorepo layout, key directories, and how the stack fits together

Vercel

Vercel-focused deployment notes for this project