Skip to main content

Local Development

Compass has multiple workable development modes. Pick the lightest mode that supports the feature you are changing.

For first-time setup, see Development Quickstart.

Frontend-Only Mode​

Command:

bun run dev:web

Use this for:

  • most layout and interaction work
  • many event UI changes
  • router and view work

You do not need the backend for basic frontend rendering.

Backend​

Command:

bun run dev:backend

Use this for:

  • authenticated API work
  • Google OAuth/session behavior
  • Mongo-backed event behavior
  • sync and SSE work

This requires valid Compass YAML config.

Bootstrap once from repo root:

cp compass.example.yaml compass.yaml

Runtime note:

  • bun run dev:backend, bun run dev:web, and bun run cli ... load values from compass.yaml at the repo root.
  • compass.yaml contains secrets. Do not commit it.

Backend Environment Contract​

Source: packages/backend/src/common/constants/config.constants.ts

Workflow: The backend loads compass.yaml, builds the runtime config object directly from it, and validates that object at startup with Zod.

Google Integration

  • Google is disabled unless both google.clientId and google.clientSecret are set to real, non-placeholder values.
  • When Google is enabled and the effective Google webhook URL uses HTTPS, google.notificationToken is required for Google Calendar webhook validation.

Derived backend values:

  • DB is not supplied directly; backend derives it from runtime.nodeEnv
  • ORIGINS_ALLOWED is derived from the backend.originsAllowed YAML list

CLI And Build URL Variables​

Primary files:

  • packages/scripts/src/common/cli.constants.ts
  • packages/scripts/src/common/cli.utils.ts
  • packages/web/build.ts
  • packages/web/dev.ts

Variables used by CLI/build flows:

  • backend.apiUrl (used for local CLI operations and injected into the web build as API_BASEURL)
  • web.url (used by backend auth email flows and CLI domain resolution)

If web.url points to localhost, the CLI prompts for a VM/public domain and builds the API URL from that input.

Web Environment Contract​

Source:

  • packages/web/src/common/constants/env.constants.ts

Important variables:

  • API_BASEURL
  • NODE_ENV
  • POSTHOG_KEY
  • POSTHOG_HOST

google.clientId is optional. When it is missing, the web app hides Google sign-in and Google Calendar connection actions.

BACKEND_BASEURL is derived from API_BASEURL.

Bun build/dev behavior:

  • packages/web/build.ts injects backend.apiUrl as API_BASEURL for production builds
  • packages/web/dev.ts does the same for the local web dev server
  • google.clientId is injected when present
  • if API_BASEURL is not injected, the web app falls back to PORT and builds http://localhost:<PORT>/api

Practical Mode Matrix​

Safe without backend​

  • route changes
  • component rendering
  • keyboard and pointer interactions
  • local storage behavior

Requires backend​

  • user profile loading
  • authenticated event APIs
  • Google connection flows
  • backend validation behavior
  • Mongo persistence
  • SSE stream behavior

Multiple Worktrees​

bun run dev:web and bun run dev:backend run a small preflight (bun run dev:ports) that gives each git worktree its own dev ports. If this worktree has no compass.yaml yet, the preflight copies it from the main checkout; if its ports are already claimed by another worktree's compass.yaml, it rewrites web.port, web.url, backend.port, backend.apiUrl, and the localhost originsAllowed entries to the next free pair (9081/3001, 9082/3002, ...). Comments and secrets in the file are preserved, and reruns are no-ops.

The preflight only mutates gitignored local config. It does not rewrite tracked tooling files such as .claude/launch.json; see issue #1969 for the cleanup that removed that behavior.

Notes:

  • The main checkout keeps the defaults (9080/3000).
  • If web.url or backend.apiUrl is customized (e.g. a tunnel or real domain), the preflight leaves the file alone — manage ports manually.
  • Real Google sign-in only works on ports whose redirect URIs are registered in Google Cloud Console; pin a worktree back to the default ports if you need it.

Backend Health Probe​

When debugging backend startup or connectivity issues, use the health endpoint first:

curl -i http://localhost:<PORT>/api/health

Interpretation:

  • 200 with {"status":"ok","timestamp":"..."}: backend is running and can reach MongoDB
  • 500 with {"status":"error","timestamp":"..."}: backend is running but database connectivity failed
  • connection refused/timeouts: backend process is not listening yet, or the port/base URL is wrong
  • real OAuth
  • real Google Calendar import/sync
  • notification watch flows

Auth And Anonymous Behavior​

Compass supports both:

  • never-authenticated users using local storage
  • authenticated or previously-authenticated users using remote repositories

When testing changes around event loading, explicitly decide which user state you are modeling.

Google Calendar Webhook Notes​

Google OAuth and Google Calendar Watch have different local requirements. Google sign-in can use localhost redirect URLs, but Calendar Watch notifications are server-to-server callbacks from Google to Compass. For those callbacks, Google needs an HTTPS backend URL that it can reach from the public internet.

Compass does not start a local tunnel automatically. Google Calendar webhook watch flows use google.webhookUrl when it is set and fall back to backend.apiUrl when it is not set.

For normal local development:

backend:
  apiUrl: http://localhost:3000/api

Google sign-in, Google Calendar connect, and initial import can still work, but live Google-to-Compass notifications are skipped because Google cannot call a local HTTP backend.

For local end-to-end Google Watch testing, run a temporary HTTPS tunnel to the backend:

cloudflared tunnel --url http://localhost:3000

Then set:

backend:
  apiUrl: http://localhost:3000/api
google:
  webhookUrl: https://<generated-host>.trycloudflare.com/api

Keep backend.apiUrl local so the browser and Server-Sent Events continue using localhost. Only Google's webhook POST requests should use the tunnel.

Stop the tunnel when testing is complete. Do not use personal calendars with sensitive data for manual tunnel tests.

Common Failure Modes​

  • backend exits immediately because required YAML config is missing
  • backend/web/cli read from compass.yaml at the repo root; using .env no longer configures Compass
  • web points at the wrong API base URL
  • session exists but user profile fetch fails
  • sync endpoints work but notification/watch setup is skipped because neither google.webhookUrl nor backend.apiUrl is public HTTPS
  • google.webhookUrl points to a tunnel without /api, so Google posts to the wrong route
  • backend starts but /api/health returns 500 because mongo.uri or database reachability is broken