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_LEGACY_APP_URL`	Legacy app URL exposed to the browser, used to validate postMessage origins from legacy iframes	`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)

Vercel Project Link (required for Queues)

Vercel Queues use OIDC authentication that requires the Vercel CLI to be linked to the project. Run this once from apps/web/:

pnpm pull-vercel-env

This links the Vercel project, pulls the development environment, and adds VERCEL_OIDC_TOKEN to your .env. Without it, any code that enqueues a job (performLater) will fail locally with Failed to get OIDC token for local development.

When to re-run: The OIDC token rotates periodically. If you see the OIDC error again, re-run pnpm pull-vercel-env to refresh it.

`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