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

$3

``bash
npm install -g automatically
`

$3

`bash
npm install automatically
`

Quick Start - CLI (Zero Config!)

Just prefix any dev server command with automatically:

`bash


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
`

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:
`bash
$ automatically npm start

✨ Found available port: 3001
🚀 Starting: npm start

> my-app@1.0.0 start
> react-scripts start

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

CLI Usage

$3

`bash


Start any server

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

View help

automatically
automatically --help
`

$3

Run multiple dev servers without conflicts:

`bash


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:

$3

`bash
npm install automatically
`

$3

`javascript
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);
`

$3

`javascript
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});
});
});
`

$3

Full TypeScript support included!

`typescript
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

$3

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

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

$3

Find port with advanced options.

`javascript
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')
});
`

$3

Check if a specific port is available.

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

$3

Get multiple available ports.

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

$3

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

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

Examples

$3

`bash


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
`

$3

`javascript
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});
});
});
`

$3

`javascript
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();
`

$3

`javascript
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

$3


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

$3

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