Skip to content

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, developer and backend. The system overview shows how they connect.
  • packages/ holds shared code: libraries, emails, post-body, letter-shapes, cast and page-widget.
  • tooling/ holds development-only tools.

Before you start ​

  • Bun 1.4.4, the packageManager in the root package.json. Nx, TypeScript, Biome, Wrangler and the Supabase CLI are pinned in the workspace, so nothing else is needed globally. Use Bun for installs and bunx to run tools, not npm.
  • 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-version in apps/desktop/Cargo.toml) and the system libraries Tauri lists for your OS, only if you work on apps/desktop.

Steps ​

1. Install and turn on the hooks ​

Run these from the repository root, once per clone:

bash
bun install --frozen-lockfile
bunx lefthook install
git config blame.ignoreRevsFile .git-blame-ignore-revs

The 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 with cn()).

    A green push is not a green PR: the pull request's Checks job (.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 to main, 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):

bash
bunx nx run @hobenakicoffee/backend:dev

Repeating 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.

bash
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:

bash
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 inventory

check 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.