NodeJS

User preferences and memory live in ~/Clawic/data/nodejs/ (see setup.md on first use, memory-template.md for the file format). If you have data at an old location (~/nodejs/ or ~/clawic/nodejs/), move it to ~/Clawic/data/nodejs/.

When To Use

• Writing or reviewing Node services, CLIs, libraries, workers, or release scripts
• Debugging a live process: hangs, crash loops, growing RSS, slow endpoints, import failures, unclean shutdown
• Deciding the runtime shape of a package: ESM vs CJS, exports map, lockfile policy, native dependencies, publish surface
• Production incidents: intermittent 502s behind a proxy, EMFILE, event loop stalls, containers OOMKilled overnight
• Running TypeScript, tests, or child processes on Node — the runtime side, not the type system
• Not for browser-only JavaScript, TypeScript type design, or the Bun/Deno runtimes (each has its own skill)

Quick Reference

Depth on demand: debug.md symptom→cause chains · commands.md diagnostic toolkit · async.md event loop and promises · modules.md ESM/CJS · errors.md failure handling and shutdown · streams.md backpressure · http.md servers, clients, timeouts · performance.md profiling and leaks · concurrency.md workers, cluster, child processes · filesystem.md files, paths, descriptors · security.md hardening · testing.md suites and mocks · packages.md npm, lockfiles, publishing · typescript.md running TS on Node · runtime.md versions, flags, native modules · production.md deploy, config, logging, observability · cli.md command-line tools.

Core Rules

1. Budget sync work at ~10 ms per slice. Max throughput per process ≈ 1000 ms ÷ block_ms: a 50 ms sync JSON.parse in a request handler caps that process near 20 req/s, and every concurrent request inherits the stall. Repeatedly over budget → worker_threads; one-off → partition with setImmediate (→ async.md).
2. Handle operational errors, crash on programmer errors (Joyent doctrine). ECONNRESET, ENOENT, bad user input → handle at the call site. TypeError, undefined property → let it crash; the supervisor restarts a clean process. Catch-all recovery keeps corrupted state serving traffic.
3. "Async" fs, dns.lookup, crypto, and zlib share 4 libuv threads (default UV_THREADPOOL_SIZE; max 1024). The 5th concurrent fs.promises.readFile queues behind the first 4. Slow "async" crypto/fs under load → raise the pool to roughly the number of concurrent slow calls, or move the work off the process.
4. Cap concurrency explicitly. Promise.all(items.map(fetch)) over 10k items opens 10k sockets — EMFILE at the common 1024 fd soft limit. Batch or use a limiter; 8-32 concurrent per upstream host is a sane starting cap, raised on evidence: throughput climbing with flat latency = raise it; latency climbing = you found the ceiling.
5. keepAliveTimeout must exceed the proxy's idle timeout. Node's default is 5 s; ALB's default idle is 60 s, so Node closes sockets the balancer just reused → intermittent 502s. Formula: keepAliveTimeout = proxy_idle + 5 s and headersTimeout = keepAliveTimeout + 1 s (ALB 60 s → 65 s / 66 s; nginx upstream keepalive_timeout 75s → 80 s / 81 s).
6. Exact versions for apps, ranges for libraries; npm ci in anything automated. npm install rewrites the lockfile whenever package.json allows it — in CI that means testing an install nobody reviewed (→ packages.md).
7. One process per container. Let the orchestrator scale replicas; cluster only on bare metal or VMs you own entirely — two schedulers fighting over the same cores obscures both.
8. Set the heap ceiling below the memory limit. RSS = heap + buffers + stacks + native, so a default-sized heap under a container limit invites an OOMKill instead of a catchable heap error. Formula: --max-old-space-size = floor(0.75 × container_limit_MB) — 512 MB limit → 384; 2 GB → 1536. Exit 134 with FATAL ERROR: ... heap out of memory means you hit V8's ceiling; exit 137 means the kernel hit yours first.

Exit and Error Codes

Exit codes above 128 mean killed by signal code − 128; Node's own fatal codes sit below 10.

Error codes worth recognizing on sight: EADDRINUSE (port held), EMFILE/ENFILE (descriptor limit, rule 4), ECONNRESET (peer closed mid-flight — operational, rule 2), EPIPE (downstream closed a pipe), ERR_REQUIRE_ESM and ERR_MODULE_NOT_FOUND (format or extension), ERR_UNHANDLED_REJECTION (rule 2), ERR_STRING_TOO_LONG (V8 caps string length in the hundreds of MB — stream instead of JSON.stringify), ERR_CHILD_PROCESS_STDIO_MAXBUFFER (child output over the buffer cap).

