Skip to content

ericrisco/rsc-harness / skills/nodejs

nodejs

Verified

Use when building or operating a plain Node.js / Express 5 backend service: project layout, async correctness, central error middleware, fail-fast config, graceful shutdown on SIGTERM. NOT DI modules/providers/guards (that is `nestjs`), NOT the type system or tsconfig (that is `typescript`), NOT REST contract design (that is `api-design`).

FileKindSize
SKILL.mdskill md12.5 KB
evals/README.mdmarkdown732 B
evals/cases.yamlconfig2.7 KB
references/express5-migration.mdmarkdown2.7 KB
references/graceful-shutdown.mdmarkdown3.0 KB
scripts/verify.shexecutablescript4.3 KB

references/graceful-shutdown.md

View on GitHub
# Graceful shutdown — complete server.ts

Copy-pasteable. Threads an `AbortController` so in-flight long ops are cancelled, gates readiness so the load balancer stops routing before drain, and keeps a force-exit backstop so a stuck connection can't hang the deploy. Sources: AbortController guides (AppSignal 2025-02-12, BetterStack), Node SIGTERM semantics (accessed 2026-06-02).

## Why a readiness gate, not just `server.close()`

`server.close()` stops accepting *new* connections but in-flight requests keep going. If the load balancer is still routing new traffic at you while you close, those new connections are refused. So you flip `/readyz` to 503 *first*, give the LB a moment to deregister, then close. `/healthz` stays 200 the whole time — the process is alive, just draining.

```ts
// server.ts
import { buildApp } from "./app.ts";
import { config } from "./config/env.ts";
import { logger } from "./logger.ts";
import { closePool } from "./repositories/pool.ts";

let ready = true;
const controller = new AbortController(); // pass controller.signal into fetch/DB/long ops

const app = buildApp();
app.get("/healthz", (_req, res) => res.json({ status: "up" }));        // liveness
app.get("/readyz", (_req, res) =>                                       // readiness
  ready ? res.json({ status: "ready" }) : res.status(503).json({ status: "draining" }),
);

const server = app.listen(config.PORT, () =>
  logger.info({ port: config.PORT }, "listening"),
);

let shuttingDown = false;
async function shutdown(signal: string) {
  if (shuttingDown) return;            // ignore a second signal
  shuttingDown = true;
  logger.info({ signal }, "shutting down");

  ready = false;                       // 1. /readyz → 503, LB deregisters

  const backstop = setTimeout(() => {  // 5. backstop: never hang the deploy
    logger.error("drain timed out, forcing exit");
    process.exit(1);
  }, 10_000);
  backstop.unref();

  server.close(async () => {           // 2. stop accepting; wait for in-flight
    controller.abort();                // 3. cancel long-running ops
    await closePool();                 // 4. release DB/other resources
    clearTimeout(backstop);
    logger.info("clean exit");
    process.exit(0);
  });
}

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

// last-resort: log and exit, never keep running on a detached failure
process.on("unhandledRejection", (reason) => {
  logger.error({ reason }, "unhandled rejection");
  void shutdown("unhandledRejection");
});
```

## Threading the signal into work

The `AbortController` only helps if operations actually receive `controller.signal`:

```ts
// in a repository / service
const res = await fetch(url, { signal: controller.signal });
// or compose a per-request deadline with a shutdown abort:
const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(5_000)]);
```

`AbortSignal.timeout(ms)` returns an auto-aborting signal; `AbortSignal.any([...])` aborts when any input aborts — so the op dies on either the 5s deadline or process shutdown.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall