wait-port

Wait until a port, URL, or file becomes available — then exit. Cross-platform, zero dependencies.

The classic "wait for the database/server to be ready before running tests" utility. Works in CI, Docker entrypoints, and package.json scripts.

Unlike wait-on / wait-port (npm, with dependencies) or until nc -z (Unix-only), this is a single zero-dep Node.js file.

Install

npm install -g wait-port

Or without installing:

npx wait-port 5432

Usage

wait-port 5432                          # Wait for TCP localhost:5432
wait-port localhost:3000 -t 60000       # Wait up to 60s
wait-port http://localhost:8080/health  # Wait for a healthy HTTP endpoint
wait-port 3000 5432 6379                # Wait for ALL three
wait-port file:./build/done             # Wait for a file to appear
wait-port 3000 --reverse                # Wait until port 3000 is FREED

Gate a command on readiness:

wait-port db:5432 && npm test

Target Formats

| Target | Meaning | |---|---| | 3000 | TCP localhost:3000 | | localhost:5432 | TCP host:port | | db:5432 | TCP host:port | | http://host/health | HTTP — ready when status < 400 | | https://host | HTTPS | | file:./path | File existence |

Example Output

wait-port  waiting for localhost:5432 to be ready...
  ✓ localhost:5432 ready  (2.4s)

Multiple targets:

wait-port  waiting for localhost:3000, localhost:5432, localhost:6379 to be ready...
  ✓ all 3 targets ready  (5.1s)

Timeout:

wait-port  waiting for localhost:9999 to be ready...
  ✗ Timed out after 30s — still not ready: localhost:9999

Options

| Flag | Default | Description | |---|---|---| | -t, --timeout <ms> | 30000 | Give up after this long (0 = wait forever) | | -i, --interval <ms> | 500 | Poll interval | | --probe-timeout <ms> | 2000 | Per-attempt connection timeout | | -r, --reverse | off | Wait until the target is gone instead of available | | -q, --quiet | off | No output, just the exit code |

Exit Codes

• 0 — all targets became available (or freed, with --reverse)
• 1 — timed out
• 2 — invalid target

CI Example

- name: Start services
  run: docker compose up -d
- name: Wait for Postgres + Redis
  run: npx wait-port localhost:5432 localhost:6379 -t 60000
- name: Run tests
  run: npm test

License

MIT

Keywords

wait for port · wait-on alternative · wait for server · healthcheck · ci wait · wait for service · tcp wait · docker entrypoint · cross-platform · zero dependencies

Built to solve, shared to help — Rushabh Shah 🛠️✨

One of 40+ zero-dependency developer CLI tools — no node_modules, ever.