App Setup

Overview

The app (apps/app) is a Vite + React 19 SPA using TanStack Router. It runs in two modes:

Hono mode (default): connects to the API server for data, with a local IndexedDB fallback for domains not yet migrated
Local mode: fully local IndexedDB for development without any backend

Prerequisites

Node.js 24+
pnpm 10+
Clerk account (for authentication)
API server running (for Hono mode)

Environment Variables

Create apps/app/.env from the example:

cp apps/app/.env.example apps/app/.env

Variable	Required	Default	Description
`VITE_CLERK_PUBLISHABLE_KEY`	Yes	—	Clerk publishable key
`VITE_API_BASE_URL`	Production builds	`${appUrl("api")}/api` in development and test	BFF API base URL
`VITE_API_MOCK`	No	—	Set to `true` to embed the scenario runner (dev and test bundles only)
`VITE_FLAGS`	No	—	Feature flags (comma-separated or `*`)
`VITE_LOG_LEVEL`	No	`debug` (dev) / `warn` (prod)	Log level override
`VITE_WEB_BASE_URL`	Production builds	`appUrl("web")` in development and test	Landing site URL
`VITE_PLAYER_BASE_URL`	Production builds	`appUrl("player")` in development and test	Player app base URL
`VITE_LEARN_URL`	Production builds	`appUrl("learn")` in development and test	Learner space, linked from the screen an account signed up there gets instead of the app
`VITE_E2E`	No	—	Set to `true` for E2E test mode

API modes

Real API (default)

The app always talks to the API server at VITE_API_BASE_URL, with Clerk for authentication.

With VITE_API_MOCK=true (set in .env.development and .env.test), opening the app with ?__scenario=<id> replaces the API with MSW handlers and Clerk with a simulated actor, for one scenario at a time. No API server is needed. Without __scenario, the app uses the real API. The deployed build contains neither the runner nor MSW. See the app README for the catalogue and the DevBar menu.

Running

# Start the app (Vite dev server)
pnpm dev:app

# Or from the app directory
cd apps/app && pnpm dev

The app runs on http://localhost:5173.

Full stack development

For Hono mode, start both the API and app:

# Terminal 1: Start local Supabase + migrate + seed
cd packages/database && pnpm db:local && pnpm db:reset

# Terminal 2: Start the API server
pnpm dev:api

# Terminal 3: Start the app
pnpm dev:app