automatically

Zero-config port management - just prefix your command and run any dev server without port conflicts

Stop crashing into existing servers! automatically finds available ports and runs your dev servers automatically - no code changes needed.

Installation

Global (Recommended)

npm install -g automatically

Per-project

npm install automatically

Quick Start - CLI (Zero Config!)

Just prefix any dev server command with automatically:

# React / Create React App
automatically npm start

# Next.js
automatically npm run dev
automatically next dev

# Express / Node
automatically node server.js
automatically npm start

# Python
automatically python manage.py runserver
automatically python -m http.server

# Any framework
automatically <your-command>

How it works:

1. Finds an available port (starting from 3000)
2. Sets the PORT environment variable
3. Runs your command with that port
4. Most frameworks automatically use the PORT env variable

Example output:

$ automatically npm start

✨ Found available port: 3001
🚀 Starting: npm start

> [email protected] start
> react-scripts start

Compiled successfully!
Server running on http://localhost:3001

CLI Usage

Basic Commands

# Start any server
automatically npm start
automatically node app.js
automatically next dev
automatically python -m http.server

# View help
automatically
automatically --help

Multiple Servers Simultaneously

Run multiple dev servers without conflicts:

# Terminal 1
automatically npm start          # → Port 3000

# Terminal 2
automatically npm start          # → Port 3001 (auto-picks next)

# Terminal 3
automatically next dev           # → Port 3002

Library Usage (Advanced)

You can also use automatically as a library in your code:

Installation

npm install automatically

Basic Usage

const automatically = require('automatically');

// Find next available port (starts from 3000)
const port = await automatically();
console.log(`Server running on port ${port}`);

// Start from a specific port
const port = await automatically(5000);

With Express

const express = require('express');
const automatically = require('automatically');

const app = express();

automatically(3000).then(port => {
  app.listen(port, () => {
    console.log(`Server running on http://localhost:${port}`);
  });
});

TypeScript Support

Full TypeScript support included!

import automatically, { PortOptions } from 'automatically';

const port: number = await automatically(3000);

const options: PortOptions = {
  start: 3000,
  end: 9000,
  host: 'localhost'
};

const port2: number = await automatically(options);

API

automatically(startPort?)

Find the next available port starting from startPort (default: 3000).

const port = await automatically();        // Start from 3000
const port = await automatically(5000);    // Start from 5000

automatically(options)

Find port with advanced options.

const port = await automatically({
  start: 3000,  // Start port (default: 3000)
  end: 9999,    // End port (default: 9999)
  host: '127.0.0.1'  // Host to check (default: '127.0.0.1')
});

automatically.check(port, host?)

Check if a specific port is available.

const isAvailable = await automatically.check(3000);
console.log(isAvailable); // true or false

automatically.ports(count, options?)

Get multiple available ports.

const ports = await automatically.ports(3, { start: 4000 });
console.log(ports); // [4000, 4001, 4002]

automatically.kill(port)

Kill the process running on a specific port (cross-platform).

await automatically.kill(3000);
console.log('Port 3000 is now free');

Examples

CLI - Multiple Projects

# Work on multiple projects simultaneously
cd ~/project-a
automatically npm start      # Runs on 3000

cd ~/project-b
automatically npm start      # Runs on 3001

cd ~/project-c
automatically next dev       # Runs on 3002

Library - Express Server

const express = require('express');
const automatically = require('automatically');

const app = express();

app.get('/', (req, res) => {
  res.send('Hello World!');
});

automatically(3000).then(port => {
  app.listen(port, () => {
    console.log(`Express server running on http://localhost:${port}`);
  });
});

Library - Multiple Servers

const automatically = require('automatically');

async function startServers() {
  const ports = await automatically.ports(3, { start: 3000 });

  ports.forEach((port, index) => {
    // Start your servers on each port
    console.log(`Server ${index + 1} on port ${port}`);
  });
}

startServers();

Library - Clean Up Port Before Starting

const automatically = require('automatically');

async function start() {
  const targetPort = 3000;

  // Kill any process on the port
  await automatically.kill(targetPort);

  // Now start your server
  app.listen(targetPort, () => {
    console.log(`Server running on port ${targetPort}`);
  });
}

start();

Why automatically?

• Zero Config: Just prefix your command - no code changes needed
• CLI + Library: Use as global CLI tool or import as library
• Smart: Automatically picks available ports - never crashes your existing servers
• Universal: Works with any framework (React, Next.js, Express, Django, etc.)
• Cross-platform: Works on Windows, macOS, and Linux
• TypeScript: Full type definitions included

How It Works

CLI Mode

1. Scans for available port starting from 3000
2. Sets PORT environment variable to the available port
3. Executes your command with that environment
4. Your framework reads PORT and uses it automatically

Library Mode

automatically checks ports by attempting to bind a server to each port. If a port is available, it returns immediately. If not, it tries the next port until it finds one that's free.

Framework Compatibility

Works with any framework that respects the PORT environment variable:

• ✅ React / Create React App - Uses PORT automatically
• ✅ Next.js - Uses PORT automatically
• ✅ Express - Use process.env.PORT
• ✅ Vite - Uses PORT automatically
• ✅ Angular - Configure to use PORT
• ✅ Django - Can specify port in runserver
• ✅ Flask - Use port=os.getenv('PORT')
• ✅ Any custom server - Read from process.env.PORT or os.getenv('PORT')

License

MIT

Contributing

Issues and PRs welcome at https://github.com/gzew/automatically