Graceful Shutdown Handler

The Graceful Shutdown Handler ensures that your Express application terminates safely and predictably when the process receives termination signals (like SIGTERM or SIGINT).

Installation Guide

Install the component using the servercn CLI:

npx servercn-cli add shutdown-handler

Why Graceful Shutdown Matters

When an application is restarted or stopped (e.g., during a deployment or scaling event), it's important to finish current work. Without graceful shutdown:

Active HTTP requests are abruptly terminated, leading to errors for users.
Database connections might be left in a "hanging" state.
Background tasks might be interrupted without saving progress.

Basic Implementation

src/utils/shutdown.ts

import { Server } from "http";
 
export const configureGracefulShutdown = (server: Server) => {
  const signals = ["SIGTERM", "SIGINT"];
 
  signals.forEach(signal => {
    process.on(signal, () => {
      console.log(`\n${signal} signal received. Shutting down gracefully...`);
 
      server.close(err => {
        if (err) {
          console.error("Error during server close:", err);
          process.exit(1);
        }
 
        console.log("HTTP server closed.");
        // Add additional cleanup logic here (e.g., closing database connections)
        process.exit(0);
      });
 
      // Force shutdown after 10 seconds
      setTimeout(() => {
        console.error(
          "Could not close connections in time, forcefully shutting down"
        );
        process.exit(1);
      }, 10000);
    });
  });
};

Usage

Import and apply the shutdown handler in your main entry file (usually server.ts).

src/server.ts

import http from "http";
import app from "./app";
import { configureGracefulShutdown } from "./utils/shutdown";
 
const server = http.createServer(app);
 
const PORT = process.env.PORT || 3000;
 
server.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});
 
// Apply graceful shutdown
configureGracefulShutdown(server);

Graceful Shutdown Handler

Installation Guide

Why Graceful Shutdown Matters

Basic Implementation

Usage

File & Folder Structure

Installation