🎯 @gkucmierz/dport

Deterministic local port generator based on your project name.

Tired of port collisions (EADDRINUSE) or trying to remember which project runs on 3000, 8080, or 5173? dport replaces chaotic local development port assignments with stable, predictable, and mathematically calculated ports.

Why deterministic ports?

• Zero Collisions: Every project gets a unique, stable port based on its name.
• PWA & Service Worker Isolation: Using localhost:3000 everywhere shares LocalStorage, IndexedDB, and active Service Workers between multiple unrelated projects, causing bizarre and hard-to-track bugs. Deterministic ports guarantee 100% strict origin isolation.
• Microservice Harmony: Your backend (45612), frontend (51425), and proxy can securely talk to each other without port mapping spreadsheets.

📖 Read the full philosophy: Dive deep into why monolithic ports are hurting your development flow in my dedicated Tech Blog article: Porty deterministyczne: Lekarstwo na piekło dewelopera

📦 Installation

npm install -g @gkucmierz/dport

🚀 Usage

1. Calculate Port (Auto-detect)

Run inside any Node.js project directory. It automatically reads the name from package.json and calculates your port:

dport
# or
dport calc

2. Fast Custom Calculation

Pass any string directly to generate its specific deterministic port:

dport talk-app-backend

3. Shell Autocomplete

Never type the full command again. dport comes with native autocomplete hook for Zsh & Bash!

# Inject the auto-complete hook into your ~/.zshrc or ~/.bashrc
dport setup

4. Open in Browser

Calculate the port and instantly launch your default browser at http://localhost:<port>:

dport open
dport open tech-blog

No more manual copy-pasting of localhost URLs from the terminal!

5. Auto-Fix your package.json

Scans your scripts block (e.g. dev, serve, preview) and automatically replaces common default development ports (3000, 8080, 5173, 8000, 4000, 4200) with your uniquely calculated deterministic port.

dport fix

🧠 How it Works (Under the hood)

It takes the provided string, reduces it to a stable numeric hash, boundaries it carefully using modulo arithmetic against the ephemeral networking limits, and binds it safely to the 40000 - 65000 port range. The string tech-blog will always generate 51425 — across any machine, operating system, or environment.

Crafted carefully as part of the 7u.pl Tech Ecosystem under strict "The Vault" architectural guidelines. Engineering & Visual Excellence.