{"id":15377,"library":"server-ready","title":"Server Port Readiness Checker","description":"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.","status":"abandoned","version":"0.3.1","language":"javascript","source_language":"en","source_url":"https://github.com/typicode/server-ready","tags":["javascript","server","ready","port","open"],"install":[{"cmd":"npm install server-ready","lang":"bash","label":"npm"},{"cmd":"yarn add server-ready","lang":"bash","label":"yarn"},{"cmd":"pnpm add server-ready","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is CommonJS-only and does not support ES module import syntax.","wrong":"import serverReady from 'server-ready'","symbol":"serverReady","correct":"const serverReady = require('server-ready')"},{"note":"The 'timeout' property is accessed directly on the imported `serverReady` function; it is not a named export.","wrong":"import { timeout } from 'server-ready'","symbol":"serverReady.timeout","correct":"const serverReady = require('server-ready'); serverReady.timeout = 5000;"}],"quickstart":{"code":"const serverReady = require('server-ready');\nconst http = require('http');\n\nconst port = 3001;\n\n// Simulate a server that takes a moment to start\nconst server = http.createServer((req, res) => {\n  res.writeHead(200, { 'Content-Type': 'text/plain' });\n  res.end('Server is ready!\\n');\n});\n\n// Start the server after a short delay\nsetTimeout(() => {\n  server.listen(port, () => {\n    console.log(`Simulated server started on port ${port}`);\n  });\n}, 1000);\n\n// Use server-ready to detect when the port is open\nconsole.log(`Waiting for server to be ready on port ${port}...`);\nserverReady(port, (err) => {\n  if (err) {\n    console.error(`Error: ${err.message}`);\n  } else {\n    console.log(`Port ${port} is open or has just opened.`);\n    // Make a request to the ready server\n    http.get(`http://localhost:${port}`, (res) => {\n      let data = '';\n      res.on('data', (chunk) => data += chunk);\n      res.on('end', () => {\n        console.log(`Received from server: ${data.trim()}`);\n        server.close(() => console.log('Server closed.'));\n      });\n    }).on('error', (e) => {\n      console.error(`HTTP request error: ${e.message}`);\n      server.close(() => console.log('Server closed due to HTTP error.'));\n    });\n  }\n});\n\n// Optional: Set a custom timeout for server-ready\n// serverReady.timeout = 5000; // 5 seconds","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.3.1"},{"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)`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"`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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The server failed to start or open the port within the allotted timeout, or a firewall is blocking the connection.","error":"Error: timeout, can't connect to port"},{"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`.","cause":"`server-ready` is a CommonJS module and cannot be directly imported using `import` statements in an ES module environment.","error":"ReferenceError: require is not defined in ES module scope"},{"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`.","cause":"The port `server-ready` is trying to check is already occupied by another process.","error":"Error: listen EADDRINUSE: address already in use :::<port>"}],"ecosystem":"npm"}