Derive unique default port per worktree to avoid collisions
- Dominant language
- TypeScript
- Stars
- 481
- Forks
- 108
- Avg merge
- 8d 9h
- Merged PRs (30d)
- 7
Description
## Description
When running `pnpm dev` across parallel git worktrees, every instance defaults to port 80 (from `resolveServerConfig` in `server-config.ts`). This means the second+ worktree always hits EADDRINUSE and must be manually configured with a different port.
With the fail-fast fix in place (#1925), the collision is no longer silent — the process exits cleanly — but the developer still has to remember to set a unique port for each worktree, which is friction that could be eliminated.
## Preferred Solution
Derive a stable, unique default port per worktree so parallel instances never collide without manual configuration. Approaches to consider:
- Hash the worktree directory name into a port in a safe range (e.g. 3000–9999) and use that as the default when no explicit port is configured
- Read a `PORT` or `PROXY_SERVER_PORT` env var (already supported?) and document setting it per-worktree
- Use a `.env` or config file local to the worktree
The port should be stable (same worktree always gets the same port) and deterministic (no file locks or port scanning). The developer should be able to discover which port their worktree uses (log it on startup).
## Key constraint: don't break existing workflows
The tricky part here isn't the hashing — it's making sure we don't silently change the port for anyone who already depends on the current default (port 80). Users running Graph Explorer in production, in Docker, or behind a reverse proxy may have hardcoded that port in their configuration. A change to the default port derivation could break those setups without warning.
Whatever approach we take needs to:
- Preserve the existing behavior when an explicit port is configured (env var, CLI flag, config file)
- Only apply worktree-derived ports in development contexts where no explicit port is set and the process is running from a git worktree
- Make it obvious at startup which port was chosen and why, so no one is silently served on a different port than they expect
## Related Issues
- Builds on #1925
---
> [!IMPORTANT]
> Internal only — this issue is maintained by the core team and is not accepting external contributions.
Contributor guide
Research direction
Start in server-config.ts at resolveServerConfig and trace how pnpm dev determines its default port and handles explicit configuration. Review the constraints in this issue and related issue #1925, then define a deterministic worktree-only behavior that preserves configured and non-development ports. Done means the selected port is stable, discoverable at startup, and does not silently change existing workflows.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git, typescript
- Domain
- developer-experience, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 15/100