Registry / devops / wait-on

wait-on

JSON →
library0.1.1jsnpmunverified

wait-on is a robust, cross-platform utility available as both a command-line interface (CLI) and a Node.js programmatic API, designed to pause execution until specified resources become available or unavailable. Its current stable version is 9.0.5, with minor patch releases addressing dependency updates and bug fixes, while major versions primarily align with Node.js LTS lifecycle. It differentiates itself by supporting a wide array of resource types including local files, TCP ports, Unix domain sockets, and HTTP(s) endpoints, with advanced features like waiting for files to stop growing (useful for build processes) and a 'reverse mode' to await resource unavailability. This makes it particularly suited for orchestrating tasks in CI/CD pipelines, development environments, and service startup/shutdown sequences where precise timing and resource readiness are crucial.

npm install wait-on
INSTALL
IMPORT
SIG · WAIT-ON
W
wait-on
devopsjavascriptv0.1.1
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

waitOn
✓ import waitOn from 'wait-on'
✗ const waitOn = require('wait-on')
ESM import is generally preferred for Node.js versions >=20. The package primarily exports a default function.
CLI Usage
✓ wait-on http://localhost:3000/api && npm run start-client
✗ require('wait-on')(['http://localhost:3000/api'], () => { ... })
The CLI is a separate usage pattern; the 'require' example is attempting programmatic use with CLI syntax which is incorrect.
Type Definition
✓ import type { WaitOnOptions } from 'wait-on'
✗ import { WaitOnOptions } from 'wait-on'
Importing types uses the 'type' keyword for clarity and build-time only inclusion in TypeScript environments.

This quickstart demonstrates how to programmatically use `wait-on` in TypeScript to await the creation of a local file and the availability of a TCP port and an HTTP endpoint before proceeding with further application logic.

import waitOn from 'wait-on'; import fs from 'node:fs/promises'; async function waitForResourcesAndProceed() { const tempFilePath = './temp-resource.txt'; const port = 8080; console.log('Waiting for temp file and port...'); // Simulate a file being created later setTimeout(async () => { await fs.writeFile(tempFilePath, 'This is a test file.'); console.log(`Created ${tempFilePath}`); }, 2000); try { await waitOn({ resources: [ tempFilePath, // defaults to file: type `tcp:${port}`, // wait for a TCP port 'http://localhost:8080/health' // wait for an HTTP endpoint ], delay: 1000, // initial delay in ms to allow resources to start interval: 100, // poll interval in ms timeout: 30000, // total timeout in ms window: 750 // period in ms to check resource availability (for files to stop growing) }); console.log('Resources are ready! Proceeding with application...'); // Clean up temporary file for demonstration await fs.unlink(tempFilePath); console.log(`Cleaned up ${tempFilePath}`); } catch (err) { console.error('One or more resources did not become available:', err); process.exit(1); } } waitForResourcesAndProceed();
wait-on --version
Debug
Known issues
breakingVersion 9.0.0 removed support for Node.js versions that are no longer actively maintained or in maintenance, aligning with Node.js LTS releases. This could break environments running on older Node.js versions.
fix
Upgrade your Node.js runtime to version 20, 22, 24, or newer LTS releases to ensure compatibility with wait-on v9.x. Check https://nodejs.org/en/about/releases/ for current LTS versions.
affects: >=9.0.0
gotchaWhen waiting on HTTP(S) resources, `wait-on` defaults to making HEAD requests. If your server does not support HEAD requests or requires a full GET for status, you must explicitly specify `http-get:` or `https-get:`.
fix
For HTTP GET requests, use `http-get://your-server/path` or `https-get://your-server/path` instead of `http://` or `https://`.
affects: >=1.0.0
gotchaBy default, `wait-on` interprets resources without a prefix as file paths. This can lead to unexpected behavior if you intend to wait on a different resource type but omit the prefix.
fix
Always explicitly specify the resource type prefix (e.g., `file:`, `http:`, `tcp:`, `socket:`) to avoid ambiguity and ensure correct behavior.
affects: >=1.0.0
gotchaThe `window` option is crucial for files that are actively being written. If not set appropriately, `wait-on` might prematurely signal readiness before a file is fully flushed or finished growing.
fix
Adjust the `window` option (e.g., `window: 750` ms) to a value suitable for your file write patterns, ensuring `wait-on` waits for the file size to stabilize for that duration before considering it 'available'.
affects: >=1.0.0
breakingPrevious versions (e.g., v8.0.3) included dependency updates for `axios` (1.8.2) which fixed CVE-2024-39338. While this was a patch, users on much older versions of `wait-on` and its dependencies might be exposed to this vulnerability.
fix
Upgrade `wait-on` to the latest stable version (9.0.5 or newer) to ensure all dependency patches, including security fixes for `axios`, are applied.
affects: <8.0.3
Errors
Common errors & fixes
Error: wait-on timed out after N ms
One or more specified resources did not become available within the allotted timeout period.
fix
Increase the `timeout` option in your programmatic usage or the `--timeout` flag in CLI. Verify that the resources (file paths, ports, URLs) are correct and that the services they represent are actually starting up.
wait-on: command not found
The `wait-on` CLI tool is not in your system's PATH, likely because it was installed locally or not installed globally.
fix
If installed locally, run `npx wait-on ...` or ensure `node_modules/.bin` is in your PATH. If you intend global use, install with `npm install -g wait-on`.
Error: ENOTFOUND or ETIMEDOUT when waiting on HTTP(S) resources.
The hostname could not be resolved, or the connection timed out before a response was received.
fix
Check the URL for typos. Ensure the target server is running, accessible from where `wait-on` is executed, and that no firewall is blocking the connection.
TypeError: waitOn is not a function
Incorrect import statement or attempting to call a non-existent function.
fix
Ensure you are using the correct ESM import: `import waitOn from 'wait-on';` or CommonJS: `const waitOn = require('wait-on');`. Confirm `wait-on` is installed correctly.
Upgrade
Version history
0.1.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
13 hits · last 30 days
node
12
OpenAI (training)
1
Resources
wait-on — npm install wait-on · libregistry