🎯 @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.
• Live Visual Telemetry with Port Lens: Monitor and inspect all running deterministic ports live in real-time using Port Lens (Source Code on Gitea).

📖 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 & Directory Fallback)

Run inside any project directory. It automatically reads the name from package.json, or seamlessly falls back to the current directory name if no package.json exists yet:

dport
# or
dport calc

2. Monorepo & Nested Project Detection

When running inside a subfolder (e.g. skyhook/ui or skyhook/packages/client), dport automatically walks up parent directories (up to 3 levels) to find the project root. It prevents port collisions across different repositories by deriving a composite project name (skyhook-ui) and displaying a transparent candidate list:

$ dport
📦 Project: skyhook-ui (parent 'skyhook' + 'ui')
🎯 Deterministic Port: 1267

📋 Hierarchy candidates (up to 3 levels):
   [1] skyhook-ui           → 1267 (selected)
   [2] ui                   → 45123
   [3] skyhook              → 38921

💡 Tip: Run 'dport <name>' or 'dport <index>' to target a specific candidate.

You can instantly select any candidate by passing its index or subname:

dport 2      # calculates port for 'ui'
dport 2 --fix # replaces ports in local package.json with candidate 2

3. Fast Custom Calculation

Pass any string directly to generate its specific deterministic port:

dport talk-app-backend

4. Shell Scripts & Raw Output (-p, --port)

Output solely the numeric port without headers or emojis, perfect for environment variables and bash automation:

PORT=$(dport -p)
echo "Running on port $PORT"

5. Shell Autocomplete

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

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

6. 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!

7. 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

8. Deterministic Color Palette & UI Tokens

Every port mathematically determines its own aesthetic color palette and coordinated UI design tokens (panels, borders, radial gradients, badges, glows) for dark and light themes:

dport color
dport color workflow-app
dport color 45330 --css

Programmatic JavaScript API:

import {
  getDeterministicHue,
  getDeterministicColor,
  getDeterministicColorPalette
} from '@gkucmierz/dport';

// Port determines the hue (accepts project name or port number)
const hue = getDeterministicHue('workflow-app'); // 194 (matches port 45330)

// Semantic UI styles
const panelBg = getDeterministicColor('workflow-app', 'panel');
const radialGlow = getDeterministicColor(45330, 'radial');
const badgeBorder = getDeterministicColor(45330, { style: 'badgeBorder', theme: 'dark' });

// Full UI design tokens & CSS variables
const palette = getDeterministicColorPalette('workflow-app');
// palette.dark.bgGradient
// palette.dark.border
// palette.cssVars('dark') -> { '--dport-hue': 194, '--dport-bg': ... }

🧠 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.

🌐 Ecosystem & Related Projects

• 🔭 Port Lens — Live network & macOS port scanner dashboard (Gitea Repository).
• ⚡ Skyhook Tunnel — Instant reverse tunnel with native deterministic port routing (skyhook <project>).
• 📖 Tech Blog Article — The architecture behind deterministic ports.

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