wait-port-now

Wait until a TCP port is open. Zero dependencies. Works in Node.js + CLI.

Install

Install locally as a development dependency:

npm install --save-dev wait-port-now

Or run on-demand via npx:

npx wait-port-now 3000

Programmatic API

wait-port-now distributes both native ESM and CommonJS wrappers.

ESM / TypeScript Example

import { waitForPort, TimeoutError } from 'wait-port-now';

async function start() {
  try {
    // Wait for port 5432 with custom options
    await waitForPort(5432, {
      host: 'localhost',
      timeout: 10000, // 10 seconds timeout
      interval: 500   // poll every 500ms
    });
    console.log('Database is ready! Starting application...');
  } catch (err) {
    if (err instanceof TimeoutError) {
      console.error(`Timeout! Port ${err.port} on ${err.host} was not ready within ${err.timeout}ms.`);
    } else {
      console.error('An unexpected error occurred:', err);
    }
  }
}

start();

CommonJS / JavaScript Example

const { waitForPort, TimeoutError } = require('wait-port-now');

async function check() {
  try {
    // Basic usage (defaults to localhost, 30s timeout, 250ms interval)
    await waitForPort(3000);
    console.log('Server is up!');
  } catch (err) {
    if (err instanceof TimeoutError) {
      console.error('Connection timed out');
    }
  }
}

check();

CLI Usage

Usage: wait-port-now <port> [options] [-- <command> [args...]]

Options:
  --host <host>       Host to check (default: localhost)
  --timeout <ms>      Timeout in ms (default: 30000)
  --interval <ms>     Poll interval in ms (default: 250)
  -h, --help          Show help
  -v, --version       Show version

Real-world CLI Examples

1. Wait for PostgreSQL before running migrations (CI/CD Pipelines)

wait-port-now 5432 --timeout 60000 -- npm run db:migrate

2. Wait for a dev server before running Playwright tests (E2E testing)

wait-port-now 3000 -- npx playwright test

3. Wait for Redis before starting a worker (Docker Compose startup)

wait-port-now 6379 --host redis --node worker.js

Options Table

| Option | Type | Default | Description | |--------|------|---------|-------------| | host | string | 'localhost' | Hostname or IP address to connect to | | timeout | number | 30000 | Maximum time to wait in milliseconds before throwing a TimeoutError | | interval | number | 250 | Sleep time in milliseconds between connection retries |

Comparison Table

| Feature | wait-port-now | wait-on | wait-port | |---------|-----------------|-----------|-------------| | Zero dependencies | ✅ | ❌ | ❌ | | TypeScript types | ✅ | ✅ | ❌ | | ESM + CJS | ✅ | ❌ | ❌ | | Node 18+ | ✅ | ✅ | ✅ | | File/HTTP wait | ❌ | ✅ | ❌ |

How It Works

wait-port-now uses Node's native node:net module to perform a raw TCP socket connection check.

• It attempts a TCP handshake with the target host and port.
• If the connection succeeds, it cleans up and releases the socket immediately to prevent connection leaks.
• If it encounters a connection error (like ECONNREFUSED or ENOTFOUND), it waits for the configured interval and retries.
• If the total elapsed time exceeds the timeout, it throws a custom TimeoutError.

License

MIT © 2025 [Your Name]