claude-code-mastery-project-starter-kit: Skill for Claude Code

Node.js: Process Lifecycle and Runtime Rules

Claude writes Node services that work in a demo and fall over in production, almost always around the process lifecycle. These are the parts to get right.

Graceful shutdown, done correctly

A server must shut down cleanly on SIGTERM (what docker stop, Swarm, and Kubernetes send) and SIGINT (Ctrl-C). Claude usually omits this entirely, so the orchestrator waits the grace period and then SIGKILLs, dropping in-flight requests. The correct sequence is: stop accepting new connections, drain in-flight ones, close dependencies, exit 0, with a hard timeout so a stuck connection can't block shutdown forever.

const server = app.listen(port);
let shuttingDown = false;

async function shutdown(signal) {
  if (shuttingDown) return;                 // ignore repeat signals
  shuttingDown = true;
  logger.info("shutting down", { signal });

  const force = setTimeout(() => {           // drain hung? force it
    logger.error("shutdown timed out, forcing exit");
    process.exit(1);
  }, 10_000);
  force.unref();

  try {
    await new Promise((r) => server.close(r)); // stop new conns, let in-flight finish
    await db.close();                          // then close DB, redis, change streams
    clearTimeout(force);
    process.exit(0);
  } catch (err) {
    logger.error("error during shutdown", { err });
    process.exit(1);
  }
}

process.on("SIGTERM", () => shutdown("SIGTERM"));
process.on("SIGINT",  () => shutdown("SIGINT"));

Two things that look fine but are bugs: do not put async cleanup in a process.on("exit", ...) handler, the event loop is already stopped so nothing async runs, exit is for synchronous work only. And do not trap SIGUSR1, Node uses it for the debugger. This only works if the process actually receives the signal, which means an exec-form ENTRYPOINT so Node is PID 1 (see the docker skill) and init: true so signals are forwarded (see docker-swarm).

Let it crash, never swallow a fault