Timeout Ladder

Every timeout in the path must be ordered, or one layer kills a connection another layer still believes in. Each line reads strictly larger left to right:

client abort  <  upstream call timeout  <  inbound requestTimeout
proxy idle    <  keepAliveTimeout       <  headersTimeout
force-exit backstop  <  orchestrator kill window

• Node HTTP server defaults (node >=18): keepAliveTimeout 5 s, headersTimeout 60 s, requestTimeout 300 s, server.timeout 0 (disabled). Only the first is short enough to bite by accident (rule 5).
• Outbound calls need their own deadline — an upstream that never answers holds a socket, a descriptor, and a request slot. AbortSignal.timeout(ms), with retries × per-try timeout still under requestTimeout.
• Shutdown backstop = orchestrator grace window − 5 s (Kubernetes terminationGracePeriodSeconds defaults to 30 s → force-exit at 25 s), so you exit on your own terms with logs flushed instead of by SIGKILL.

Version Gates

The canonical minimums this skill's guidance assumes. Check node -v before recommending anything above the user's line, and name the fallback when the target is older.

Release cadence, so "supported" stays checkable instead of remembered: one new major every April and October; even majors enter LTS that October and get ~3 years total (6 months Current, 12 Active LTS, 18 Maintenance); odd majors die after ~6 months and never belong in production. Which majors are live today: runtime.md (dated).

Output Gates

Before shipping Node code, verify:

• Any *Sync call, unbounded JSON.parse, or whole-array loop reachable from a request handler? (rule 1)
• Every Promise.all bounded by something other than user input? (rule 4)
• Every stream wired through pipeline() or carrying its own error handler — an unhandled stream error is a process crash?
• Every outbound call carrying a timeout or AbortSignal, and every server timeout ordered per the ladder?
• All process.env reads parsed and validated once at startup — they are strings or undefined, never numbers or booleans?
• Shutdown path present: SIGTERM → fail readiness → stop accepting → drain → close pools → exit, in that order (→ errors.md)?
• Heap ceiling set against the container limit (rule 8), and one process per container (rule 7)?

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/nodejs/config.yaml.

Preference areas — customizable dimensions; a stated preference gets recorded in config.yaml and applied:

• Tooling — script runner (node --run vs package-manager scripts), linter/formatter stack, profiler of choice — affects the shape of every command example
• Conventions — extensions (.mjs/.cjs vs a type field), error-class taxonomy, script names, folder layout, log field names
• Platform — OS (Windows path and spawn caveats), architecture (arm64 prebuilds), base image (musl vs glibc), registry mirror
• Thresholds — concurrency cap per upstream (rule 4), heap fraction (rule 8), timeout values, stream highWaterMark
• Risk posture — crash-vs-catch aggressiveness (rule 2), --ignore-scripts on install, automatic major bumps, permission model
• Output format — log shape (JSON vs pretty), verbosity, how much error detail reaches clients
• Work order — test-first vs code-first, profile-before-optimize, review gates before publish
• Integrations — registry, observability vendor, CI provider, process supervisor
• Constraints — banned dependencies, license policy, no-native-modules, offline or air-gapped installs
• Cadence — dependency update rhythm, Node upgrade rhythm against the April/October cadence

Traps

Where Experts Disagree

• Crash-and-restart vs catch-and-continue. Crash when a supervisor restarts you and in-process state may be corrupt; continue only for operational errors scoped to a single request. The boundary question: can you name exactly what stayed consistent?
• Dual CJS+ESM packages vs ESM-only. Dual carries the two-instance hazard (instanceof fails across copies, module state duplicates); ESM-only is viable once consumers are ESM or run node >=22.12, where require() of a sync ESM graph works.
• node:test vs Jest vs Vitest. node:test for new libraries — no transform layer, native ESM, no hoisting magic; Jest for existing suites with heavy matcher and snapshot use; Vitest where the project already runs a Vite pipeline. Migrating a green suite for aesthetics is a net loss.
• TypeScript at runtime vs a build step. Type stripping deletes the toolchain for apps deployed from source; a tsc build stays correct for published libraries that must ship .d.ts and support older consumers.

Related Skills

More Clawic skills, get them at https://clawic.com/skills/nodejs (install if the user confirms):

• javascript — language-level semantics: coercion, closures, dates, regex
• typescript — type-system design, tsconfig strictness, declaration files
• docker — containerizing the service, image layers, resource limits
• api — HTTP API design, versioning, and contracts above the runtime

Feedback

• If useful, star it: https://clawic.com/skills/nodejs
• Latest version: https://clawic.com/skills/nodejs

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/nodejs.