{"id":16424,"library":"lil-http-terminator","title":"Graceful HTTP(S) Server Terminator","description":"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()`.","status":"active","version":"1.2.3","language":"javascript","source_language":"en","source_url":"https://github.com/flash-oss/lil-http-terminator","tags":["javascript","docker","kubernetes","prometheus","http","https","keep-alive","close","terminate"],"install":[{"cmd":"npm install lil-http-terminator","lang":"bash","label":"npm"},{"cmd":"yarn add lil-http-terminator","lang":"bash","label":"yarn"},{"cmd":"pnpm add lil-http-terminator","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The module exports a factory function directly, not a named export. This is the correct CommonJS pattern.","wrong":"import { createHttpTerminator } from 'lil-http-terminator';","symbol":"createHttpTerminator","correct":"const createHttpTerminator = require('lil-http-terminator');"},{"note":"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.","wrong":"const createHttpTerminator = require('lil-http-terminator').default;","symbol":"createHttpTerminator","correct":"import createHttpTerminator from 'lil-http-terminator';"},{"note":"The `terminate()` method returns a Promise; ensure you await its resolution to handle the shutdown result properly and prevent unintended process exits.","wrong":"terminator.terminate(); // Missing await","symbol":"terminator.terminate","correct":"await terminator.terminate();"}],"quickstart":{"code":"const http = require('http');\nconst createHttpTerminator = require('lil-http-terminator');\n\nconst server = http.createServer((req, res) => {\n  console.log(`Request received: ${req.method} ${req.url}`);\n  setTimeout(() => {\n    res.writeHead(200, { 'Content-Type': 'text/plain' });\n    res.end('Hello from lil-http-terminator!\\n');\n  }, 500);\n});\n\nconst httpTerminator = createHttpTerminator({\n  server: server,\n  gracefulTerminationTimeout: 1000,\n  maxWaitTimeout: 5000,\n  logger: console,\n});\n\nserver.listen(3000, () => {\n  console.log('Server listening on http://localhost:3000');\n  console.log('Send SIGTERM or SIGINT to gracefully shut down.');\n});\n\nasync function shutdown(signal) {\n  console.log(`\\nReceived ${signal}. Initiating graceful shutdown...`);\n  const { success, code, message, error } = await httpTerminator.terminate();\n  if (success) {\n    console.log(`HTTP server closure successful.`);\n  } else {\n    console.error(`HTTP server closure failed: ${code} - ${message}`, error || '');\n  }\n  process.exit(success ? 0 : 1);\n}\n\nprocess.on('SIGTERM', shutdown); // Used by K8s, AWS ECS, etc.\nprocess.on('SIGINT', shutdown);  // Atom, VSCode, WebStorm or Terminal Ctrl+C","lang":"javascript","description":"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."},"warnings":[{"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`.","message":"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()`.","severity":"breaking","affected_versions":">=1.2.3"},{"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);`","message":"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.","severity":"breaking","affected_versions":">=1.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"If using ESM, change `import { createHttpTerminator } from 'lil-http-terminator';` to `import createHttpTerminator from 'lil-http-terminator';`","cause":"Attempting to import a CommonJS module that exports a function directly using an incorrect ESM named import syntax.","error":"TypeError: lil_http_terminator_1.default is not a function"},{"fix":"Call the `createHttpTerminator` function directly without `new`: `const terminator = createHttpTerminator({ server });`","cause":"Trying to instantiate the factory function using the `new` keyword, which is not supported.","error":"TypeError: HttpTerminator is not a constructor"},{"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'`.","cause":"The package is not installed or the import path is incorrect.","error":"Error: Cannot find module 'lil-http-terminator'"}],"ecosystem":"npm"}