esm: unflag --experimental-wasm-modules

PR-URL: #57038 Backport-PR-URL: #59179 Reviewed-By: Yagiz Nizipli <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Stephen Belanger <[email protected]> Reviewed-By: Geoffrey Booth <[email protected]> Reviewed-By: Chengzhong Wu <[email protected]>
nodejs · aduh95 · Aug 28, 2025 · Jul 8, 2025 · Jul 8, 2025 · Jul 8, 2025
commit fa9a9e9c69a72499e3b17d19d87ea376b95d5ed9
diff --git a/doc/api/cli.md b/doc/api/cli.md
@@ -36,8 +36,7 @@ If a file is found, its path will be passed to the
   point to be loaded with ECMAScript module loader, such as `--import` or
   [`--experimental-default-type=module`][].
 * The file has an `.mjs` extension.
-* The file has an `.mjs` or `.wasm` (with `--experimental-wasm-modules`)
-  extension.
+* The file has an `.mjs` or `.wasm` extension.
 * The file does not have a `.cjs` extension, and the nearest parent
   `package.json` file contains a top-level [`"type"`][] field with a value of
   `"module"`.
@@ -49,8 +48,7 @@ Otherwise, the file is loaded using the CommonJS module loader. See
 
 When loading, the [ES module loader][Modules loaders] loads the program
 entry point, the `node` command will accept as input only files with `.js`,
-`.mjs`, or `.cjs` extensions; with `.wasm` extensions when
-[`--experimental-wasm-modules`][] is enabled; and with no extension when
+`.mjs`, `.cjs` or `.wasm` extensions; and with no extension when
 [`--experimental-default-type=module`][] is passed.
 
 ## Options
@@ -1015,8 +1013,7 @@ Node.js currently defaults to CommonJS to instead default to ECMAScript modules,
 with the exception of folders and subfolders below `node_modules`, for backward
 compatibility.
 
-Under `--experimental-default-type=module` and `--experimental-wasm-modules`,
-files with no extension will be treated as WebAssembly if they begin with the
+Files with no extension will be treated as WebAssembly if they begin with the
 WebAssembly magic number (`\0asm`); otherwise they will be treated as ES module
 JavaScript.
 
@@ -1233,14 +1230,6 @@ changes:
 
 Enable experimental WebAssembly System Interface (WASI) support.
 
-### `--experimental-wasm-modules`
-
-<!-- YAML
-added: v12.3.0
--->
-
-Enable experimental WebAssembly module support.
-
 ### `--experimental-webstorage`
 
 <!-- YAML
@@ -3356,7 +3345,6 @@ one is included in the list below.
 * `--experimental-transform-types`
 * `--experimental-vm-modules`
 * `--experimental-wasi-unstable-preview1`
-* `--experimental-wasm-modules`
 * `--experimental-webstorage`
 * `--force-context-aware`
 * `--force-fips`
@@ -3938,7 +3926,6 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`--env-file`]: #--env-fileconfig
 [`--experimental-default-type=module`]: #--experimental-default-typetype
 [`--experimental-sea-config`]: single-executable-applications.md#generating-single-executable-preparation-blobs
-[`--experimental-wasm-modules`]: #--experimental-wasm-modules
 [`--heap-prof-dir`]: #--heap-prof-dir
 [`--import`]: #--importmodule
 [`--no-experimental-strip-types`]: #--no-experimental-strip-types

diff --git a/doc/api/esm.md b/doc/api/esm.md
@@ -672,10 +672,24 @@ imported from the same path.
 
 ## Wasm modules
 
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/57038
+    description: Wasm modules no longer require the `--experimental-wasm-modules` flag.
+-->
+
+Importing both WebAssembly module instances and WebAssembly source phase
+imports is supported.
+
+This integration is in line with the
+[ES Module Integration Proposal for WebAssembly][].
+
+## Wasm modules
+
 > Stability: 1 - Experimental
 
-Importing WebAssembly modules is supported under the
-`--experimental-wasm-modules` flag, allowing any `.wasm` files to be
+Importing WebAssembly modules is supported allowing any `.wasm` files to be
 imported as normal modules while also supporting their module imports.
 
 This integration is in line with the
@@ -691,7 +705,7 @@ console.log(M);
 executed under:
 
 ```bash
-node --experimental-wasm-modules index.mjs
+node index.mjs
 ```
 
 would provide the exports interface for the instantiation of `module.wasm`.
@@ -738,15 +752,6 @@ imports and they cannot be inspected via `WebAssembly.Module.imports(mod)`
 or virtualized unless recompiling the module using the direct
 `WebAssembly.compile` API with string builtins disabled.
 
-Importing a module in the source phase before it has been instantiated will also
-use the compile-time builtins automatically:
-
-```js
-import source mod from './string-len.wasm';
-const { exports: { getLength } } = await WebAssembly.instantiate(mod, {});
-getLength('foo'); // Also returns 3.
-```
-
 ### Reserved Wasm Namespaces
 
 <!-- YAML
@@ -1121,7 +1126,7 @@ _isImports_, _conditions_)
 >    1. Return _"commonjs"_.
 > 4. If _url_ ends in _".json"_, then
 >    1. Return _"json"_.
-> 5. If `--experimental-wasm-modules` is enabled and _url_ ends in
+> 5. If _url_ ends in
 >    _".wasm"_, then
 >    1. Return _"wasm"_.
 > 6. Let _packageURL_ be the result of **LOOKUP\_PACKAGE\_SCOPE**(_url_).
