Set up the workspace
When you need it
You have just cloned the repository, or made a new Git worktree, and want a running local setup and a change that passes the same gates as CI. Each step ends with a check, so you know it worked before you move on.
The repository is an Nx and Bun workspace with three kinds of project:
apps/holds everything deployable:app,admin,marketing,docs,router,mcp,desktop,developerandbackend. The system overview shows how they connect.packages/holds shared code:libraries,emails,post-body,letter-shapes,castandpage-widget.tooling/holds development-only tools.
Before you start
- Bun
1.4.4, thepackageManagerin the rootpackage.json. Nx, TypeScript, Biome, Wrangler and the Supabase CLI are pinned in the workspace, so nothing else is needed globally. Use Bun for installs andbunxto run tools, notnpm. - Docker Desktop, to run the local Supabase stack.
- Deno, only to run the unit tests for Edge Functions (Supabase's serverless functions, in
apps/backend/supabase/functions). - Rust 1.77.2 or later (the
rust-versioninapps/desktop/Cargo.toml) and the system libraries Tauri lists for your OS, only if you work onapps/desktop.
Steps
1. Install and turn on the hooks
Run these from the repository root, once per clone:
bun install --frozen-lockfile
bunx lefthook install
git config blame.ignoreRevsFile .git-blame-ignore-revsThe workspace has one bun.lock, and installs run only at the root. A new Git worktree shares no dependencies with the clone it came from, so run the same install in every new worktree.
bunx lefthook install turns on the Git hooks:
Pre-commit runs
ultracite fix(Ultracite, the workspace's Biome-based formatter and linter) on staged files and typechecks what you touched.Pre-push runs:
check(lint) on what you changed,boundaries(the import rules, step 5), and the tests related to the files you changed (see Related tests);content-guard, which flags app, marketing and email copy that reads as machine-written or machine-translated;class-guard, which rejects Tailwind class strings built with template literals (build them withcn()).
A green push is not a green PR: the pull request's
Checksjob (.github/workflows/ci.yaml; a PR merges only when it passes) runs the full typecheck, lint and test suites.The push warns, without blocking, when your branch conflicts with the last fetched
origin/main, and refuses a push tomain, so work on a branch.
Done when bunx nx show projects lists every project, from @hobenakicoffee/app to @hobenakicoffee/mcp, and bunx lefthook install finished without an error.
2. Fill in the environment
Copy apps/<project>/.env.example to apps/<project>/.env.local for the project you work on (for example apps/app/.env.example) and fill it in. .env.local is untracked and Bun loads it by itself. Commit placeholders only, never a real value.
Done when git status does not list apps/<project>/.env.local: Git ignores the file, so you cannot commit a secret by mistake.
3. Start the local backend
One Nx target starts the local Supabase stack, plus Docker stand-ins for Upstash (Redis) and the SSLCommerz dev gateway (the Bangladeshi payment gateway):
bunx nx run @hobenakicoffee/backend:devRepeating the command is safe. Run the Supabase CLI as bunx supabase ... from apps/backend, so you get the pinned version.
The Full stack is the one local Supabase stack on this machine. Only the worktree holding the Stack lease may use it, and dev checks the lease first. From apps/backend, bun run db:lease shows who holds it, and bun run db:lease acquire takes it when it is free or its holder has been gone or silent for 30 minutes.
Backend tests do not use the Full stack: each worktree gets its own Headless database. Read apps/backend/AGENTS.md before touching apps/backend/supabase/. The backend overview explains the schema, Edge Functions and tests.
Done when the command returns without an error.
4. Run an app
Projects share these targets: dev, build, test, check, typecheck, boundaries and deploy. Run them through Nx; bunx nx show project @hobenakicoffee/<name> lists one project's targets.
bunx nx dev @hobenakicoffee/app # web app for Creators and Supporters (React, served at /app)
bunx nx dev @hobenakicoffee/admin # Manager dashboard
bunx nx dev @hobenakicoffee/marketing # public site (Astro)
bunx nx dev @hobenakicoffee/docs # public guides for Creators and Supporters (Astro, served at /docs)
bunx nx dev @hobenakicoffee/router # Cloudflare Worker that sends hobenakicoffee.com requests to the other Workers
bunx nx dev @hobenakicoffee/mcp # Worker that AI tools connect to over MCP (Model Context Protocol)
bunx nx dev @hobenakicoffee/developer # this documentation site (VitePress)bunx nx dev @hobenakicoffee/desktop starts the backend and then Tauri (the Rust framework that wraps the web app in a desktop window).
Done when the dev server prints a local URL that loads in the browser.
5. Check your work
Write or update tests in the same change as any behavior change. A change is done when typecheck, check and the tests all pass:
bunx nx affected -t check typecheck test --base=origin/main
bun run boundaries
bunx nx run @hobenakicoffee/backend:check:project # backend files agree: schema load list, documented commands, RPC grant inventorycheck is the linter (ultracite check); there is no lint target. Pass --base=origin/main to nx affected: this workspace commits straight to main, so the default comparison is empty and affected runs nothing.
bun run boundaries enforces the import rules: deployable apps import shared packages only, shared packages import nothing from apps/, and nothing imports apps/backend. Shared packages such as packages/libraries are workspace packages ("@hobenakicoffee/libraries": "workspace:*") whose exports point at TypeScript source; see Libraries.
Done when every command exits with status 0.
Undo
- Stop the local backend with
bunx nx run @hobenakicoffee/backend:stop. - Stop a dev server with Ctrl+C.
- Remove the hooks with
bunx lefthook uninstall.
Hosted environments
No step here touches production or staging. deploy targets do: leave them to the release process (Deploy to production). To see what a change would deploy, run bunx nx show projects --affected --with-target deploy --files=<paths>; --dry-run is not a safe flag for Nx deploy targets. Anything that reaches a hosted environment needs the project owner's yes first, every time.
Related
- System overview: every app and how they connect.
- Glossary: the product's words.
- The root
AGENTS.mdand theAGENTS.mdbeside each project hold the rules for that code.