npx skills add jasnell/node-skills --skill node-experimental-checkSKILL.md
Verify experimental Node.js features before relying on them
Experimental APIs (Stability 1, 1.0, 1.1) change between minor releases. Option names change, methods move, and flags get renamed or removed. A skill describes one snapshot. The installed Node.js is the source of truth.
Checklist (do not skip for Stability 1.x)
- Find the runtime that will run the code. Run
node --version, but also check.nvmrc,package.jsonengines,volta, the DockerfileFROM node:<tag>, and the CInode-version. The shell'snodemay not be the one that matters. - Probe the exact items you will use. Run the bundled script with the
target binary:
The probe passesnode scripts/probe.mjs --flag --experimental-stream-iter --module node:stream/iter node scripts/probe.mjs --module node:zlib:ZipFile.openSync --global URLPattern node scripts/probe.mjs --flag --experimental-bench --list node:bench # list exports node scripts/probe.mjs --node ./out/Release/node --flag --process-timeout--experimental-*/--allow-*flags through to the module checks and exits 1 if anything is missing. If you can't run the script, use a one-liner instead:node --experimental-x -p "typeof require('node:mod').thing"andnode --help | grep -- --flag. - Read the docs for that version, not
latest:https://nodejs.org/docs/<version>/api/<module>.html. For a pre-release build, readdoc/api/<module>.mdin its checkout. Check the YAMLadded:/changes:history and the Stability line of each API you use. - Prefer behavior over docs. For anything subtle (defaults, units, error codes), run a 5-line script instead of trusting prose.
- Gate or fall back. If the code must run on several versions, use
feature detection (
typeof x === 'function', atry { await import() }block), not a version-string compare. State the minimum version inenginesor in a comment. - Tell the user that the code depends on an experimental API, which flag it needs, and that the API may change in minor releases.
Reading added: lists
added: [v26.8.0, v24.22.0] means the feature is in 24.22+ on the v24 line
and in 26.8+. It is not in v25.x or in 26.0–26.7. A single entry
v26.1.0 means the feature is not on v24 at all.
Pitfalls
- A flag that the installed version does not accept fails the process with
bad option. That means the version lacks the feature, not that the flag is spelled wrong. - Some modules only resolve with the
node:prefix (node:sqlite,node:test,node:bench) and some only behind a flag. Probe with the flag. - Flags that get unflagged keep an opposite
--no-experimental-*form. After that, passing the old--experimental-*flag may warn or error.