nodejs

Build Node.js modules and services with async I/O, streams, package scripts, and deliberate process-lifecycle handling.

SKILL.md

GitHub

Node.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

  1. Prefer node: built-ins (node:fs/promises, node:http, native fetch).
  2. Set "type": "module" or explicit .mjs/.cjs—don't mix default imports blindly.
  3. Webhook routes: Register raw body parser before express.json() for Stripe path only.
  4. Handle unhandledRejection / uncaughtException with logging + controlled shutdown in production.
  5. Streams for large payloads; backpressure awareness.
  6. Pin "engines": { "node": ">=20" } and match CI.
  7. 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.
  • AbortController for 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 engines and CI. Never commit secrets.


Sources