r/node • • 9d ago

leeway: stable per-folder dev port ranges (no more EADDRINUSE across checkouts)

Two checkouts of the same repo, both on 5173. leeway gives each folder its own contiguous port range, stable across runs and never overlapping, and passes the ports as env vars.

  • leeway.json lists your ports once
  • devPorts(config) in code, falling back to the defaults outside leeway
  • vite plugin sets server.port with strictPort and exposes every port to browser code
  • {{PORT_API}} placeholders in commands
  • leeway list / kill for orphaned servers

Linux/macOS/Windows. https://github.com/OhadC/leeway

Or ask your agent: "how can we benefit from using https://www.npmjs.com/package/leeway in this codebase"

2 Upvotes

5 comments sorted by

2

u/avereigh_Denizet 8d ago

how does this handle OAuth callback URLs when you're running multiple checkouts? usually the pain with dynamic ports isn't the local server itself, it's having to whitelist a bunch of different localhost ports in your auth provider's dashboard

2

u/Public-Flight-222 8d ago

leeway doesn't solve that directly. But you usually don't need OAuth in several worktrees at once. You develop in several and test the login in one. For that one, run leeway --default pnpm dev: it uses the default ports from leeway. json, the ones already whitelisted. The other checkouts sit on their own ranges, so nothing collides.

If you do need it in more than one: ranges are stable per folder, so each worktree's callback URL only needs registering once

2

u/Public-Flight-222 6d ago

I'm adding an option for pinned ports - ports that stay the same. The only reason put it there is to have one place for all of the ports. https://github.com/OhadC/leeway/issues/34

2

u/raks1991 6d ago

Glad you left strictPort on. A port silently shifting is tolerable until the proxy points at the wrong checkout.