Pattern: How does the --port flag behave differently in @nx/angular:d...

Documentation for Sessions

🎨 Pattern: How does the --port flag behave differently in @nx/angular:d...

Date: 2026-02-06
Time: 21:03:04 UTC
Session: editor2-97.9
Agent: backend
Confidence: 100%
Status: ✅ Documented

📋 Decision Context

Question:

How does the --port flag behave differently in @nx/angular:dev-server (frontends) vs @nx/js:node (backends)?

Task: NX executor --port flag behavior for frontends vs backends

🎯 Decision Made

Chosen:

Frontend sets HTTP port; Backend sets inspector port

Options Considered:

  1. Both set the HTTP server port
  2. Frontend sets HTTP port; Backend sets inspector port
  3. Both set the inspector port

💭 Reasoning

For @nx/angular:dev-server (frontends), --port configures which HTTP port the webpack/angular dev-server listens on. For @nx/js:node (backends), --port configures the Node.js INSPECTOR port (equivalent to --inspect=PORT). The backend's actual HTTP port comes from process.env (e.g. AI_API_PORT=3001). If both are set to the same value, the inspector binds to loopback:PORT before the app binds to *:PORT, causing WebSocket upgrade requests to hit the debugger instead of the NestJS app — resulting in HTTP 400 'WebSockets request was expected'. This is NOT documented prominently in NX docs and is a significant foot-gun. The dev-serve.js script now marks backends with backend: true and skips --port for them.

📁 Files Involved

🔗 Related

Auto-generated by MCP Smart Consolidation