Feature Flag Platform

Self-hosted feature-flag system.

Documentation

Start with the Documentation Index for guides on:

• SDK Usage: Node.js, Web/Browser, React
• E2E Testing: Overview, Stack, Node Tests, Web Tests, Admin UI Tests
• API Reference: Complete SDK API
• Architecture: AWS topology, deploy runbook, getting started

Local Development

Prerequisites: Node 23.6+ (the build relies on Node's default-on TypeScript type stripping), pnpm 9, Docker.

pnpm install
docker compose up -d
cp apps/admin-api/.env.example apps/admin-api/.env
./dev.sh                     # starts admin-api, resolver, admin-ui together

The admin API listens on http://localhost:4000, the resolver on http://localhost:4001, and the admin UI on http://localhost:5173.

Seeded sample data

When NODE_ENV=development and the database is empty, admin-api seeds a default workspace on first boot with three stages (Production, Staging, Development), three subject types (User, Account, Device), four audiences with members and rules, and a handful of subjects so the admin UI has something to render. The seed is idempotent — it skips entirely once the workspace exists, so editing flags through the UI is safe. To get a fresh seed, drop the dev database and restart:

docker compose down -v && docker compose up -d

The seed lives at apps/admin-api/src/db/seed.ts (seedDevSampleData).

Git pre-commit hook

pnpm install runs the repo's prepare script, which points core.hooksPath at .githooks/. The committed pre-commit hook runs pnpm format:check, pnpm lint, and pnpm typecheck before each commit. If any step fails, fix the underlying issue (or run pnpm fix for auto-fixable formatting/lint problems) and re-stage — don't bypass with --no-verify.

Testing

Run end-to-end tests against a live resolver. Each suite manages its own e2e-stack (Postgres + Redis via docker compose, plus admin-api and resolver as child processes), so you can run them independently:

# Node.js SDK tests (Vitest)
pnpm --filter @ffp/e2e-node test

# Browser SDK tests (Playwright)
pnpm --filter @ffp/e2e-web test

# Admin UI browser tests (Playwright)
pnpm --filter @ffp/admin-ui-e2e test

To skip the auto-managed lifecycle and reuse a long-running stack, start it in a separate terminal first — both runners detect a healthy stack and reuse it when CI isn't set:

pnpm --filter @ffp/e2e-stack start

See E2E Testing Overview for detailed instructions.

Useful Scripts

pnpm lint              # Check code style
pnpm lint:fix          # Auto-fix lint problems where possible
pnpm format            # Apply prettier formatting
pnpm fix               # format + lint:fix (covers everything pre-commit checks)
pnpm typecheck         # TypeScript validation
pnpm test              # Run unit + integration tests (excludes e2e-node/e2e-web)
pnpm build             # Build all packages
pnpm graph:deps        # Generate dependency graph

Dependency Graph

Generate the workspace dependency graph as a Mermaid diagram:

pnpm graph:deps

This writes the graph to docs/dependency-graph.mmd.

You can also provide a custom output path:

node scripts/draw-dependency-graph.mjs docs/dependency-graph.mmd

Viewing the Graph

The generated file is Mermaid source, so you need a Mermaid-compatible viewer.

Options:

• Open docs/dependency-graph.mmd in the Mermaid Live Editor by pasting in the file contents.
• Use the official VS Code Mermaid Chart extension if you want to work with .mmd files directly: https://marketplace.visualstudio.com/items?itemName=MermaidChart.vscode-mermaid-chart
• If you prefer Markdown previews, copy the diagram into a Markdown file inside a fenced mermaid block and use the Markdown Preview Mermaid Support extension: https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid