Graceful shutdown signal handler utility for Node.js
- Features
- Requirements
- Setup
- Usage
- Development
- Testing
- Troubleshooting
- Security
- API
- Packaging
- Examples
- Support
- Links
- License
Handle SIGTERM, SIGINT, and SIGHUP.
Run ordered cleanup hooks during shutdown.
Control the exit code or disable process exit.
Use Node.js 26 or later. Use native ESM.
Run this command in your project:
npm install @eliware/signalsThis command installs the current latest release from npm.
Import registerSignals from @eliware/signals.
Pass a cleanup function as shutdownHook.
Set exit: false when your application controls process exit.
Call shutdown() to run cleanup and wait for completion.
Call removeHandlers() when you no longer need the registration.
import registerSignals from "@eliware/signals";
registerSignals({
shutdownHook: async () => {
process.stdout.write("Cleanup complete\n");
},
});This example requires Node.js 26 or later and native ESM.
Run it in a project that has this package installed.
Send SIGTERM, SIGINT, or SIGHUP to run the hook.
The process exits with code 0 after the hook.
Read the release notes for user-visible changes. Read the user guides for full usage details.
Run npm ci to install the locked development dependencies.
Run npm test before you commit changes.
Run npm test to validate the package.
Set exit: false when your application controls process exit.
Call and await shutdown() when your application must wait for cleanup.
Read the troubleshooting guide for more help.
Keep secrets and sensitive shutdown data out of logs.
Do not rely on asynchronous cleanup during Node.js exit events.
Call registerSignals(options?) to get a registration object.
Options include processObj, log, signals, shutdownHook, exitCode, exit, and signal.
Each hook runs in registration order.
The package logs hook errors and continues to later hooks.
Read the API reference and type declarations for details.
The package uses native ESM and requires Node.js 26 or later.
The runtime entrypoint is src/index.mjs.
The type declarations are src/index.d.ts.
The package includes source, docs, examples, and specifications.
Install the public package from npm.
Repository validation does not authorize publication.
Read the documentation index and specification index.
Read the example index.
The example requires Node.js 26 or later and installed package dependencies.
Run it with node examples/example.mjs.
It runs cleanup and removes handlers without exiting the process.
For help, questions, or to chat with the author and community, visit:
