http-graceful-shutdown is a Node.js utility library designed to ensure HTTP and HTTPS servers (including those built with frameworks like Express, Koa, and Fastify, or native Node.js http/http2) shut down cleanly and without disrupting active client connections. It manages open sockets, stops accepting new connections, and allows for the registration of custom cleanup functions (e.g., closing database connections) to execute before the server fully terminates. The library tracks all connections, gracefully communicates shutdown intent to clients, and can optionally destroy remaining sockets forcefully after a timeout. Version 3.1.16 is the current stable release, with version 3.0 being a significant update that improved internal handling while maintaining backward compatibility with 2.x. It has seen over 35 million downloads, indicating its widespread adoption for robust application termination. The release cadence appears stable, with major versions being well-tested.
npm install http-graceful-shutdownVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to integrate `http-graceful-shutdown` with an Express application, showing server initialization, handling a simulated long-running request, and registering custom cleanup functions during a graceful shutdown triggered by signals like `SIGINT` or `SIGTERM`.
Thoroughly test existing shutdown logic and custom cleanup functions after upgrading to ensure expected behavior. Review the examples for version 3.x to understand any changes in best practices.
If conflicts arise, configure `http-graceful-shutdown` to disable automatic signal handling (`disableSignalHandlers: true`) and manually trigger shutdown using `gracefulShutdown.shutdown()` within your own signal handler. Alternatively, ensure `http-graceful-shutdown` is initialized last to give it priority.
To prevent `process.exit()`, set `forceExit: false` in the options passed to `gracefulShutdown(server, { forceExit: false })`. Be aware that without `forceExit`, your application might hang if any lingering event loop tasks or open handles prevent it from naturally exiting.Carefully calculate the `timeout` value based on your longest expected request processing time plus any synchronous or asynchronous cleanup operations. Test various shutdown scenarios under load to find an optimal balance.
Ensure all long-running processes and connections (like database clients, Redis, message queues) are explicitly closed within the `onShutdown` or `preShutdown` hooks. Alternatively, set `forceExit: true` (which is the default) to ensure termination after the configured timeout, or manually call `process.exit()` in your `finally` hook.
Use the correct import statement for a default export: `import gracefulShutdown from 'http-graceful-shutdown';` for ESM, or `const gracefulShutdown = require('http-graceful-shutdown');` for CommonJS.Wrap the asynchronous operations within your `onShutdown` and `preShutdown` functions in `try...catch` blocks or chain `.catch()` to handle potential rejections gracefully. While the library itself handles errors within these hooks to prevent process crashes, logging and specific error handling are your responsibility.
No dependency data recorded yet.