Getting Started

Prerequisites

Tool	Version	Notes
Node.js	>= 20	Recommended: use `nvm` or `fnm`
pnpm	10.23.0	`corepack enable` will install the correct version
Supabase CLI	latest	Required for DB and E2E tests
Docker	latest	Required by Supabase CLI for local development

Initial Setup

# Clone the repo
git clone <repo-url> circle-v2
cd circle-v2

# Install dependencies
pnpm install

Environment Variables

Create .env files in the appropriate locations. There is no checked-in .env.example, so use the table below as a reference.

`apps/web/.env`

Variable	Description	Example
`NEXT_PUBLIC_APP_URL`	Public URL of the web app	`http://localhost:3000`
`LEGACY_APP_URL`	URL of the legacy app (CORS origin)	`http://localhost:3001`
`NEXT_PUBLIC_TRPC_URL`	tRPC endpoint (defaults to `/api/trpc`)	`/api/trpc`
`NEXT_PUBLIC_DISABLE_REACT_QUERY_DEVTOOLS`	Disable RQ devtools	`false`
`DATABASE_URL`	PostgreSQL connection string	`postgresql://postgres:postgres@127.0.0.1:54322/postgres`
`SUPABASE_URL`	Supabase project URL	`http://127.0.0.1:54321`
`SUPABASE_ANON_KEY`	Supabase anonymous key	(from `supabase status`)
`SUPABASE_SERVICE_ROLE_KEY`	Supabase service role key	(from `supabase status`)
`SUPABASE_AUTH_EXTERNAL_GOOGLE_CLIENT_ID`	Google OAuth client ID	(optional for local dev)
`SUPABASE_AUTH_EXTERNAL_GOOGLE_SECRET`	Google OAuth secret	(optional for local dev)

`packages/db/.env.test`

Used by DB integration tests. Typically points to the local Supabase instance.

`packages/e2e-web/.env.test`

Used by Playwright E2E tests. Loaded automatically in CI; source manually for local runs.

Common Commands

All commands are run from the repo root unless noted otherwise.

Command	Description
`pnpm dev`	Start the web app and all dependencies in dev mode
`pnpm build`	Build all packages and apps
`pnpm test`	Run all unit tests via Turbo
`pnpm test:watch`	Run tests in watch mode
`pnpm lint`	Run Biome + ESLint across the monorepo
`pnpm format`	Auto-fix formatting via `biome check --write`
`pnpm check-types`	Type-check all packages and apps

Storybook

pnpm --filter storybook dev    # Start Storybook on port 6006
pnpm --filter storybook build  # Build static Storybook

Database

pnpm --filter @repo/db generate   # Generate a new Drizzle migration
pnpm --filter @repo/db migrate    # Apply pending migrations
pnpm --filter @repo/db test       # Run DB integration tests (requires local Supabase)

E2E Tests

# Start the E2E Supabase instance
pnpm --filter @repo/e2e-web test:supabase-start

# Run Playwright tests (starts the web server automatically)
START_WEB_SERVER=true pnpm --filter @repo/e2e-web test:e2e

Turborepo

All pnpm scripts at the root delegate to turbo run. Turbo handles:

Dependency ordering: build runs ^build (dependencies first).
Caching: Build and test outputs are cached; env vars are included in cache keys.
Parallelism: Independent tasks run in parallel automatically.

See turbo.json for the full task configuration.

Next: Repository Structure