Skip to content
Tutorials Center
My learning

Topics

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.

NODE
// shell: node --experimental-vm-modules app.js

Try it

Node.js A feature that appears only with its flag

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.

Node.js Finding the flags your Node.js knows

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

NODE
// 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 with process.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_OPTIONS accepts 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-types runs TypeScript files; --permission is the permission model; --experimental-vm-modules is how test frameworks such as Jest run ES modules in vm contexts.