nodejs
Build Node.js modules and services with async I/O, streams, package scripts, and deliberate process-lifecycle handling.
SKILL.mdskills/nodejs/SKILL.md
GitHubNode.js Runtime AI Skill Guide (Claude)
Overview & Engine Architecture
Node.js runs JavaScript on a single-threaded event loop with libuv thread pool for I/O. Worker threads and child processes handle CPU-bound work. Agents pin engines, choose ESM vs CJS deliberately, and never block the loop on sync filesystem or heavy JSON on hot paths.
Claude operates as a Principal Node Engineer: raw webhook bodies, AbortController timeouts, structured logging, and process lifecycle.
HTTP / CLI entry
│
event loop (timers, I/O, microtasks)
│
worker_threads / child_process (CPU)
When to use / when not to
Use when
- Lightweight HTTP APIs, webhooks, and integration glue.
- Streaming uploads/downloads without loading full bodies into RAM.
- Tooling and build scripts in the same repo as frontend.
Do not use when
- CPU-heavy batch jobs should run in Python/Rust workers or a queue—not the API process.
- Team has standardized on Bun/Deno—verify API compatibility per runtime.
Operational Capabilities & Agent Directives
- Prefer
node:built-ins (node:fs/promises,node:http, nativefetch). - Set
"type": "module"or explicit.mjs/.cjs—don't mix default imports blindly. - Webhook routes: Register raw body parser before
express.json()for Stripe path only. - Handle
unhandledRejection/uncaughtExceptionwith logging + controlled shutdown in production. - Streams for large payloads; backpressure awareness.
- Pin
"engines": { "node": ">=20" }and match CI. - Idempotency for payment webhooks at DB layer—see
@stripe.
Minimal ESM HTTP server
import http from "node:http";
const port = Number(process.env.PORT ?? 3000);
const server = http.createServer(async (req, res) => {
if (req.method === "GET" && req.url === "/health") {
res.writeHead(200, { "content-type": "application/json" });
res.end(JSON.stringify({ ok: true }));
return;
}
res.writeHead(404);
res.end();
});
server.listen(port, () => console.log(`listening on ${port}`));
Express Stripe webhook ordering:
app.post("/webhooks/stripe", express.raw({ type: "application/json" }), handler);
app.use(express.json()); // after webhook route
Technical Troubleshooting Matrix
| Pitfall | Why it hurts | Fix |
|---|---|---|
Sync fs.readFileSync in handler |
Event loop stall | Async + streams |
| JSON parser before Stripe verify | Signature failure | Raw route first |
Missing await |
Silent failures | Lint; global rejection handler |
| Memory spike | Buffer entire upload | Stream to disk/S3 |
| Version skew | Native API differences | Pin engines in CI |
Best practices
- Validate env at boot (zod/envalid).
- Structured JSON logs + request IDs.
AbortControllerfor fetch timeouts.- Graceful shutdown: stop accepting, drain connections, exit.
Limitations
- Single-threaded JS—not for heavy parallel CPU without workers.
- Native addons complicate cross-platform CI.
- Bun/Deno APIs differ—don't assume Node-only snippets run everywhere.
Related skills
@express— middleware ordering for webhooks@stripe— constructEvent on Buffer@typescript— typed Node services@docker— container NODE_ENV and signals
Agent Operational Directive
MANDATORY: For signed webhooks, preserve exact raw body bytes through verification. Register body parsers so they cannot mutate webhook routes. Pin Node version in
enginesand CI. Never commit secrets.