Registry / http-networking / server-ready

server-ready

JSON →
library0.3.1jsnpmunverified

server-ready is a lightweight Node.js utility designed to ascertain when a network server is listening and ready to accept TCP connections on a specified port. The package operates by repeatedly attempting to establish a TCP connection to the target port, polling every 250 milliseconds until a connection is successful or a default timeout of 20 seconds is reached. While functional, it is important to note that the package, currently at version 0.3.1, has not received updates since 2017, suggesting it is unmaintained. It is primarily intended for use in Node.js scripts, deployment processes, or testing environments where programmatic waiting for server startup is required. Its key differentiator is its simplicity and singular focus on port availability, without deeper application-level health checks.

npm install server-ready
INSTALL
IMPORT
SIG · SERVER-READY
S
server-ready
http-networkingjavascriptv0.3.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

serverReady
const serverReady = require('server-ready')
import serverReady from 'server-ready'
This package is CommonJS-only and does not support ES module import syntax.
serverReady.timeout
const serverReady = require('server-ready'); serverReady.timeout = 5000;
import { timeout } from 'server-ready'
The 'timeout' property is accessed directly on the imported `serverReady` function; it is not a named export.

This quickstart demonstrates how to use `server-ready` to wait for a simulated HTTP server to become available on a specific port, then makes a request to confirm.

const serverReady = require('server-ready'); const http = require('http'); const port = 3001; // Simulate a server that takes a moment to start const server = http.createServer((req, res) => { res.writeHead(200, { 'Content-Type': 'text/plain' }); res.end('Server is ready!\n'); }); // Start the server after a short delay setTimeout(() => { server.listen(port, () => { console.log(`Simulated server started on port ${port}`); }); }, 1000); // Use server-ready to detect when the port is open console.log(`Waiting for server to be ready on port ${port}...`); serverReady(port, (err) => { if (err) { console.error(`Error: ${err.message}`); } else { console.log(`Port ${port} is open or has just opened.`); // Make a request to the ready server http.get(`http://localhost:${port}`, (res) => { let data = ''; res.on('data', (chunk) => data += chunk); res.on('end', () => { console.log(`Received from server: ${data.trim()}`); server.close(() => console.log('Server closed.')); }); }).on('error', (e) => { console.error(`HTTP request error: ${e.message}`); server.close(() => console.log('Server closed due to HTTP error.')); }); } }); // Optional: Set a custom timeout for server-ready // serverReady.timeout = 5000; // 5 seconds
Debug
Known issues
breakingThe `server-ready` package is abandoned and has not been updated since 2017. It may have compatibility issues with newer Node.js versions or contain unpatched vulnerabilities. Use with caution or consider actively maintained alternatives.
fix
Evaluate alternatives like `wait-port`, `tcp-port-used`, or implement custom polling logic for critical applications. If `server-ready` is indispensable, consider forking and maintaining it or thoroughly auditing its codebase.
affects: >=0.3.1
gotchaThe default timeout for `server-ready` is 20 seconds. This might be too long for fast-starting services, leading to unnecessary delays in scripts, or too short for services that take a long time to initialize, resulting in premature failures.
fix
Explicitly set `serverReady.timeout` to an appropriate value (in milliseconds) before calling the function, or pass the timeout as an argument: `serverReady(port, host, timeoutMs, cb)`.
affects: >=0.1.0
gotcha`server-ready` only checks for a successful TCP connection on the specified port. It does not perform application-level health checks (e.g., HTTP status codes, specific API responses). A port being open doesn't guarantee the application is fully initialized or functional.
fix
For robust readiness checks, combine `server-ready` with an application-specific health check (e.g., making an HTTP GET request to a `/health` endpoint and checking the response status) once the port is reported as open.
affects: >=0.1.0
Errors
Common errors & fixes
Error: timeout, can't connect to port
The server failed to start or open the port within the allotted timeout, or a firewall is blocking the connection.
fix
Verify the server process is correctly starting and listening on the specified port. Increase the `serverReady.timeout` if the server takes longer to initialize. Check firewall rules that might be preventing `server-ready` from connecting.
ReferenceError: require is not defined in ES module scope
`server-ready` is a CommonJS module and cannot be directly imported using `import` statements in an ES module environment.
fix
Ensure your project or file uses CommonJS (`.js` files without `"type": "module"` in `package.json`, or `.cjs` files) when requiring `server-ready`. If you must use ES modules, consider a wrapper or use a tool like `createRequire` from Node.js's `module`.
Error: listen EADDRINUSE: address already in use :::<port>
The port `server-ready` is trying to check is already occupied by another process.
fix
Ensure no other application is running on the target port. Use a different port for your server, or gracefully shut down the conflicting process before starting your server and using `server-ready`.
Upgrade
Version history
0.3.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
5 hits · last 30 days
node
4
OpenAI (training)
1
Resources
server-ready — npm install server-ready · libregistry