Manage multiple dev servers with health checks, port handling, and unified logs.
- Start, stop, and monitor multiple servers from one command
- Health checks with automatic retry and status reporting
- Port conflict resolution — finds the next available port
- Centralized logs in
.dev/log/with configurable viewers - Auto-configuration from
package.jsonscripts - Native OS notifications for server events
- Automatic cleanup of stale processes
Most projects juggle multiple servers: frontend, backend, workers. Running them manually means scattered terminals, forgotten processes, and port conflicts. dev gives you a single command to start everything, track what's running, and view logs in one place.
# Install globally npm install -g @wilmoore/dev # Or run directly with npx npx @wilmoore/dev initInitialize in your project, then start:
npx dev init # Creates .dev/servers.json from package.json npx dev start # Starts the first configured server npx dev status # Shows running servers npx dev logs # Follows logs in real-time npx dev stop # Stops all servers| Command | Description | Example |
|---|---|---|
init | Initialize .dev/ directory from package.json | npx dev init |
start [server] | Start a server (default: first) | npx dev start frontend |
stop [server] | Stop server(s) (default: all) | npx dev stop backend |
restart [server] | Restart a server | npx dev restart api |
status | Show running servers with health status | npx dev status |
logs [server] | Follow server logs | npx dev logs api |
doctor | Diagnose environment and configuration | npx dev doctor |
cleanup | Remove stale PID entries | npx dev cleanup |
Shortcut: Use server names directly as commands:
npx dev frontend # Same as: npx dev start frontendThe init command creates .dev/servers.json:
{ "frontend": { "command": "npm run dev > .dev/log/frontend.log 2>&1", "preferredPort": 3000, "healthCheck": "http://localhost:{PORT}" }, "backend": { "command": "npm run server --port {PORT} > .dev/log/backend.log 2>&1", "preferredPort": 3010, "healthCheck": "http://localhost:{PORT}/health" } }| Key | Description |
|---|---|
command | Shell command to run. Use {PORT} and {ROLE} as placeholders. |
preferredPort | Starting port. Auto-increments if busy. |
healthCheck | URL to poll until the server responds. |
| Variable | Description | Default |
|---|---|---|
DEV_LOG_VIEWER | Command for viewing logs | tail -f |
ENABLE_NOTIFICATIONS | Enable OS notifications | true |
npx dev logs --log-viewer "bat -f" # Syntax highlighting npx dev logs --log-viewer "less +F" # Scrollable # Or set a default export DEV_LOG_VIEWER="bat -f"Use {PORT} and {ROLE} for dynamic values:
{ "worker": { "command": "NODE_ENV={ROLE} node worker.js --port {PORT} > .dev/log/{ROLE}.log 2>&1", "preferredPort": 4000, "healthCheck": "http://localhost:{PORT}/health" } }If the preferred port is busy, dev tries the next one:
$ npx dev start api Started api on port 3001 (3000 was busy) ENABLE_NOTIFICATIONS=false npx dev startAfter initialization:
your-project/ ├── .dev/ │ ├── servers.json # Server config (commit this) │ ├── pid.json # Process tracking (gitignored) │ └── log/ # Log files (gitignored) └── package.json MIT — see LICENSE for details.
Built for developers who value efficient workflows.