Dev Stack Tasks — VS Code / Cursor & yarn serve

Start and stop dev servers via tasks and scripts; dev-serve.js behavior, stability, and health monitoring

Dev Stack Tasks — Start and Kill Development Services

Purpose: Run development servers from Cursor/VS Code tasks or from yarn serve:* without guessing ports. This document is the canonical reference for the dev stack wiring in this repo.

Overview

Piece Role
.vscode/tasks.json Tasks such as Dev Stack (All), per-app [serve] / [kill], [serve · no restart], Continuous Health Monitoring
.vscode/launch.json Run and Debug configs: dev-serve: <app> (no restart) with DEV_SERVE_NO_RESTART=1 and autoAttachChildProcesses
package.json serve:* Delegates to tools/scripts/dev-serve.js for consistent ports and NX invocation
tools/scripts/dev-serve.js Resolves ports from .env.local, starts nx daemon (best effort), runs nx serve, auto-restarts on crash
tools/scripts/dev-kill.js Stops processes listening on the configured ports
tools/scripts/performance/continuous-monitor.js Optional logging-only process counts (does not kill Node or reset NX)

How to run tasks: Cmd+Shift+P → Tasks: Run Task → pick a task.

Start tasks

Compound tasks (multiple services)

Task Services started
Dev Stack (APIs Only) API, AI-API, VITTO + zsh
Dev Stack (Frontend Only) gograb-space, gograb-admin, gograb-dev, gograb-ai, space-admin + zsh
Dev Stack (All) All of the APIs above + all frontends above + zsh
Dev Stack (All + Docs) Same as All, plus DOCS-API and docs-angular

Compound tasks use dependsOrder: parallel: each [serve] task opens its own dedicated terminal. Some backend tasks include a short sleep before yarn so not every process hits NX/webpack at the exact same instant (reduces startup contention).

NX daemon: Each yarn serve:* invocation runs npx nx daemon --start inside dev-serve.js before nx serve. You do not need to run Start NX Daemon (Manual) first, but that task is still available if the daemon is wedged.

Individual [serve] tasks

Task label App Port variable (see .env.local)
API (gspace1) [serve] backend-api API_PORT (default 3000)
AI-API (gspace1) [serve] backend-ai-api AI_API_PORT (default 3001)
VITTO (gspace1) [serve] backend-vitto-api VITTO_API_PORT (default 3003)
DOCS-API (gspace1) [serve] backend-docs-api DOCS_API_PORT (default 3002)
GOGRAB-SPACE (gspace1) [serve] gograb-space GOGRAB_SPACE_PORT
GOGRAB-ADMIN (gspace1) [serve] gograb-admin GOGRAB_ADMIN_PORT
GOGRAB-DEV (gspace1) [serve] gograb-dev GOGRAB_DEV_PORT
GOGRAB-AI (gspace1) [serve] gograb-ai GOGRAB_AI_PORT
SPACE-ADMIN (gspace1) [serve] space-admin SPACE_ADMIN_PORT
DOCS-ANGULAR (gspace1) [serve] docs-angular GOGRAB_DOCS_PORT
ZSH (gspace1) [shell] Interactive shell —

Label pattern: {APP} (gspace1) [serve]. For [serve · no restart], see Debugging one-shot crashes.

dev-serve.js behavior (stability)

All yarn serve:* scripts use node tools/scripts/dev-serve.js. Important behaviors:

  1. Ports — Read from process.env, then .env.local, then defaults (see script header). Do not pass --port to backend serve (it affects the Node inspector, not the app port; see comments in dev-serve.js and repo architecture docs).

  2. Daemon warmup — Runs npx nx daemon --start before nx serve to reduce “daemon terminated” / socket races when many terminals start together.

  3. Child process — Uses spawn (not blocking execSync) so signals behave predictably in the IDE terminal.

  4. Auto-restart — If nx serve exits with a non-zero code, the wrapper waits (backoff capped at 30s) and starts again. Stop this when debugging repeated crashes:

    • DEV_SERVE_NO_RESTART=1 yarn serve:gograb-space, or
    • node tools/scripts/dev-serve.js gograb-space --no-restart

  5. Backend port already in use — If the listen port is taken, the script does not start a second server and exits with code 1 so the task is visibly failed. Kill the old process or use the matching [kill] task first.

  6. Backends — NODE_OPTIONS includes a reduced heap for webpack in dev; typecheck is relaxed for speed (TS_NODE_TRANSPILE_ONLY where applicable).

Debugging one-shot crashes (no restart)

When you need the last error to stay on screen or you want to attach a debugger without dev-serve respawning the child:

Method What to do
Tasks Tasks: Run Task → choose {APP} (gspace1) [serve · no restart] — sets DEV_SERVE_NO_RESTART=1 (same commands as normal [serve], including staggered sleep on some backends).
Launch Run and Debug (or F5 with a config selected) → dev-serve: <app> (no restart). Runs tools/scripts/dev-serve.js with the same args as yarn serve:*, DEV_SERVE_NO_RESTART=1, and autoAttachChildProcesses: true so VS Code can attach to child processes spawned by nx.
CLI DEV_SERVE_NO_RESTART=1 yarn serve:gograb-space or node tools/scripts/dev-serve.js gograb-space --no-restart

Legacy: backend-api: nx serve + inspector 9229 (bypasses dev-serve) runs yarn nx serve backend-api directly with --inspect=9229. It does not go through dev-serve.js (ports/env differ from the usual path). Prefer the dev-serve: backend-api (no restart) config unless you specifically need that inspector setup.

Kill tasks

Unchanged from prior docs: use Dev Stack (Kill) for full cleanup, Dev Stack (Kill Ports Only) for ports only, or per-app [kill] tasks. Details remain in tools/scripts/dev-kill.js (port-based, safe for servers).

Continuous Health Monitoring (optional)

Use Monorepo Health Check (Manual) (yarn crash:prevent) when you want a deliberate cleanup workflow — not as a substitute for [kill] tasks.

Ports and .env.local

Copy from .env.example if needed. gspace1 typically uses frontend ports in the 6xxx range and shared backends 3000–3003; editor2 uses other ranges. Wrong ports cause confusing 404s and connection errors.

For agents and developers

  1. Prefer yarn serve:* or VS Code [serve] tasks over raw nx serve with hardcoded ports.
  2. Prefer Dev Stack (Kill) (or [kill] per app) over killing random PIDs.
  3. If the daemon is broken: Start NX Daemon (Manual) or yarn nx reset when no dev servers need to stay up.
  4. Read docs/english/architecture/APIs-architecture.md (or repo AGENTS.md) for never pass --port to backend serve and WebSocket behavior.

Practices that improve stability (short list)

Practice Why it helps
Open the gspace1 folder as the workspace root when using tasks Tasks assume ${workspaceFolder} is the monorepo root
Run yarn crash:prevent when the doc set recommends it (heavy sessions) Reduces stale cache / fd issues before a big parallel start
Use compound tasks instead of manually starting ten commands Fewer forgotten env vars and port mistakes
DEV_SERVE_NO_RESTART=1 while debugging exit codes Avoids restart loops hiding the last stack trace
After cache corruption symptoms, nx reset — but not during active serves Reset disrupts running webpack/NX
Keep Node major version aligned with CI / .nvmrc if present Avoids one-off native or resolution bugs
Do not rely on an old continuous-monitor path under tools/scripts/ Use performance/continuous-monitor.js as in tasks.json

For multi-repo setups and file limits, see Developers/monorepo/ and troubleshooting/system-overload-prevention.md.

Related docs