Local Development

Use this contributor path when you are changing Breakdown, self-hosting it, or testing repo-local integration scaffolding. Hosted MCP and REST users should start with Getting Started instead.

Install

Breakdown uses the pnpm version pinned in package.json. Enable Corepack, then install dependencies from the repo root.

corepack enable
pnpm install

Configure Environment Variables

Secrets are file-local only. Use .env.local.example as the variable inventory — copy it to .env.local and fill in values locally. No Doppler setup is required for ordinary development or for Breakdown Local.

For the standard local workflow, copy the example file, validate, and run:

cp .env.local.example .env.local
# edit .env.local with your Clerk/Supabase/Google Drive values
pnpm secrets:check
pnpm dev

Hosted-legacy note (self-host only): operators self-hosting the SaaS app under src/ may sync env from their own secrets manager (Doppler, Vault, 1Password, or Vercel dashboard) via standard env vars. That hosted-legacy path is documented in Operator Deployment — Appendix A and is not required for Breakdown Local. See Roadmap and ADR 0004.

Run The App

Open http://localhost:3000 after the dev server starts. Use the sign-in flow to reach the dashboard and graph editor.

Useful Checks

Before sending changes for review, run the focused checks for the work you touched.

pnpm lint
pnpm typecheck
pnpm test
pnpm build

Package Security

Dependency resolution uses pnpm with a seven-day release cooldown. Run the high-severity audit before dependency changes.

pnpm run audit:high

See Operator Deployment for the fuller self-hosting and production setup model.