Graceful HTTP(S) Server Terminator

1.2.3 · active · verified Wed Apr 22

lil-http-terminator is a minimalistic, zero-dependency Node.js library designed for gracefully shutting down HTTP and HTTPS servers. Currently at stable version 1.2.3, it offers a consistent, promise-based API for managing server connections during shutdown. Its core differentiator lies in its low footprint (11 KB), absence of external dependencies, and a design that prioritizes robustness: it never throws exceptions during termination, instead resolving with a `{success, code, message, error}` object. Unlike some alternatives, it guarantees termination by timing out if connections linger, and it avoids monkey-patching Node.js core APIs. The library is actively maintained, with recent updates ensuring compatibility with newer Node.js features like `server.closeIdleConnections()`.

Common errors

```
TypeError: lil_http_terminator_1.default is not a function
```
cause Attempting to import a CommonJS module that exports a function directly using an incorrect ESM named import syntax.

fix If using ESM, change `import { createHttpTerminator } from 'lil-http-terminator';` to `import createHttpTerminator from 'lil-http-terminator';`
```
TypeError: HttpTerminator is not a constructor
```
cause Trying to instantiate the factory function using the `new` keyword, which is not supported.

fix Call the `createHttpTerminator` function directly without `new`: `const terminator = createHttpTerminator({ server });`
```
Error: Cannot find module 'lil-http-terminator'
```
cause The package is not installed or the import path is incorrect.

fix Run `npm install lil-http-terminator` or `yarn add lil-http-terminator` to install the package. Verify the import statement is `require('lil-http-terminator')` or `import createHttpTerminator from 'lil-http-terminator'`.

Warnings

breaking Starting with version 1.2.3, `lil-http-terminator` requires Node.js version 12 or higher. Earlier Node.js versions are no longer supported due to the adoption of `server.closeIdleConnections()`.
Fix: Upgrade your Node.js runtime to version 12 or newer. For projects requiring older Node.js versions, use `lil-http-terminator@1.2.2`.
breaking Version 1.1.0 changed the API for `terminate()` to never throw exceptions. Instead, it now returns a Promise that resolves to an object `{ success: Boolean, code: String, message: String, error?: Error }` indicating the termination result.
Fix: Update your error handling logic. Instead of using `try/catch` blocks around `await terminator.terminate()`, inspect the `success` and `code` properties of the resolved object. Example: `const { success, code, message } = await terminator.terminate(); if (!success) console.error(message);`
gotcha Node.js's native `server.close()` method only stops new connections but keeps existing 'keep-alive' connections open indefinitely, potentially hanging your process. `lil-http-terminator` addresses this by actively tracking and terminating all connections after a configurable timeout.
Fix: Always use `await httpTerminator.terminate()` instead of `server.close()` when you need to shut down your server gracefully to ensure all connections are properly closed or destroyed.

Install

npm install lil-http-terminator npm
yarn add lil-http-terminator yarn
pnpm add lil-http-terminator pnpm

Imports

createHttpTerminator
wrong:
```
import { createHttpTerminator } from 'lil-http-terminator';
```
correct:
```
const createHttpTerminator = require('lil-http-terminator');
```
The module exports a factory function directly, not a named export. This is the correct CommonJS pattern.
createHttpTerminator
wrong:
```
const createHttpTerminator = require('lil-http-terminator').default;
```
correct:
```
import createHttpTerminator from 'lil-http-terminator';
```
For ESM projects, this default import syntax will generally work via Node.js's CJS-ESM interop. Avoid accessing `.default` explicitly for CommonJS modules in ESM.
terminator.terminate
wrong:
```
terminator.terminate(); // Missing await
```
correct:
```
await terminator.terminate();
```
The `terminate()` method returns a Promise; ensure you await its resolution to handle the shutdown result properly and prevent unintended process exits.

Quickstart

This quickstart demonstrates how to set up a basic HTTP server and integrate `lil-http-terminator` for graceful shutdown upon receiving SIGTERM or SIGINT signals, logging the termination result.

const http = require('http');
const createHttpTerminator = require('lil-http-terminator');

const server = http.createServer((req, res) => {
  console.log(`Request received: ${req.method} ${req.url}`);
  setTimeout(() => {
    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end('Hello from lil-http-terminator!\n');
  }, 500);
});

const httpTerminator = createHttpTerminator({
  server: server,
  gracefulTerminationTimeout: 1000,
  maxWaitTimeout: 5000,
  logger: console,
});

server.listen(3000, () => {
  console.log('Server listening on http://localhost:3000');
  console.log('Send SIGTERM or SIGINT to gracefully shut down.');
});

async function shutdown(signal) {
  console.log(`\nReceived ${signal}. Initiating graceful shutdown...`);
  const { success, code, message, error } = await httpTerminator.terminate();
  if (success) {
    console.log(`HTTP server closure successful.`);
  } else {
    console.error(`HTTP server closure failed: ${code} - ${message}`, error || '');
  }
  process.exit(success ? 0 : 1);
}

process.on('SIGTERM', shutdown); // Used by K8s, AWS ECS, etc.
process.on('SIGINT', shutdown);  // Atom, VSCode, WebStorm or Terminal Ctrl+C

view raw JSON →