Node.js Reference ยท CLI Flags
Node.js --experimental flags
Reference for Node.js --experimental-* flags: how opt-in features work, what ExperimentalWarning means, how to list the flags, and how to use them safely.
Node.js ships new features behind --experimental-* flags while their design is still settling. Without the flag the feature is missing or inactive; with it, you can try the feature and give feedback, knowing that the API may change or disappear in any release.
Features usually follow a path: flag only, then enabled by default (and a --no-experimental-* flag to turn it off), then stable with the flag deprecated. Many things that began as flags, such as fetch, the test runner, WebSocket and type stripping, are now on by default.
// shell: node --experimental-vm-modules app.js
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
// shell node --experimental-<feature> <script> node --no-experimental-<feature> <script> // turns a default-on feature off node --help | grep experimental // list the flags of your version
| Name | Description |
|---|---|
--experimental-<feature> |
Enables a feature that is off by default, for example --experimental-vm-modules, --experimental-transform-types or --experimental-eventsource. |
--no-experimental-<feature> |
Disables a feature that became default-on, such as --no-experimental-require-module or --no-experimental-websocket. |
Returns: nothing. Check process.execArgv to see which flags are active, and process.features for some built-in switches.
Edge cases: flags that do not exist in your version cause node: bad option. A --no-... form only exists for features that are booleans; for example --no-experimental-fetch is rejected because fetch has no such switch.
Usage notes
ExperimentalWarning: the first use of an experimental API prints a warning to stderr. It does not mean something is broken; it is a reminder that the API is unstable. Listen withprocess.on('warning'), and silence specific ones with--disable-warning=ExperimentalWarning.- Flags change between versions. Do not copy a list from a blog post; ask your own binary with
node --help, and read the stability index in the docs (Stability index). - Do not depend on experimental features in libraries. Applications can pin a Node.js version; a published package cannot.
NODE_OPTIONSaccepts most--experimental-*flags, which is how tools enable them for the processes they spawn.- Worker threads inherit most experimental flags from the main thread; child processes do not unless you pass them or use
NODE_OPTIONS. - Graduation: when a feature is promoted, the old flag usually keeps working (sometimes with a deprecation notice) so existing commands do not break.
- Specific cases:
--experimental-strip-typesruns TypeScript files;--permissionis the permission model;--experimental-vm-modulesis how test frameworks such as Jest run ES modules invmcontexts.