Skip to main content

Concern

Easing local development: single command, no port conflicts, consistent configuration.

Technology

Central configuration (env, root scripts) and a Node.js dev launcher script that finds available ports, sets env, and runs the concurrent dev processes. No single external product; the approach is one dev command plus central config.

Implementation

Central configuration
Dev-relevant settings (ports, API URL) are driven from one place when using the root dev command. The dev script sets BACKEND_PORT and FRONTEND_DESKTOP_PORT only; the backend strips BACKEND_ to get PORT, and the desktop Vite config maps FRONTEND_DESKTOP_PORT to VITE_PORT (dev server port) and derives VITE_BACKEND_URL from BACKEND_PORT when unset. So multiple worktrees or other apps can run without editing per-project files. See backend configuration, frontend configuration and vite, and http-client for where those vars are consumed.

Automatic development command
Running pnpm dev from the repo root (1) builds shared and frontends-shared once, (2) runs prisma generate in the backend (so the Prisma client exists), (3) runs scripts/dev.js, which finds an available backend port (prefer 3000) and frontend port (prefer 5173), sets BACKEND_PORT and FRONTEND_DESKTOP_PORT, optionally starts Postgres (see below), runs prisma migrate deploy, then spawns concurrently with the four dev processes. The desktop Vite config derives VITE_BACKEND_URL from BACKEND_PORT when unset. No manual port selection or .env editing needed for typical local runs.

Optional Postgres when DATABASE_URL is unset
The dev script loads the root .env and checks BACKEND_DATABASE_URL. If it is not set, the script finds an available port for Postgres (starting at 5432), starts Postgres in Docker (postgres:17) in the background, waits for it to accept connections, runs prisma migrate deploy, then spawns the four app processes (shared, frontends-shared, backend, desktop). The DB process is a child of the dev script and is terminated when dev stops. If BACKEND_DATABASE_URL is already set in root config, no DB process is started and prisma migrate deploy runs against that URL before the app processes start.

Integration

  • monorepo — Root dev script and workspace layout; see Hot reload (development).
  • package-manager — pnpm dev runs from repo root.
  • configuration (backend) — Backend uses PORT for the HTTP server.
  • vite — Desktop dev server port is set by VITE_PORT (from FRONTEND_DESKTOP_PORT when started via root pnpm dev).
  • http-client — Frontend API base URL uses VITE_BACKEND_URL (derived from BACKEND_PORT when unset in dev).