Architecture: How should package.json scripts resolve ports dynamically fr...

Documentation for Sessions

🏗️ Architecture: How should package.json scripts resolve ports dynamically fr...

Date: 2026-02-06
Time: 19:32:51 UTC
Session: editor2-97.5
Agent: angular
Confidence: 95%
Status: ✅ Documented

📋 Decision Context

Question:

How should package.json scripts resolve ports dynamically from .env.local?

Task: Session 97: Cross-platform dynamic port resolution for package.json scripts

🎯 Decision Made

Chosen:

Cross-platform Node.js wrapper script (tools/scripts/dev-serve.js) that parses .env.local and passes --port to nx serve

Options Considered:

bash source .env.local (macOS/Linux only)
dotenv-cli npm package (new dependency)
Node.js wrapper script (zero deps, cross-platform)
NX env var interpolation (not supported)

💭 Reasoning

The team uses macOS, Windows, and Linux. bash source is not cross-platform. dotenv-cli adds a dependency and still needs shell expansion. NX does not support env var interpolation in project.json. A Node.js script uses only built-in modules (fs, path, child_process), works on all platforms, and provides a single mapping table (APP_PORT_MAP) that maps app names to env vars with defaults. Supports --only flag for serve-only targets (frontend without backend dependency).

📁 Files Involved

tools/scripts/dev-serve.js
package.json
.env.local

🔗 Related

Decision ID: dev_1770406371867_xzi8f87
Session: 97
Workspace: editor2

Auto-generated by MCP Smart Consolidation