Repository navigation
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.
| 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.
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"]
-
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. - 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.
-
Branch from
develop, and targetdevelopwith the pull request.mainholds releases only. -
CI must be green. That means the Woodpecker pipeline, plus
execution-planeandpackage-smokeon three OSes when execution-plane paths change. See Deployment and Releases. - A merge into
developdeploys staging.
- Bun 1.4.0 (
packageManagerin the root package.json) - Node 24 or later. The repository's
enginesis>=24. The published CLI needs Node 20 or later. - Docker, for the local PostgreSQL. Only the API needs it.
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 modeUse Bun as the package manager. Never use npm install or yarn. Versions are pinned exactly (bunfig.toml: exact = true).
| 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.
-
Test with Vitest under Node: each package's
testscript runstscand thenvitest run. Never usebun 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
- 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/apiimports Prisma, throughPrismaService. The web app reaches the API over HTTP. Schema changes go throughprisma migrate devwith a descriptive name. Never edit an applied migration. -
packages/corehas no Node APIs and depends only on zod (ADR-0001). - API inputs are DTOs with
class-validatordecorators. - A bug fix comes with the test that would have caught it.
- Each new environment variable goes into the matching
.env.examplein 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.
| 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 |
- The repository's
enginesis>=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/fixtureis 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.
DemoFlow · Issues · Decision records · Specs · MIT licensed
Start
Features
- Scenarios
- Recording Scenarios
- Running Demos
- Rendering and Effects
- Secrets and Masking
- Run Artifacts
- MCP Server
Operate
Reference