{"id":14319,"library":"wait-on","title":"wait-on: Resource Readiness Utility","description":"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.","status":"active","version":"9.0.5","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/jeffbski/wait-on","tags":["javascript","wait","delay","cli","files","tcp","ports","sockets","http"],"install":[{"cmd":"npm install wait-on","lang":"bash","label":"npm"},{"cmd":"yarn add wait-on","lang":"bash","label":"yarn"},{"cmd":"pnpm add wait-on","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM import is generally preferred for Node.js versions >=20. The package primarily exports a default function.","wrong":"const waitOn = require('wait-on')","symbol":"waitOn","correct":"import waitOn from 'wait-on'"},{"note":"The CLI is a separate usage pattern; the 'require' example is attempting programmatic use with CLI syntax which is incorrect.","wrong":"require('wait-on')(['http://localhost:3000/api'], () => { ... })","symbol":"CLI Usage","correct":"wait-on http://localhost:3000/api && npm run start-client"},{"note":"Importing types uses the 'type' keyword for clarity and build-time only inclusion in TypeScript environments.","wrong":"import { WaitOnOptions } from 'wait-on'","symbol":"Type Definition","correct":"import type { WaitOnOptions } from 'wait-on'"}],"quickstart":{"code":"import waitOn from 'wait-on';\nimport fs from 'node:fs/promises';\n\nasync function waitForResourcesAndProceed() {\n  const tempFilePath = './temp-resource.txt';\n  const port = 8080;\n\n  console.log('Waiting for temp file and port...');\n  // Simulate a file being created later\n  setTimeout(async () => {\n    await fs.writeFile(tempFilePath, 'This is a test file.');\n    console.log(`Created ${tempFilePath}`);\n  }, 2000);\n\n  try {\n    await waitOn({\n      resources: [\n        tempFilePath, // defaults to file: type\n        `tcp:${port}`, // wait for a TCP port\n        'http://localhost:8080/health' // wait for an HTTP endpoint\n      ],\n      delay: 1000, // initial delay in ms to allow resources to start\n      interval: 100, // poll interval in ms\n      timeout: 30000, // total timeout in ms\n      window: 750 // period in ms to check resource availability (for files to stop growing)\n    });\n    console.log('Resources are ready! Proceeding with application...');\n    // Clean up temporary file for demonstration\n    await fs.unlink(tempFilePath);\n    console.log(`Cleaned up ${tempFilePath}`);\n  } catch (err) {\n    console.error('One or more resources did not become available:', err);\n    process.exit(1);\n  }\n}\n\nwaitForResourcesAndProceed();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"For HTTP GET requests, use `http-get://your-server/path` or `https-get://your-server/path` instead of `http://` or `https://`.","message":"When 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:`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always explicitly specify the resource type prefix (e.g., `file:`, `http:`, `tcp:`, `socket:`) to avoid ambiguity and ensure correct behavior.","message":"By 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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'.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Previous 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.","severity":"breaking","affected_versions":"<8.0.3"}],"env_vars":null,"search_vec":"'9.0.5':47 'address':52 'advanc':91 'align':62 'api':30 'array':74 'avail':17,39 'await':109 'becom':38 'bug':56 'build':102 'ci/cd':121 'cli':25,140 'command':22 'command-lin':21 'cross':14 'cross-platform':13 'crucial':136 'current':43 'delay':139 'depend':53 'design':31 'develop':123 'differenti':68 'domain':84 'endpoint':89 'environ':124 'execut':34 'featur':92 'file':80,96,141 'fix':57 'grow':99 'http':87,145 'includ':78 'interfac':24 'javascript':137 'lifecycl':66 'like':93 'line':23 'local':79 'lts':65 'major':59 'make':113 'minor':49 'mode':107 'node.js':28,64 'orchestr':118 'particular':115 'patch':50 'paus':33 'pipelin':122 'platform':15 'port':82,143 'precis':130 'primarili':61 'process':103 'programmat':29 'readi':5,134 'releas':51 'resourc':4,37,76,110,133 'revers':106 'robust':12 'sequenc':128 'servic':126 'socket':85,144 'specifi':36 'stabl':44 'startup/shutdown':127 'stop':98 'suit':116 'support':71 'task':119 'tcp':81,142 'time':131 'type':77 'unavail':41,111 'unix':83 'updat':54 'use':100 'util':6,16 'version':45,60 'wait':2,8,94,138 'wait-on':1,7 'wide':73","created_at":"2026-04-20T01:59:05.191304+00:00","updated_at":"2026-04-20T01:59:05.191304+00:00","problems":[{"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.","cause":"One or more specified resources did not become available within the allotted timeout period.","error":"Error: wait-on timed out after N ms"},{"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`.","cause":"The `wait-on` CLI tool is not in your system's PATH, likely because it was installed locally or not installed globally.","error":"wait-on: command not found"},{"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.","cause":"The hostname could not be resolved, or the connection timed out before a response was received.","error":"Error: ENOTFOUND or ETIMEDOUT when waiting on HTTP(S) resources."},{"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.","cause":"Incorrect import statement or attempting to call a non-existent function.","error":"TypeError: waitOn is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.1.1","cli_name":"wait-on","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/jeffbski/wait-on","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/wait-on","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}