ericrisco/rsc-harness / skills/nodejs
nodejs
VerifiedUse 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`).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.5 KB |
| evals/README.md | markdown | 732 B |
| evals/cases.yaml | config | 2.7 KB |
| references/express5-migration.md | markdown | 2.7 KB |
| references/graceful-shutdown.md | markdown | 3.0 KB |
| scripts/verify.shexecutable | script | 4.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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |