{"slug":"nodejs","title":"nodejs","summary":"Write and review Node.js: the module system, package manifest, streams, event loop, process and worker lifecycle, the permission model, native TypeScript execution, `node:test`, and the runtime version `engines.node` permits.","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-11-10T18:27:22.556143Z","repo":{"url":"https://github.com/xobotyi/cc-foundry","stars":23,"forks":2,"license":"MIT","updatedAt":"2026-11-10T17:16:40Z"},"bodyHtml":"<hr>\n<h2>name: nodejs\ndescription: &gt;-\nWrite and review Node.js: the module system, package manifest, streams, event loop, process and worker lifecycle,\nthe permission model, native TypeScript execution, <code>node:test</code>, and the runtime version <code>engines.node</code> permits.\nwhen_to_use: &gt;-\nInvoke whenever Node.js runtime code is touched at all — writing, reviewing, refactoring, or debugging a server, a\nCLI, a script, or a <code>package.json</code>, and whenever a project's Node floor is raised. Also invoke on the symptoms:\n<code>ERR_REQUIRE_ESM</code>, <code>ERR_REQUIRE_ASYNC_MODULE</code>, or <code>ERR_MODULE_NOT_FOUND</code>; an import that resolves in the bundler and\nnot in Node; a <code>.ts</code> file Node refuses to run; a process that hangs at exit or dies with no stack; a stream that\nbuffers without bound; a leaked HTTP connection; <code>ERR_ACCESS_DENIED</code>; a <code>node:test</code> mock or fake timer that does not\ntake effect; or a flag that works on one Node major and not the next. Covers the Node runtime and <code>node:test</code>;\nJavaScript semantics belong to the javascript skill, types to typescript, the Bun runtime to bun, and Vitest to\nvitest.\ncompatibility: Uses Claude Code frontmatter beyond the Agent Skills spec (when_to_use)</h2>\n<p>One thread runs every callback in a Node process, so anything that holds it holds the whole program. Three biases decide\nmost calls:</p>\n<ul>\n<li><strong>The <code>engines.node</code> floor decides what may be written</strong>, not the <code>node</code> binary on the machine.</li>\n<li><strong>Read an API's stability index before depending on it.</strong> Node ships an API for years before committing to it, and an\nexperimental one can be deleted without a deprecation cycle.</li>\n<li><strong>Check the standard library before adding a dependency.</strong> It absorbed <code>fetch</code>, a test runner, a file watcher, <code>glob</code>,\nSQLite, <code>.env</code> parsing, a script runner, and TypeScript execution.</li>\n</ul>\n<h2>Node Version</h2>\n<p><code>engines.node</code> in <code>package.json</code> is the floor a project claims. Read it before writing code and never reach for an API\nabove it. Nothing enforces it at run time — Node never reads the field, and npm checks it only under\n<code>engine-strict=true</code> — so the floor holds by discipline and by CI running the oldest major it names.</p>\n<p><strong>The installed binary is not the floor.</strong> <code>node --version</code> reports what one machine has, not what the project supports.</p>\n<p>Support windows, which decide whether a floor is defensible:</p>\n<ul>\n<li><strong>20</strong> — end of life 2026-04-30. A floor of <code>&gt;=20</code> claims a runtime that receives no fixes at all.</li>\n<li><strong>22</strong> — maintenance from 2025-10-21, end of life 2027-04-30. Security and critical fixes only; no new capability.</li>\n<li><strong>24</strong> — Active LTS from 2025-10-28, maintenance from 2026-10-20, end of life 2028-04-30.</li>\n<li><strong>26</strong> — released 2026-05-05, Active LTS from 2026-10-28, end of life 2029-04-30.</li>\n</ul>\n<p>Floor version per feature — the APIs and behavior changes that decide what may be written.</p>\n<ul>\n<li><strong>20.19.0</strong> — <code>require(esm)</code> unflagged on the 20 line; syntax detection on by default</li>\n<li><strong>22.0.0</strong> — <code>node --run</code>; <code>fs.glob</code>; <code>WebSocket</code> global; watch mode Stable; <code>assert { type: 'json' }</code> removed</li>\n<li><strong>22.12.0</strong> — <code>require(esm)</code> unflagged on the 22 line; JSON modules Stable</li>\n<li><strong>22.13.0</strong> — Permission Model Stable and <code>--permission</code> accepted; <code>node:sqlite</code> unflagged</li>\n<li><strong>22.15.0</strong> — <code>module.registerHooks()</code></li>\n<li><strong>22.16.0</strong> — <code>import.meta.dirname</code> and <code>import.meta.filename</code> Stable; <code>--experimental-config-file</code></li>\n<li><strong>22.18.0</strong> — type stripping on by default; <code>import.meta.main</code></li>\n<li><strong>22.21.0</strong> — <code>--env-file</code> Stable; <code>NODE_USE_ENV_PROXY</code></li>\n<li><strong>24.0.0</strong> — <code>--experimental-permission</code> renamed <code>--permission</code>; <code>AsyncLocalStorage</code> on <code>AsyncContextFrame</code>;\n<code>URLPattern</code> global; test runner awaits subtests; <code>url.parse()</code> runtime-deprecated (DEP0169); <code>args</code> with\n<code>{ shell: true }</code> runtime-deprecated (DEP0190)</li>\n<li><strong>24.12.0</strong> — type stripping Stable</li>\n<li><strong>24.20.0</strong> — <code>--permission-audit</code></li>\n<li><strong>26.0.0</strong> — <code>Temporal</code> global; <code>module.register()</code> runtime-deprecated (DEP0205); <code>--experimental-transform-types</code>\nremoved; <code>node:_stream_*</code> removed. It also inherits what 25 added and neither 22 nor 24 received: <code>--allow-net</code>, and\nwith it network confinement under <code>--permission</code></li>\n<li><strong>26.3.0</strong> — <code>permission.drop()</code></li>\n</ul>\n<p><strong>No odd major is a defensible floor.</strong> Node 21, 23, and 25 are end of life — 25 since 2026-06-01 — so a feature that\narrived on one is reachable only from the LTS major above it.</p>\n<p>Read [<code>${CLAUDE_SKILL_DIR}/references/versions/node-NN.md</code>] — one file per LTS major: <code>node-20.md</code>, <code>node-22.md</code>,\n<code>node-24.md</code>, <code>node-26.md</code> — when writing against a feature near the floor, and whenever raising the floor. Each carries\nwhat its major added, the stability each addition holds, the behavior it changed, and the traps it introduced.</p>\n<h2>Stability Index</h2>\n<p>Every documented API carries one, and it decides how the API may be used, not merely how finished it is.</p>\n<ul>\n<li><strong>2 - Stable</strong> — protected by semver. Safe in a published library's surface.</li>\n<li><strong>1 - Experimental</strong> — outside semver, and the level most unfinished APIs print. Three subdivisions refine it: <strong>1.2 -\nRelease candidate</strong>, where no further breaking change is anticipated but none is ruled out; <strong>1.1 - Active\ndevelopment</strong>, nearing minimum viability; <strong>1.0 - Early development</strong>, unfinished and expecting substantial change.</li>\n<li><strong>3 - Legacy</strong> — semver-protected and unmaintained. Bugs in it are not fixed. Migrate rather than report.</li>\n<li><strong>0 - Deprecated</strong> — carries a DEP number and a migration.</li>\n</ul>\n<p>What follows from the index:</p>\n<ul>\n<li><strong>An experimental API can be removed with no deprecation cycle.</strong> <code>--experimental-transform-types</code> shipped in 22.7.0\nand was deleted in 26.0.0, taking the runtime path for TypeScript enums with it.</li>\n<li><strong>Never put an experimental API in a published library's public surface.</strong> A consumer cannot see that the risk was\ntaken on their behalf.</li>\n<li><strong>The index moves per major.</strong> <code>TracingChannel</code> is Stable from 26.8.0 and experimental on 24; <code>module.register()</code> is\nsupported on 24 and runtime-deprecated on 26. State the index for the floor, not for the machine.</li>\n<li><strong>Check the index rather than the flag.</strong> Type stripping needs no flag from 22.18.0 and was not Stable until 24.12.0;\nan unflagged feature is not a committed one.</li>\n</ul>\n<h2>Module System</h2>\n<ul>\n<li><strong>Declare <code>\"type\"</code> in every <code>package.json</code>.</strong> Without it, a <code>.js</code> or extensionless file is parsed as CommonJS and\nre-parsed as an ES module when that fails. The retry costs startup time on every ES module and turns a real syntax\nerror into a confusing module-system error.</li>\n<li><strong><code>.mjs</code> and <code>.cjs</code> override <code>\"type\"</code>; nothing overrides them.</strong> Use them to place one file of the other kind inside a\npackage, never as the default.</li>\n<li><strong>Node's resolver performs no extension search and no directory-index lookup.</strong> It loads the specifier as written, so\n<code>./startup</code> resolves in a bundler and throws <code>ERR_MODULE_NOT_FOUND</code> here.</li>\n<li><strong>Import a builtin through <code>node:</code></strong> — <code>import fs from 'node:fs/promises'</code>. The prefix cannot be shadowed by a package\nof the same name, and <code>node:test</code> and <code>node:sqlite</code> resolve under no other specifier.</li>\n<li><strong><code>import.meta.dirname</code> and <code>import.meta.filename</code> replace <code>__dirname</code> and <code>__filename</code></strong>, and exist only on <code>file:</code>\nmodules.</li>\n<li><strong>The <code>assert</code> import-attribute form was removed in 22.0.0 and throws.</strong> Only <code>with</code> parses.</li>\n<li><strong><code>require()</code> of an ES module works</strong> from 20.19.0 and 22.12.0, and throws <code>ERR_REQUIRE_ASYNC_MODULE</code> when anything in\nthe graph uses top-level <code>await</code>. That is a property of the whole graph, so a transitive dependency can break a caller\nthat did not change.</li>\n<li><strong>Reach for <code>module.registerHooks()</code>, not <code>module.register()</code>.</strong> The latter is runtime-deprecated in 26.0.0 (DEP0205)\nand needs <code>--allow-worker</code> under the Permission Model, because its hooks run on a worker thread.</li>\n</ul>\n<p>Read [<code>${CLAUDE_SKILL_DIR}/references/conventions/modules.md</code>] when a specifier resolves in a bundler and not in Node,\nwhen writing a loader hook, or when repeated start-up cost is worth caching — it carries what decides a file's module\nsystem, the specifier rules, the two hook APIs, and the compile cache.</p>\n<h2>Package Manifest</h2>\n<ul>\n<li><strong><code>\"exports\"</code> seals the package.</strong> Once present, nothing outside the map is importable, deep relative paths included.\nAdd it deliberately: it is the only way to keep internals private, and adding it to a published package is a breaking\nchange.</li>\n<li><strong>Condition order in the map is the match order.</strong> Earlier keys win, so write the most specific first.</li>\n<li><strong><code>\"default\"</code> goes last and <code>\"types\"</code> first.</strong> <code>\"default\"</code> matches every caller, and <code>\"types\"</code> is a convention of the\ntype systems rather than a condition Node reads.</li>\n<li><strong><code>\"import\"</code> and <code>\"require\"</code> describe the caller's syntax, not the target's format.</strong> A <code>.mjs</code> file behind <code>\"require\"</code>\nis legal and loads through <code>require(esm)</code>.</li>\n<li><strong>Use <code>\"module-sync\"</code> instead of a dual build</strong> where one ES module must serve both callers. Two builds of one package\ngive a process two class identities and two copies of every module-level singleton.</li>\n<li><strong><code>\"imports\"</code> keys start with <code>#</code></strong> and are the only path-alias mechanism that survives <code>node file.ts</code>, because\nnothing in the runtime reads <code>tsconfig.json</code>.</li>\n<li><strong>Every <code>\"exports\"</code> target starts with <code>./</code>.</strong> Absolute paths, <code>file:</code> URLs, <code>../</code>, and any <code>.</code>, <code>..</code>, or\n<code>node_modules</code> segment are rejected with <code>ERR_INVALID_PACKAGE_TARGET</code>.</li>\n</ul>\n<p>Read [<code>${CLAUDE_SKILL_DIR}/references/conventions/modules.md</code>] when designing an <code>\"exports\"</code> map or publishing a package\nthat must serve both <code>require</code> and <code>import</code> — it carries the condition-matching rules, the target-path restrictions, and\nthe dual-package hazard.</p>\n<h2>TypeScript Execution</h2>\n<p>Node erases type syntax and runs the result. It does not compile, does not type-check, and does not read\n<code>tsconfig.json</code>.</p>\n<ul>\n<li><strong>Keep the project's type-check command in the verification path.</strong> Running a <code>.ts</code> file proves it parses, nothing\nmore.</li>\n<li><strong><code>import type</code> is mandatory for type-only imports.</strong> Erasure is syntactic: without the keyword the import survives as\na value import and fails at run time. <code>verbatimModuleSyntax: true</code> makes <code>tsc</code> enforce it.</li>\n<li><strong>Write the real extension in the specifier</strong> — <code>import './x.ts'</code>, and <code>require('./x.ts')</code> in CommonJS. Node loads the\nfile that exists; it does not rewrite <code>.js</code> to <code>.ts</code>.</li>\n<li><strong>Enums, <code>namespace</code> with runtime code, parameter properties, and import aliases raise\n<code>ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX</code>.</strong> <code>--experimental-transform-types</code> handled some of them and was removed in\n26.0.0. Set <code>erasableSyntaxOnly: true</code> so the compiler rejects them first.</li>\n<li><strong>A decorator fails as a bare <code>SyntaxError</code> instead</strong>, with no <code>code</code> to match on — measured on 26.2.0. The parser\nrejects the <code>@</code> before type stripping runs.</li>\n<li><strong>A dependency shipping <code>.ts</code> files cannot be loaded.</strong> Node refuses TypeScript under any <code>node_modules</code> path,\ndeliberately and at every version.</li>\n</ul>\n<p>Read [<code>${CLAUDE_SKILL_DIR}/references/conventions/typescript-execution.md</code>] when a <code>.ts</code> file fails to run, when\nchoosing between type stripping and a compiler, or when writing the <code>tsconfig.json</code> that matches the runtime — it\ncarries the flag history, the full refused-syntax list, and the matching compiler options.</p>\n<h2>Blocking</h2>\n<ul>\n<li><strong>No synchronous file, process, or crypto call on a request path.</strong> <code>readFileSync</code>, <code>execSync</code>, <code>pbkdf2Sync</code>,\n<code>inflateSync</code> belong in CLIs, build scripts, and startup code that runs before the server listens.</li>\n<li><strong>Bound every input before parsing it.</strong> <code>JSON.parse</code> is synchronous and scales with input size, so an unbounded body\nis a denial of service that needs no bug.</li>\n<li><strong>Never match a backtracking pattern against user input.</strong> Nested quantifiers, overlapping alternations, and\nbackreferences with repetition give one request the whole thread. Use <code>indexOf</code> or a linear engine.</li>\n<li><strong>Recursive <code>process.nextTick</code> starves I/O.</strong> The tick queue drains to exhaustion before the loop advances, so a\nself-scheduling <code>nextTick</code> stops the process serving traffic while looking idle. <code>queueMicrotask</code> has the same\nproperty one level down.</li>\n<li><strong><code>setImmediate</code> beats <code>setTimeout(fn, 0)</code> inside an I/O callback and races it at the top level.</strong> Never encode either\nordering as a dependency.</li>\n<li><strong>Partition long synchronous loops</strong> with <code>setImmediate</code> between chunks, or move them to a worker.</li>\n</ul>\n<p>Read [<code>${CLAUDE_SKILL_DIR}/references/conventions/concurrency.md</code>] when a process stops serving traffic while looking\nidle, or when one slow operation surfaces as an unrelated failure — it carries the loop phase order and the list of work\nthat shares the libuv thread pool.</p>\n<h2>Streams</h2>\n<ul>\n<li><strong>Compose with <code>pipeline</code> from <code>node:stream/promises</code>.</strong> A <code>.pipe()</code> chain propagates neither errors nor destruction,\nso one failure leaves the rest of the chain open with its descriptors held.</li>\n<li><strong>Respect the return value of <code>write()</code>.</strong> <code>false</code> means the buffer is over <code>highWaterMark</code>; keep writing and memory\ngrows without any error being raised. <code>pipeline</code> and <code>for await</code> handle this.</li>\n<li><strong><code>highWaterMark</code> is a threshold, not a cap.</strong> A single write larger than it still buffers in full, and in object mode\nthe count is objects rather than bytes.</li>\n<li><strong>Destroy a stream on the error path.</strong> <code>stream.destroy(err)</code> releases the descriptor or socket; an undestroyed stream\nleaks it.</li>\n<li><strong>An unhandled <code>'error'</code> event crashes the process.</strong> Every stream outside a <code>pipeline</code> needs a listener.</li>\n<li><strong><code>readable.map</code>, <code>filter</code>, <code>take</code>, <code>reduce</code> and the rest are Experimental</strong>, on every major through 26. They read\nlike committed API and are not. Keep them out of a library's surface.</li>\n<li><strong>Do not stream data already in memory.</strong> Streams earn their cost on unbounded or arriving-over-time input.</li>\n</ul>\n<p>Read [<code>${CLAUDE_SKILL_DIR}/references/conventions/streams.md</code>] when crossing between Node streams and web streams, when\nwriting a custom <code>Readable</code>, <code>Writable</code>, or <code>Transform</code>, or when tuning <code>highWaterMark</code> — it carries the interop matrix,\nthe platform-dependent defaults, and the whole-stream consumers.</p>\n<h2>Errors and Exit</h2>\n<ul>\n<li><strong>Set <code>process.exitCode</code> and let the loop drain.</strong> <code>process.exit()</code> terminates immediately, and a write to a pipe or a\nsocket may still be in flight — measured on 26.2.0/macOS, 512 KiB written to a pipe arrives as 64 KiB. A write to a\nfile is synchronous and survives, which is why the loss reads as intermittent.</li>\n<li><strong>Match on <code>error.code</code>, never on the message.</strong> Every built-in error carries one; messages change between minors.</li>\n<li><strong><code>util.inspect</code> renders a <code>cause</code> chain</strong>, so an error chained with <code>{ cause: err }</code> reaches a Node logger intact\nwithout the caller unwrapping it.</li>\n<li><strong>Never resume after <code>'uncaughtException'</code>.</strong> Installing the listener disables the crash and leaves the process\nrunning with unknown state. Log, flush, exit.</li>\n<li><strong>An unhandled rejection is fatal by default.</strong> Do not add <code>--unhandled-rejections=warn</code> to make a test suite pass.</li>\n<li><strong><code>'exit'</code> listeners run synchronously only.</strong> Anything asynchronous scheduled there never runs.</li>\n<li><strong>Cancel with <code>AbortSignal</code>.</strong> <code>fetch</code>, <code>fs/promises</code>, <code>timers/promises</code>, <code>pipeline</code>, <code>stream.addAbortSignal</code>, and\n<code>events.on</code> all take <code>{ signal }</code>.</li>\n<li><strong>A cancelled call does not report itself the same way twice.</strong> Node's own APIs reject with an <code>AbortError</code> carrying\n<code>code: 'ABORT_ERR'</code>; <code>fetch</code> rejects with a <code>DOMException</code> whose <code>code</code> is the number <code>20</code>; and a <code>fetch</code> deadline\nbuilt from <code>AbortSignal.timeout(ms)</code> rejects with <code>name === 'TimeoutError'</code>, not <code>'AbortError'</code> — measured on 26.2.0.\nTest <code>signal.aborted</code> where the signal is in scope, and <code>err.name === 'AbortError' || err.name === 'TimeoutError'</code>\nwhere it is not.</li>\n<li><strong>Set the HTTP server timeouts.</strong> <code>requestTimeout</code> defaults to 300000 ms and <code>keepAliveTimeout</code> to 5000 ms; the latter\nmust be shorter than the idle timeout of any proxy in front, or the proxy reuses a socket Node has closed.</li>\n</ul>\n<p>Read [<code>${CLAUDE_SKILL_DIR}/references/conventions/lifecycle.md</code>] when writing a graceful shutdown, when a process\nrefuses to exit or exits without flushing, or when auditing server timeouts — it carries the shutdown sequence, the\ndeprecation flags, and the timeout defaults.</p>\n<h2>Async Context and Diagnostics</h2>\n<ul>\n<li><strong><code>run(store, fn)</code> is the only Stable way to enter a store.</strong> <code>enterWith</code> and <code>withScope</code> are Experimental, and\n<code>enterWith</code> applies for the rest of the current synchronous execution rather than for a scope — called inside one\nevent handler it leaks into every later handler on the same emit.</li>\n<li><strong>Instrument with <code>diagnostics_channel</code>, not with a logger call.</strong> Publishing to a channel with no subscriber costs\nnothing measurable, so the instrumentation can ship enabled.</li>\n<li><strong>Create a channel once at module top level</strong> and guard expensive payload construction with <code>channel.hasSubscribers</code>.</li>\n<li><strong>Subscribers receive the message object by reference.</strong> A subscriber that mutates it changes what the publisher and\nlater subscribers see.</li>\n<li><strong>Measure loop lag with <code>perf_hooks.monitorEventLoopDelay()</code></strong>, not with a <code>setTimeout</code> drift estimate.</li>\n<li><strong>Get a stack out of a native crash with <code>--report-on-fatalerror</code>.</strong> No JavaScript handler runs at that point.</li>\n</ul>\n<p>Read [<code>${CLAUDE_SKILL_DIR}/references/conventions/observability.md</code>] when context goes missing across an async boundary,\nwhen adding tracing to a library, or when picking a profiling flag — it carries the context-loss diagnosis, the\n<code>TracingChannel</code> contract, and the list of channels Node publishes itself.</p>\n<h2>HTTP Client</h2>\n<ul>\n<li><strong>Consume or cancel every response body</strong>, on the error path too. undici does not release the connection until the\nbody is read or cancelled, and the garbage collector is not prompt enough to save it — a pool exhausted this way\nstalls rather than errors.</li>\n<li><strong><code>fetch</code> does not reject on a non-2xx status.</strong> Check <code>res.ok</code>.</li>\n<li><strong><code>fetch</code> has no total timeout.</strong> Pass <code>signal: AbortSignal.timeout(ms)</code>, combined with the caller's signal through\n<code>AbortSignal.any</code>.</li>\n<li><strong><code>http.Agent</code> options do not reach <code>fetch</code>.</strong> It uses undici's global dispatcher; change it with a <code>dispatcher</code>\noption per request or <code>setGlobalDispatcher</code> process-wide.</li>\n<li><strong><code>fetch</code> ignores <code>HTTP_PROXY</code> unless told otherwise</strong> — <code>NODE_USE_ENV_PROXY=1</code> or <code>--use-env-proxy</code>, from 22.21.0 and\n24.5.0.</li>\n<li><strong>Drop to <code>node:http</code> for upgrades, <code>CONNECT</code>, trailers, or per-request agent control</strong>, and to <code>node:http2</code> for\nHTTP/2, which <code>fetch</code> does not speak.</li>\n</ul>\n<p>Read [<code>${CLAUDE_SKILL_DIR}/references/conventions/http-client.md</code>] when tuning connection pooling, or when deciding\nbetween <code>fetch</code> and <code>node:http</code> — it carries the dispatcher model and the undici version each Node major embeds.</p>\n<h2>Workers and Processes</h2>\n<ul>\n<li><strong>Workers are for CPU work.</strong> Node's asynchronous I/O beats a worker at I/O, and each worker carries a full V8\nisolate.</li>\n<li><strong>Size a pool from <code>os.availableParallelism()</code>.</strong> <code>os.cpus().length</code> ignores CPU affinity and container limits.</li>\n<li><strong><code>--max-old-space-size</code> is per isolate.</strong> Every worker adds its own heap, so the container limit must cover the sum.</li>\n<li><strong>A worker receives no signals.</strong> The main thread must tell its workers to stop and wait for them, and\n<code>process.exit()</code> inside a worker ends only that thread.</li>\n<li><strong>A worker does not inherit the Permission Model.</strong></li>\n<li><strong><code>process.env</code> in a worker is a copy</strong> unless the <code>Worker</code> was constructed with <code>env: SHARE_ENV</code>.</li>\n<li><strong>Never pass an argument array together with <code>{ shell: true }</code>.</strong> <code>spawn</code> and <code>execFile</code> join it with spaces without\nescaping, which is command injection — runtime-deprecated as DEP0190 in 24.0.0.</li>\n<li><strong>Raise <code>UV_THREADPOOL_SIZE</code> in the environment, not in the program.</strong> The pool is built during initialization, so\nassigning <code>process.env.UV_THREADPOOL_SIZE</code> at run time does nothing.</li>\n</ul>\n<p>Read [<code>${CLAUDE_SKILL_DIR}/references/conventions/concurrency.md</code>] when building a worker pool, or when choosing between\n<code>worker_threads</code>, <code>child_process</code>, and <code>cluster</code> — it carries how data crosses a thread boundary and the full list of\nbehavior differences inside a worker.</p>\n<h2>Permission Model</h2>\n<ul>\n<li><strong><code>--permission</code> is a seat belt, not a sandbox.</strong> Node's own documentation states it does not protect against\nmalicious code. Never present it to a reviewer as containment for untrusted input.</li>\n<li><strong>It does not restrict the network below 25.0.0.</strong> <code>--allow-net</code> does not exist on the 22 and 24 lines, so a process\nconfined there still opens any socket it likes.</li>\n<li><strong>Symlinks are followed out of the granted set.</strong> A relative link inside a granted directory reaches any path.</li>\n<li><strong>An already-open file descriptor is never checked</strong>, including one inherited from the parent process.</li>\n<li><strong>A granted directory that exists gets an implicit <code>/*</code>; one that does not, does not.</strong> Write the wildcard explicitly\nwhen the directory is created at run time.</li>\n<li><strong>Derive the grant list with <code>--permission-audit</code></strong> (24.20.0) before enforcing. It publishes every violation to a\n<code>node:permission-model:*</code> channel and denies nothing.</li>\n</ul>\n<p>Read [<code>${CLAUDE_SKILL_DIR}/references/conventions/permissions.md</code>] when confining a process, when a run fails with\n<code>ERR_ACCESS_DENIED</code>, or when writing the grant list — it carries the full scope-to-flag map, the path-matching rules,\nand everything the model does not cover.</p>\n<h2>Supply Chain</h2>\n<ul>\n<li><strong><code>npm ci</code> in CI and in image builds.</strong> It requires a lockfile, removes <code>node_modules</code> first, and fails rather than\nrewriting the lockfile when it disagrees with <code>package.json</code>.</li>\n<li><strong>Set <code>ignore-scripts=true</code> in <code>.npmrc</code>.</strong> Lifecycle scripts run for the whole dependency tree with the runner's\nprivileges, and this is where almost all registry compromise lands. Re-enable it per package where a build genuinely\nneeds it.</li>\n<li><strong>Set <code>min-release-age</code> to a window in days</strong> (npm 11.10.0). A compromised-account attack publishes a version that is\nminutes old, and the window is what blocks it. When no version of a dependency clears the window the command errors,\nso treat that exit as a signal rather than a reason to remove the setting. The <code>min-release-age-exclude</code> escape hatch\nneeds npm 12.0.0, which no Node line bundles.</li>\n<li><strong>Publish from CI over OIDC trusted publishing</strong>, not with a token. npm classic tokens were revoked on 2025-12-09, and\na granular token with <code>Bypass 2FA</code> set overrides both account-level and package-level 2FA for publishing.</li>\n<li><strong>Node 22 ships npm 10</strong>, so neither <code>min-release-age</code> nor trusted publishing works on that line without upgrading\nnpm.</li>\n<li><strong>Corepack stopped shipping with Node 25</strong>, so <code>\"packageManager\"</code> is inert unless <code>corepack</code> is installed separately.</li>\n</ul>\n<p>Read [<code>${CLAUDE_SKILL_DIR}/references/conventions/supply-chain.md</code>] when hardening an install, configuring publishing,\nor auditing what a lockfile actually guarantees — it carries the trusted-publishing constraints, the provenance rules,\nand the npm configuration keys.</p>\n<h2>CLI and Flags</h2>\n<ul>\n<li><strong><code>node --run &lt;script&gt;</code> is not <code>npm run</code>.</strong> It skips <code>pre</code> and <code>post</code> scripts, sets no <code>npm_package_*</code> variables, and\ndoes not pass <code>--env-file</code> variables to the command.</li>\n<li><strong><code>--env-file</code> is read before the Permission Model initializes</strong>, so <code>--permission</code> cannot restrict which file it\nreads, and the file can set <code>NODE_OPTIONS</code>.</li>\n<li><strong>The real environment overrides an <code>--env-file</code> value.</strong> Later <code>--env-file</code> flags override earlier ones.</li>\n<li><strong><code>NODE_OPTIONS</code> refuses <code>-e</code> and <code>-p</code>.</strong> Node exits with <code>-e is not allowed in NODE_OPTIONS</code> rather than ignoring the\nflag.</li>\n<li><strong>A bare script path in <code>NODE_OPTIONS</code> is dropped silently</strong> — the file never runs and nothing warns, measured on\n26.2.0. Load code from the variable with <code>--require</code> or <code>--import</code>.</li>\n<li><strong><code>--test</code> defaults to process isolation</strong>, one child per file, and reports asynchronous work that outlives a test as\na failure rather than dropping it.</li>\n<li><strong><code>--test</code> picks up <code>.ts</code> files</strong> under the same name patterns unless <code>--no-strip-types</code> is passed.</li>\n</ul>\n<p>Read [<code>${CLAUDE_SKILL_DIR}/references/conventions/cli-and-flags.md</code>] when wiring a container entrypoint, building a\nsingle executable, or choosing hardening flags — it carries the environment-file rules, the test-runner CLI surface, the\nSEA build paths per major, and <code>--disable-proto</code>, <code>--frozen-intrinsics</code>, and <code>--secure-heap</code>.</p>\n<h2>Testing with <code>node:test</code></h2>\n<ul>\n<li><strong><code>test()</code> and <code>suite()</code> are the names; <code>it()</code> and <code>describe()</code> are aliases.</strong> Subtests come from the context —\n<code>await t.test(...)</code> — and <code>beforeEach</code>/<code>afterEach</code> fire between subtests, not only between top-level tests.</li>\n<li><strong>Await every <code>t.test()</code>.</strong> The runner awaits subtests from 24.0.0, but the 22 line does not, and the await is what\nmakes ordering deterministic on both.</li>\n<li><strong>Assert through <code>t.assert.*</code>, not the bare <code>node:assert</code>.</strong> Only the context-bound form is counted by <code>t.plan()</code>, so\na bare <code>assert</code> leaves the plan short and the failure reads as a miscount rather than a wrong assertion.</li>\n<li><strong><code>t.plan(n)</code> checks the moment the test function returns.</strong> The default is <code>{ wait: false }</code>; an assertion arriving\nfrom a callback afterwards is not counted. Pass <code>{ wait: true }</code> or a millisecond budget.</li>\n<li><strong>Import <code>node:assert/strict</code>, never <code>node:assert</code>, outside a test.</strong> The legacy surface compares with <code>==</code>, so\n<code>assert.equal(1, '1')</code> passes. <code>assert.CallTracker</code> was removed in 25.0.0 (DEP0173) — use <code>mock.fn()</code> and\n<code>fn.mock.callCount()</code>.</li>\n<li><strong>Prefer <code>t.mock</code> to the imported <code>mock</code>.</strong> The context tracker is reset after each test; the module-level one is\nprocess-wide and needs a manual <code>mock.reset()</code> or <code>mock.restoreAll()</code>.</li>\n<li><strong><code>mock.module()</code> needs <code>--experimental-test-module-mocks</code>.</strong> Without the flag it is <code>undefined</code>, so the test dies on\na <code>TypeError</code> instead of a clear message. It is Stability 1.0, the least settled part of the runner. Pass the\ndependency in as a parameter or a constructor argument before reaching for it.</li>\n<li><strong>A destructured timer import is never mocked.</strong> <code>import { setTimeout } from 'node:timers'</code> binds the real function\nbefore <code>mock.timers.enable()</code> runs. Call the global or the namespace property.</li>\n<li><strong>Pass <code>--test-reporter</code> explicitly.</strong> The non-TTY default changed from <code>tap</code> to <code>spec</code> in 23.0.0, so a piped CI run\nemits a different format on 22 than on 24. Reporter output is not a stable contract — parse the <code>TestsStream</code> events\ninstead.</li>\n<li><strong>Coverage is experimental and off</strong>: <code>--experimental-test-coverage</code>, with core modules, <code>node_modules/</code>, and the test\nfiles excluded by default.</li>\n<li><strong>Never run <code>--test-update-snapshots</code> in CI.</strong> It rewrites the baseline, turning every regression into a pass.</li>\n<li><strong><code>--test-force-exit</code> hides an open handle rather than closing one.</strong> Find it with <code>process.getActiveResourcesInfo()</code>.</li>\n</ul>\n<p>Read [<code>${CLAUDE_SKILL_DIR}/references/conventions/testing.md</code>] when writing the first test in a project, when a mock or\na fake timer does not take effect, or when wiring reporters and coverage thresholds — it carries the structure and hook\nrules, the assertion surface, the mocking API with its restore semantics and flags, snapshots, the reporter pairing\nrules, and the subtest-awaiting behavior that the shipped documentation states incorrectly.</p>\n<h2>Application</h2>\n<p>When <strong>writing</strong> Node.js code, apply these rules silently — do not narrate a rule while following it. Where existing\ncode contradicts one, follow the codebase and flag the divergence once.</p>\n<p>When <strong>reviewing</strong> Node.js code, cite the violation and show the fix inline. Do not lecture.</p>\n<pre><code>Bad:  \"Node.js best practice is to avoid process.exit() because stdout writes...\"\nGood: process.exit(1) -&gt; process.exitCode = 1\n</code></pre>\n<h2>Integration</h2>\n<p>The <strong>javascript</strong> and <strong>typescript</strong> skills own the language and the type system; this skill owns the runtime that\nexecutes them. The split with <code>javascript</code> is resolution against syntax: <code>javascript</code> states what an ES module means,\nthis skill states how Node finds it, what <code>package.json</code> changes about that, and which of Node's own APIs accept a\nsignal. <code>typescript</code> states what each compiler option does; this skill states what Node erases and refuses.</p>\n<p><code>node:test</code> is this skill's, <code>bun:test</code> is the <strong>bun</strong> skill's, and the <strong>vitest</strong> skill owns Vitest. Which one a\nproject adopts is a project decision that no skill states. The <strong>coding</strong> skill governs workflow.</p>\n<p><strong>Node enforces almost nothing it lets you declare — the floor, the permission grant, and the stability index each hold\nby discipline, and the runtime reports no violation of any of them.</strong></p>\n","files":[{"path":".dev/reference-inventory.json","sizeBytes":2292,"isText":true},{"path":"references/conventions/cli-and-flags.md","sizeBytes":5736,"isText":true},{"path":"references/conventions/concurrency.md","sizeBytes":3597,"isText":true},{"path":"references/conventions/http-client.md","sizeBytes":4058,"isText":true},{"path":"references/conventions/lifecycle.md","sizeBytes":4786,"isText":true},{"path":"references/conventions/modules.md","sizeBytes":8643,"isText":true},{"path":"references/conventions/observability.md","sizeBytes":5798,"isText":true},{"path":"references/conventions/permissions.md","sizeBytes":6101,"isText":true},{"path":"references/conventions/streams.md","sizeBytes":2964,"isText":true},{"path":"references/conventions/supply-chain.md","sizeBytes":4852,"isText":true},{"path":"references/conventions/testing.md","sizeBytes":8294,"isText":true},{"path":"references/conventions/typescript-execution.md","sizeBytes":4724,"isText":true},{"path":"references/versions/node-20.md","sizeBytes":3300,"isText":true},{"path":"references/versions/node-22.md","sizeBytes":4252,"isText":true},{"path":"references/versions/node-24.md","sizeBytes":4126,"isText":true},{"path":"references/versions/node-26.md","sizeBytes":5458,"isText":true},{"path":"SKILL.md","sizeBytes":28403,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"notes-only","suspicious":0,"notes":5,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-11-10T18:27:57.99456Z","sha256":"01A1D009EDC4F1BFCDD799351E194579027F00292958F7B16B62C586E1F9C398","sizeBytes":50159},"review":null,"source":{"repositoryUrl":"https://github.com/xobotyi/cc-foundry","path":"plugins/javascript/skills/nodejs","license":"MIT","commit":"278c16c0c371ac3ef36b12512ca558c7513ef13e","subtreeSha":"F06B8194D3C29FBF438E8A0329C69E64651EB74261AA15C10C19044295CD8D46","lastSyncedAt":"2026-11-10T18:27:15.736835Z"},"reviewedAt":"2026-11-10T18:28:55.131129Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/xobotyi/cc-foundry/tree/master/plugins/javascript/skills/nodejs"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install xobotyi-cc-foundry@llmmart"},{"target":"git","command":"git clone https://github.com/xobotyi/cc-foundry.git"}]}