Skip to main content

Local Development Setup

This guide covers setting up the Traces development environment.

Prerequisites​

  • Node.js 20 or later
  • pnpm (npm install -g pnpm)
  • Git

There is no local Docker setup. Traces uses managed cloud services (Supabase Postgres, Upstash Redis, Cloudflare R2, AWS Secrets Manager, Clerk). For local development you point your .env files at a development project on each service (most commonly a dedicated Supabase project and an Upstash database).

Quick Start​

# Clone the repository
git clone https://github.com/traces/traces.git
cd traces

# Install dependencies
pnpm install

# Set up environment variables (see below)
#   apps/web/.env       and   packages/database/.env
#   apps/worker/.env

# Generate the Prisma client
pnpm --filter @traces/database db:generate

# Run database migrations against your dev database
pnpm --filter @traces/database db:migrate:dev

# (optional) Seed connectors / roadmap data
pnpm --filter @traces/database db:seed

# Start all development servers (web + worker + docs, in parallel)
pnpm dev

The web app reads its env from apps/web/.env; Prisma (migrations) reads from packages/database/.env. Both need the database connection. The worker reads from apps/worker/.env.

Environment Variables​

The database connection uses two URLs (Supabase): a pooled URL at runtime and a direct URL for migrations/DDL.

# Database (Supabase) — apps/web/.env and packages/database/.env
DATABASE_URL="postgresql://...pooler.supabase.com:6543/postgres?pgbouncer=true"
DIRECT_URL="postgresql://...db.<ref>.supabase.co:5432/postgres"

# Redis (Upstash)
UPSTASH_REDIS_REST_URL="https://..."
UPSTASH_REDIS_REST_TOKEN="..."

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_..."
CLERK_SECRET_KEY="sk_test_..."

# AWS Secrets Manager
AWS_ACCESS_KEY_ID="..."
AWS_SECRET_ACCESS_KEY="..."
AWS_REGION="us-east-1"

# Cloudflare R2
R2_ACCESS_KEY_ID="..."
R2_SECRET_ACCESS_KEY="..."
R2_BUCKET="traces-dev"
R2_ENDPOINT="https://..."

# Anthropic (for connector generation, docs discovery, suggestions)
ANTHROPIC_API_KEY="sk-ant-..."

Project Structure​

traces/
├── apps/
│   ├── web/          # Next.js 14 (App Router) frontend + API routes
│   ├── worker/       # pg-boss background job processor
│   └── docs/         # Documentation (Docusaurus)
├── packages/
│   ├── database/     # Prisma schema, migrations, generated client
│   ├── types/        # Shared TypeScript types
│   ├── queue/        # pg-boss queue definitions (Postgres-backed)
│   ├── utils/        # Shared utilities
│   └── docs-scraper/ # Puppeteer-based scraping helpers
└── docs/             # Markdown documentation source (design docs, CODEBASE_MAP)

Development Commands​

These are the root-level scripts defined in package.json:

CommandDescription
pnpm devStart all development servers in parallel (web + worker + docs)
pnpm dev:webStart only the web application (:3000)
pnpm dev:workerStart only the worker
pnpm dev:docsStart only the Docusaurus docs site
pnpm buildBuild all packages recursively
pnpm testRun all tests recursively
pnpm lintRun linting recursively
pnpm typecheckType-check the web app (tsc --noEmit)

Database commands live in packages/database and are run with --filter:

CommandDescription
pnpm --filter @traces/database db:generateGenerate the Prisma client
pnpm --filter @traces/database db:migrate:devCreate/apply a dev migration
pnpm --filter @traces/database db:migrate:deployApply migrations (production)
pnpm --filter @traces/database db:migrate:statusShow migration status
pnpm --filter @traces/database db:seedSeed connectors / roadmap data
pnpm --filter @traces/database db:studioOpen Prisma Studio

Running Tests​

Tests run with Vitest per package.

# Run all tests
pnpm test

# Run a single package's tests
pnpm --filter @traces/web test
pnpm --filter @traces/worker test

# Watch / coverage (per package)
pnpm --filter @traces/web test:watch
pnpm --filter @traces/web test:coverage

# End-to-end (Playwright, web app)
pnpm --filter @traces/web test:e2e

Troubleshooting​

Database Connection Issues​

The database is a managed Supabase project, not a local container. Verify your DATABASE_URL (pooled, :6543) and DIRECT_URL (direct, :5432) point at the right project, then check migration status:

pnpm --filter @traces/database db:migrate:status

Migrations and DDL must use DIRECT_URL; the runtime connection uses the pooled DATABASE_URL.

Port Conflicts​

If port 3000 is in use:

# Find the process using the port
lsof -i :3000

# Kill process (replace PID)
kill -9 <PID>

Node Modules Issues​

# Clean and reinstall
rm -rf node_modules
rm -rf apps/*/node_modules
rm -rf packages/*/node_modules
pnpm install

Next Steps​