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.}