aws / aws/graph-explorer

Derive unique default port per worktree to avoid collisions

Open
#1,926 0 comments 0 reactions 0 assignees View on GitHub
infrastructure internal
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.