Appearance
Getting started
Prerequisites
- Bun 1.4+ (the repo pins
packageManagerinpackage.json) - A Cloudflare account, only for running the API with D1/R2/Queues (
alchemy dev). The web UI and docs run without it.
First run
bash
bun install # also generates src/env.ts for each app via Varlock
cp apps/web/.env.example apps/web/.env
cp apps/server/.env.example apps/server/.env
bun run dev:web # web app, http://localhost:8001
bun run dev:docs # this site, http://localhost:3010The web login page has a Development preview panel (dev builds only) that lets you open any role's space without a database or sign-in. It is removed from production bundles.
Running the API
The API is a Cloudflare Worker provisioned by Alchemy:
bash
cd packages/infra && bunx alchemy profile edit # once: choose your Cloudflare profile
bun run dev # alchemy dev: server on :8000, web on :8001BETTER_AUTH_SECRET must be at least 32 characters. Generate one with openssl rand -base64 48. Secrets never go in the repo; see Environment.
Everyday commands
| Command | What it does |
|---|---|
bun run dev:web / dev:server / dev:docs | One app in development mode |
bun run check-types | Type-check every project (Nx) |
bun run test | Run tests (domain package uses bun test) |
bun run check | Oxlint + Oxfmt (writes formatting) |
bun run lint / format:check | CI-style checks, no writes |
bun run db:generate | Generate a Drizzle migration from schema changes |
bun run db:check | Fail if an applied migration was edited or deleted |
bun run ui:add <slug> | Vendor a beUI component |
bun run ui:status | Show local edits and upstream beUI updates |
bun run build | Build everything |
Where to start reading
- Architecture: the repo map and request flow.
- Conventions: the rules code review checks.
- Versioning: how change is managed. Read this before touching a rule, a price, a template or a table.
- Roadmap: what step 1 still needs.