Skip to content

Contributing

Archi edited this page Oct 18, 2026 · 1 revision

Contributing

DemoFlow is a Bun and Turborepo monorepo. This page covers how to set it up, which tool tests which part, and how work is specified and merged.

Overview

Path What it is Runtime / tests
packages/core Contracts as zod schemas: scenario, project config, timeline, run result. Zod is its only dependency Node, Vitest
packages/engine Playwright execution, readiness, origin guard, masks, sync mark, capture Node, Vitest
packages/renderer Render plan and FFmpeg compositor, fonts, visual baselines Node, Vitest
apps/cli The demoflow CLI: run, validate, setup, record, mcp, and npm staging Node, Vitest
apps/fixture Vite + React test app on port 3680, with scenarios in demoflow/ test target
apps/api NestJS 11 API with Prisma 7 (PostgreSQL), port 8370. Scaffolding today Jest
apps/web Next.js 16 web app, port 3670. Scaffolding today —
packages/shared Glue code shared by apps/api and apps/web —

The execution plane is core, engine, renderer and apps/cli. It runs on Node and must work on Linux, macOS and Windows. See Architecture.

How it works

flowchart LR
  I["Issue"] --> S["Spec in docs/specs (docs PR)"]
  S --> B["Branch from develop"]
  B --> P["Pull request into develop"]
  P --> C["CI: Woodpecker + GitHub Actions (3 OSes)"]
  C --> M["Merge into develop → staging"]
Loading
  1. Work starts as an issue with a spec. A spec lives at docs/specs/<issue>-<slug>.md, one per issue, and lands in its own docs pull request before the code. Keep each issue to one slice. Specs are indexed in docs/specs/README.md.
  2. Decisions are ADRs in docs/adr/, one per decision. An accepted ADR is never rewritten; a later one supersedes it. Read the index before you change a boundary.
  3. Branch from develop, and target develop with the pull request. main holds releases only.
  4. CI must be green. That means the Woodpecker pipeline, plus execution-plane and package-smoke on three OSes when execution-plane paths change. See Deployment and Releases.
  5. A merge into develop deploys staging.

Using it

Prerequisites

  • Bun 1.4.0 (packageManager in the root package.json)
  • Node 24 or later. The repository's engines is >=24. The published CLI needs Node 20 or later.
  • Docker, for the local PostgreSQL. Only the API needs it.

Setup

bun install
cp docker/.env.example docker/.env        # set POSTGRES_PASSWORD
cp apps/api/.env.example apps/api/.env    # DATABASE_URL must use the same password
bun run db:setup                          # start PostgreSQL on :5470, migrate, seed
bun run start:dev                         # api + web in watch mode

Use Bun as the package manager. Never use npm install or yarn. Versions are pinned exactly (bunfig.toml: exact = true).

Commands

Command What it does
bun run build Build everything (turbo, cached)
bun run check Biome lint, format and import order, with no writes
bun run format Biome format, with writes
bun run lint Biome lint in every workspace
bun run test Every workspace's tests: Vitest for the execution plane, Jest for the API
bun run test:release Tests of the release scripts (node --test)
bun run db:migrate prisma migrate dev: create and apply a migration
bun run db:generate Regenerate the Prisma client
bun run db:studio Prisma Studio

Narrow a run with turbo filters. For example, bun run test --filter=@demoflow/engine.

Working on the execution plane

  • Test with Vitest under Node: each package's test script runs tsc and then vitest run. Never use bun test.

  • Try a change against the fixture app:

    cd apps/fixture && bun run dev            # http://localhost:3680
    bun run build --filter=demoflow
    node apps/cli/dist/main.js run apps/fixture/demoflow/customers.demo.json
  • Changed the look of the video? Regenerate the baseline PNGs in packages/renderer/test/baselines, and commit them in the same pull request so the review sees the before and after:

    bun run --filter @demoflow/renderer test:update-baselines

Rules

  • Biome is the only linter and formatter: single quotes, trailing commas, 2-space indent. Do not add ESLint or Prettier.
  • TypeScript is strict everywhere. Never use any.
  • Only apps/api imports Prisma, through PrismaService. The web app reaches the API over HTTP. Schema changes go through prisma migrate dev with a descriptive name. Never edit an applied migration.
  • packages/core has no Node APIs and depends only on zod (ADR-0001).
  • API inputs are DTOs with class-validator decorators.
  • A bug fix comes with the test that would have caught it.
  • Each new environment variable goes into the matching .env.example in the same change. Never commit a password.
  • Docs, specs, ADRs, code comments and commit messages are in English.
  • The UI uses Glass UI (@andrewbehma/glass-ui) primitives and tokens before custom components.

Settings

File Purpose
docker/.env.example POSTGRES_PASSWORD for the local database. Copy it to docker/.env, which is git-ignored
apps/api/.env.example PORT, APP_ENV, API_URL, WEB_URL, DATABASE_URL
apps/web/.env.example Web app variables
CLAUDE.md The project's conventions, used by people and agents

Limits / what it never does

  • The repository's engines is >=24. The published CLI needs only Node 20, but development needs Node 24.
  • The Woodpecker agents are Linux only. macOS and Windows behaviour is checked only by the GitHub workflows.
  • apps/fixture is a test target, not a product surface.

Note

Inside the monorepo, npx demoflow can resolve to the private workspace package instead of the npm one. To try the published package, run it from a directory outside the repository.

See also

Clone this wiki locally