port-arranger

Run multiple dev servers without port conflicts

Quick Start · Usage Guide · Commands · How It Works

Why port-arranger?

The Problem

# Terminal 1
npm run dev  # localhost:3000

# Terminal 2
npm run dev  # Error: Port 3000 is already in use

When running multiple projects simultaneously during development, port conflicts are inevitable. You end up manually changing ports or hunting down processes to kill.

The Solution

pa run "npm run dev"  # Automatically assigns an available port

port-arranger wraps your dev server commands and automatically finds and assigns available ports. No more port conflicts, ever.

Key Features

	Feature	Description
⚡	Auto Port Assignment	Automatically finds and assigns available ports
🔍	Framework Detection	Recognizes Next.js, Vite, Express, FastAPI, and more
📋	Process Management	List, monitor, and stop running servers
🖥️	GUI Dashboard	Visual server management with Electron-based UI

Requirements

• Node.js 18+

Quick Start

# Install globally
npm install -g port-arranger

# Run your dev server
pa run "npm run dev"

That's it! port-arranger handles the rest.

Usage Guide

Step 1: Run a Server

# Basic usage
pa run "npm run dev"

# With a custom name
pa run "npm run dev" --name my-frontend

# With a preferred port (falls back to available port if taken)
pa run "npm run dev" --port 3000

Step 2: Manage Servers

# List all running servers
pa list

# Stop a specific server
pa stop my-frontend

# Stop all servers
pa stop --all

Step 3: GUI Dashboard

Launch the visual dashboard for an overview of all your running servers:

pa ui

Commands

Command	Description	Example
pa run <cmd>	Run a command with auto port assignment	pa run "npm run dev"
pa run <cmd> --name <n>	Run with a custom project name	pa run "npm run dev" --name api
pa run <cmd> --port <p>	Run with a preferred port	pa run "npm run dev" --port 3000
pa list	List all running servers	pa list
pa stop <name>	Stop a server by name	pa stop my-project
pa stop --all	Stop all running servers	pa stop --all
pa ui	Open the GUI dashboard	pa ui

Supported Frameworks

Framework	Port Injection Method	Example
Next.js	Environment variable	PORT=3001 npm run dev
Vite	CLI flag	vite --port 3001
Express	Environment variable	PORT=3001 node server.js
FastAPI / uvicorn	CLI flag	uvicorn main:app --port 3001
Python http.server	Argument	python -m http.server 3001

How It Works

┌─────────────────────────────────────────────────────────────┐
│  pa run "npm run dev"                                       │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  1. Parse Command                                           │
│     Detect framework pattern (Next.js, Vite, Express, etc.) │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  2. Find Available Port                                     │
│     Use detect-port to find an open port                    │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  3. Inject Port                                             │
│     Apply framework-specific injection (env, flag, arg)     │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  4. Spawn & Track Process                                   │
│     Save process info to ~/.port-arranger/state.json        │
└─────────────────────────────────────────────────────────────┘

Configuration

port-arranger stores state in ~/.port-arranger/state.json:

{
  "processes": [
    {
      "name": "my-frontend",
      "port": 3001,
      "pid": 12345,
      "command": "npm run dev",
      "cwd": "/path/to/project",
      "startedAt": "2026-02-01T10:30:00.000Z"
    }
  ]
}

Contributing

Contributions are welcome! Feel free to:

• 🐛 Report bugs
• 💡 Suggest features
• 🔧 Submit pull requests

Author

Changmin (Chris) Kang