Black Flag Convex Template

Reusable Convex app baseline for non-CMS projects

The template is now a neutral React + Convex starter with optional Clerk auth, a pre-wired admin surface, deterministic tests, and CI gates that run before a project has a live Convex deployment.

npm run check passes 36 Vitest tests 4 Playwright smokes format:check enforced 0 audit vulnerabilities No CMS dependency

What changed

Convex core

Added users, roles, admin audit events, health checks, and auth helpers around requireIdentity, requireUser, and requireAdmin.

Clerk sync

Added Convex HTTP handling for signed Clerk lifecycle webhooks at /webhooks/clerk, including create, update, delete, and role metadata handling.

Admin surface

Added a compact /admin route for user visibility and audit events. It is ready for project-specific admin modules without assuming CMS.

Fresh clone

Added a lockfile and tracked convex/_generated stubs so npm ci and npm run check work before attaching a live Convex project.

Local quality

Added declared Prettier tooling, lint-staged coverage for source and config files, a Husky-backed check gate, and docs tests that keep deploy secrets aligned.

Not in scope

  • CMS routes, content-type registries, and CMS MCP tooling.
  • Fake seed data or sample domain objects that leak into projects.
  • Live external API tests in the default PR gate.
  • Project-specific dashboards before a project defines its real jobs.

Testing matrix

Layer Command Purpose
Quality gate npm run check Lint, format check, typecheck, Vitest, template validation, and production build.
Convex runtime npm run test:convex Runs convex-test in edge-runtime with schema validation.
Frontend unit npm run test:frontend Runs utility/component tests in jsdom.
Coverage npm run test:coverage Currently passes at 83.6% statements and 70.73% branches.
Browser smoke npm run test:e2e Desktop and mobile smoke paths before Convex is configured.
Install gate npm ci Verifies the GitHub Actions dependency path.
Deploy env npm run deploy:validate Validates Convex, Clerk, webhook, deploy key, and Cloudflare Pages secrets without printing secret values.

Convex contract

  • users.ensureCurrent provisions Clerk users.
  • @blackflag.design accounts auto-promote to admin.
  • users.list and users.setRole require admin.
  • users.upsertFromClerk and users.deleteByClerkId sync Clerk webhook state.
  • admin.overview returns user counts and recent audit events.
  • health.check stays public and deployment-safe.

Project adoption flow

CloneInstall with npm ci or npm install.
AttachRun npx convex dev and set env.
AuthEnable Clerk when admin access is needed.
BuildAdd real project tables and functions.
GateKeep npm run check and e2e green.