@@ -1136,9 +1141,8 @@ _isImports_, _conditions_)
 >        1. Return _"module"_.
 >     3. Return _"commonjs"_.
 > 11. If _url_ does not have any extension, then
->     1. If _packageType_ is _"module"_ and `--experimental-wasm-modules` is
->        enabled and the file at _url_ contains the header for a WebAssembly
->        module, then
+>     1. If _packageType_ is _"module"_ and the file at _url_ contains the
+>        header for a WebAssembly module, then
 >        1. Return _"wasm"_.
 >     2. If _packageType_ is not **null**, then
 >        1. Return _packageType_.

diff --git a/doc/node-config-schema.json b/doc/node-config-schema.json
@@ -186,9 +186,6 @@
         "experimental-vm-modules": {
           "type": "boolean"
         },
-        "experimental-wasm-modules": {
-          "type": "boolean"
-        },
         "experimental-websocket": {
           "type": "boolean"
         },

diff --git a/doc/node.1 b/doc/node.1
@@ -234,9 +234,6 @@ Enable experimental ES module support in VM module.
 Enable experimental WebAssembly System Interface support. This
 flag is no longer required as WASI is enabled by default.
 .
-.It Fl -experimental-wasm-modules
-Enable experimental WebAssembly module support.
-.
 .It Fl -experimental-inspector-network-resource
 Enable experimental support for inspector network resources.
 .

diff --git a/lib/internal/modules/esm/formats.js b/lib/internal/modules/esm/formats.js
@@ -9,20 +9,15 @@ const { getValidatedPath } = require('internal/fs/utils');
 const fsBindings = internalBinding('fs');
 const { internal: internalConstants } = internalBinding('constants');
 
-const experimentalWasmModules = getOptionValue('--experimental-wasm-modules');
-
 const extensionFormatMap = {
   '__proto__': null,
   '.cjs': 'commonjs',
   '.js': 'module',
   '.json': 'json',
   '.mjs': 'module',
+  '.wasm': 'wasm',
 };
 
-if (experimentalWasmModules) {
-  extensionFormatMap['.wasm'] = 'wasm';
-}
-
 if (getOptionValue('--experimental-strip-types')) {
   extensionFormatMap['.ts'] = 'module-typescript';
   extensionFormatMap['.mts'] = 'module-typescript';
@@ -41,7 +36,7 @@ function mimeToFormat(mime) {
     ) !== null
   ) { return 'module'; }
   if (mime === 'application/json') { return 'json'; }
-  if (experimentalWasmModules && mime === 'application/wasm') { return 'wasm'; }
+  if (mime === 'application/wasm') { return 'wasm'; }
   return null;
 }
 
@@ -52,7 +47,6 @@ function mimeToFormat(mime) {
  * @param {URL} url
  */
 function getFormatOfExtensionlessFile(url) {
-  if (!experimentalWasmModules) { return 'module'; }
   const path = getValidatedPath(url);
   switch (fsBindings.getFormatOfExtensionlessFile(path)) {
     case internalConstants.EXTENSIONLESS_FORMAT_WASM:

diff --git a/lib/internal/modules/esm/translators.js b/lib/internal/modules/esm/translators.js
@@ -433,8 +433,6 @@ translators.set('json', function jsonStrategy(url, source) {
  */
 const wasmInstances = new SafeWeakMap();
 translators.set('wasm', async function(url, source) {
-  emitExperimentalWarning('Importing WebAssembly modules');
-
   assertBufferSource(source, false, 'load');
 
   debug(`Translating WASMModule ${url}`);
@@ -483,6 +481,7 @@ translators.set('wasm', async function(url, source) {
   const createDynamicModule = require('internal/modules/esm/create_dynamic_module');
 
   const { module } = createDynamicModule([...importsList], [...exportsList], url, (reflect) => {
+    emitExperimentalWarning('Importing WebAssembly module instances');
     for (const impt of importsList) {
       const importNs = reflect.imports[impt];
       const wasmInstance = wasmInstances.get(importNs);

diff --git a/src/node_options.cc b/src/node_options.cc
@@ -479,10 +479,7 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             kAllowedInEnvvar);
   AddAlias("--loader", "--experimental-loader");
   AddOption("--experimental-modules", "", NoOp{}, kAllowedInEnvvar);
-  AddOption("--experimental-wasm-modules",
-            "experimental ES Module support for webassembly modules",
-            &EnvironmentOptions::experimental_wasm_modules,
-            kAllowedInEnvvar);
+  AddOption("--experimental-wasm-modules", "", NoOp{}, kAllowedInEnvvar);
   AddOption("--experimental-import-meta-resolve",
             "experimental ES Module import.meta.resolve() parentURL support",
             &EnvironmentOptions::experimental_import_meta_resolve,

diff --git a/src/node_options.h b/src/node_options.h
@@ -130,7 +130,6 @@ class EnvironmentOptions : public Options {
   bool experimental_global_customevent = true;
   bool experimental_global_navigator = true;
   bool experimental_global_web_crypto = true;
-  bool experimental_wasm_modules = false;
   bool experimental_import_meta_resolve = false;
   std::string input_type;  // Value of --input-type
   std::string type;        // Value of --experimental-default-type