Setting up to develop

This page is for changing the code, not merely running it. If you only want the app up and working, use Installing Deckgauge first — come back here once you're editing source.

The three gates a change has to clear before review.

Getting the stack running

Follow Installing Deckgauge for the four setup commands (cp .env.example .env, pnpm install, docker compose up -d, pnpm --filter @deckgauge/db migrate:deploy). For active development, stop the containerized web, api, and worker services first — docker compose stop web api worker — then run pnpm dev from the repo root instead: it runs turbo run dev across the workspace, so apps/web serves on http://localhost:3000 with hot reload and apps/api on http://localhost:3001, while Postgres, Redis, ClickHouse, and Keycloak stay in Docker. Skip the stop step and both the container and pnpm dev fight over the same ports, and one of them fails with EADDRINUSE.

Running tests

Every app and package runs its own tests on Vitest (vitest run), and pnpm test from the root fans out to all of them via DECKGAUGE_TEST_STRICT_INTEGRATION=1 turbo run test --concurrency=1. Each suite provisions its own Postgres on the test stack automatically — start it with docker compose -p deckgauge-test -f docker-compose.test.yml up -d and the first run creates and migrates a database named after your checkout. (packages/db used to be excluded, because its Vitest config loaded the root .env and so pointed at whatever database your app was using rather than a disposable one; it now derives a per-checkout database like the apps do.) The two flags are deliberate: --concurrency=1 keeps packages from writing the same fixture tables at once and from starving a small VM, and strict integration mode makes an integration suite that could not run — because ClickHouse is unreachable, say — fail with a named reason instead of reporting as a skip. Running a single workspace (pnpm --filter @deckgauge/api test) is lenient and skips with the same message. apps/web's vitest.config.ts sets environment: 'jsdom', since most of its tests render React components; apps/api, apps/worker, and packages/shared run in plain Node since they're testing services, SQL builders, and pure functions. Test files are *.test.ts / *.test.tsx, co-located next to the source they cover — there's no separate __tests__ tree to hunt through except a few integration suites. apps/web also has Playwright E2E specs under apps/web/e2e, run separately with pnpm --filter @deckgauge/web test:e2e; Vitest is configured to exclude that directory so a plain test run doesn't try to load it. If you're working from the published open-source snapshot rather than a full clone of the private repo, note that it strips every test file and directory before publishing — *.test.ts(x), __tests__, e2e, and fixtures included — so apps/web/e2e won't be there to reference; add co-located unit/component tests for your change instead.

The gates a change has to pass

1. pnpm lint — ESLint (typescript-eslint recommended rules plus Prettier's conflicting-rule config) across every workspace. Unused variables are an error unless prefixed with _.
2. pnpm build — turbo run build; Turborepo builds each package's dependencies first (dependsOn: ["^build"] in turbo.json), so packages/shared and packages/db build before the apps that import them.
3. pnpm test — the Vitest suite across every workspace (see above). Add tests for new business logic — validators, services, data transforms — before writing the implementation; that's the TDD expectation covered in Code conventions.

Formatting follows the committed .prettierrc: single quotes, 2-space indent, a 100-character print width. Branch from main as feature/<slug> or fix/<slug>, keep the PR small and focused, and sign off commits per the DCO (git commit -s).

Known friction

The one gotcha every new contributor hits: pnpm --filter @deckgauge/db migrate:dev does not work in this repo — it fails with a shadow-database error (Prisma P3006), so its usual "diff my schema and generate a migration for me" flow is unavailable here. When you need a schema change, hand-write the migration SQL yourself under packages/db/prisma/migrations and apply it with pnpm --filter @deckgauge/db migrate:deploy — the same command the install flow uses, and the only one that's supported for this database.

If it looks wrong

Related

• Architecture — what each app and package owns.
• Code conventions — the patterns your PR is expected to follow.
• Adding an intelligence widget — a full worked example that exercises most of this stack.
• Installing Deckgauge — the fresh-clone-to-running-app path.

Last updated 6 September 2026