esm: unflag --experimental-wasm-modules

guybedford · aduh95 · commit b919fe0447e4 · 2025-07-26T01:32:02.000+02:00
PR-URL: #57038 Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com> Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
diff --git a/doc/api/cli.md b/doc/api/cli.md
@@ -33,8 +33,7 @@ If a file is found, its path will be passed to the
 
 * The program was started with a command-line flag that forces the entry
   point to be loaded with ECMAScript module loader, such as `--import`.
-* 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,7 +48,6 @@ entry point, the `node` command will accept as input only files with `.js`,
 `.mjs`, or `.cjs` extensions. With the following flags, additional file
 extensions are enabled:
 
-* [`--experimental-wasm-modules`][] for files with `.wasm` extension.
 * [`--experimental-addon-modules`][] for files with `.node` extension.
 
 ## Options
@@ -1217,14 +1215,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
@@ -3364,7 +3354,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`
@@ -3943,7 +3932,6 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`--env-file`]: #--env-filefile
 [`--experimental-addon-modules`]: #--experimental-addon-modules
 [`--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
@@ -701,34 +701,23 @@ imported from the same path.
 
 ## Wasm modules
 
-> Stability: 1 - Experimental
+<!-- 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 are supported under the `--experimental-wasm-modules` flag.
+imports is supported.
 
 Both of these integrations are in line with the
 [ES Module Integration Proposal for WebAssembly][].
 
-Instance imports allow any `.wasm` files to be imported as normal modules,
-supporting their module imports in turn.
-
-For example, an `index.js` containing:
-
-```js
-import * as M from './library.wasm';
-console.log(M);
-```
-
-executed under:
-
-```bash
-node --experimental-wasm-modules index.mjs
-```
-
-would provide the exports interface for the instantiation of `library.wasm`.
-
 ### Wasm Source Phase Imports
 
+> Stability: 1.2 - Release candidate
+
 <!-- YAML
 added: v24.0.0
 -->
@@ -762,6 +751,8 @@ const instance = await WebAssembly.instantiate(dynamicLibrary, importObject);
 
 ### JavaScript String Builtins
 
+> Stability: 1.2 - Release candidate
+
 <!-- YAML
 added: REPLACEME
 -->
@@ -811,14 +802,36 @@ const { exports: { getLength } } = await WebAssembly.instantiate(mod, {});
 getLength('foo'); // Also returns 3.
 ```
 
+### Wasm Instance Phase Imports
+
+> Stability: 1.1 - Active development
+
+Instance imports allow any `.wasm` files to be imported as normal modules,
+supporting their module imports in turn.
+
+For example, an `index.js` containing:
+
+```js
+import * as M from './library.wasm';
+console.log(M);
+```
+
+executed under:
+
+```bash
+node index.mjs
+```
+
+would provide the exports interface for the instantiation of `library.wasm`.
+
 ### Reserved Wasm Namespaces
 
 <!-- YAML
 added: REPLACEME
 -->
 
-When importing WebAssembly modules through the ESM Integration, they cannot use
-import module names or import/export names that start with reserved prefixes:
+When importing WebAssembly module instances, they cannot use import module
+names or import/export names that start with reserved prefixes:
 
 * `wasm-js:` - reserved in all module import names, module names and export
   names.
@@ -1185,7 +1198,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. If `--experimental-addon-modules` is enabled and _url_ ends in
@@ -1203,9 +1216,8 @@ _isImports_, _conditions_)
 >        1. Return _"module"_.
 >     3. Return _"commonjs"_.
 > 12. 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
+>        "application/wasm" content type 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
@@ -177,9 +177,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
@@ -220,9 +220,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-quic
 Enable the experimental QUIC support.
 .
diff --git a/lib/internal/modules/esm/formats.js b/lib/internal/modules/esm/formats.js
@@ -9,7 +9,6 @@ const { getValidatedPath } = require('internal/fs/utils');
 const fsBindings = internalBinding('fs');
 const { internal: internalConstants } = internalBinding('constants');
 
-const experimentalWasmModules = getOptionValue('--experimental-wasm-modules');
 const experimentalAddonModules = getOptionValue('--experimental-addon-modules');
 
 const extensionFormatMap = {
@@ -18,12 +17,9 @@ const extensionFormatMap = {
   '.js': 'module',
   '.json': 'json',
   '.mjs': 'module',
+  '.wasm': 'wasm',
 };
 
-if (experimentalWasmModules) {
-  extensionFormatMap['.wasm'] = 'wasm';
-}
-
 if (experimentalAddonModules) {
   extensionFormatMap['.node'] = 'addon';
 }
@@ -46,7 +42,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;
 }
 
@@ -58,7 +54,6 @@ function mimeToFormat(mime) {
  * @returns {'wasm'|'module'}
  */
 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
@@ -495,8 +495,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}`);
@@ -546,6 +544,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.cc b/src/node.cc
@@ -773,9 +773,7 @@ static ExitCode ProcessGlobalArgsInternal(std::vector<std::string>* args,
     env_opts->abort_on_uncaught_exception = true;
   }
 
-  if (env_opts->experimental_wasm_modules) {
-    v8_args.emplace_back("--js-source-phase-imports");
-  }
+  v8_args.emplace_back("--js-source-phase-imports");
 
 #ifdef __POSIX__
   // Block SIGPROF signals when sleeping in epoll_wait/kevent/etc.  Avoids the
diff --git a/src/node_options.cc b/src/node_options.cc
@@ -536,10 +536,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
@@ -133,7 +133,6 @@ class EnvironmentOptions : public Options {
   std::string localstorage_file;
   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
   bool entry_is_url = false;
diff --git a/test/es-module/test-esm-wasm.mjs b/test/es-module/test-esm-wasm.mjs
diff --git a/test/module-hooks/test-module-hooks-import-wasm.mjs b/test/module-hooks/test-module-hooks-import-wasm.mjs
diff --git a/test/module-hooks/test-module-hooks-require-wasm.js b/test/module-hooks/test-module-hooks-require-wasm.js
diff --git a/test/parallel/test-process-env-allowed-flags-are-documented.js b/test/parallel/test-process-env-allowed-flags-are-documented.js

Original file line number	Diff line number	Diff line change
`@@ -220,9 +220,6 @@ Enable experimental ES module support in VM module.`
`220`	`220`	`Enable experimental WebAssembly System Interface support. This`
`221`	`221`	`flag is no longer required as WASI is enabled by default.`
`222`	`222`	`.`
`223`		`-.It Fl -experimental-wasm-modules`
`224`		`-Enable experimental WebAssembly module support.`
`225`		`-.`
`226`	`223`	`.It Fl -experimental-quic`
`227`	`224`	`Enable the experimental QUIC support.`
`228`	`225`	`.`
Original file line number	Diff line number	Diff line change
`@@ -773,9 +773,7 @@ static ExitCode ProcessGlobalArgsInternal(std::vector<std::string>* args,`
`773`	`773`	`env_opts->abort_on_uncaught_exception = true;`
`774`	`774`	`}`
`775`	`775`
`776`		`- if (env_opts->experimental_wasm_modules) {`
`777`		`- v8_args.emplace_back("--js-source-phase-imports");`
`778`		`- }`
	`776`	`+ v8_args.emplace_back("--js-source-phase-imports");`
`779`	`777`
`780`	`778`	`#ifdef __POSIX__`
`781`	`779`	`// Block SIGPROF signals when sleeping in epoll_wait/kevent/etc. Avoids the`