Server Port Readiness Checker

0.3.1 · abandoned · verified Tue Apr 21

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.

Common errors

```
Error: timeout, can't connect to port
```
cause 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
```
cause `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>
```
cause 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`.

Warnings

breaking The `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.
gotcha The 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)`.
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.

Install

npm install server-ready npm
yarn add server-ready yarn
pnpm add server-ready pnpm

Imports

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

Quickstart

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

view raw JSON →