Initial experimental support for ESM integration (#23985)

This change add a new experimental settings call `WASM_ESM_INTEGRATION`.

In this mode we can elide all of the wasm module loading and
instantiation code, and instead rely on the module loader to both load
and instantiate the wasm file.

Current limitations:

- No support for INCOMING_JS_MODULE_API / moduleArg.
- No support for closure
- Many features such as threads and dynamic linking do not work

Author: sbc100

ChangeLog.md

@@ -20,6 +20,9 @@ See docs/process.md for more on how version tagging works.
 
 4.0.7 (in development)
 ----------------------
+- Added experimental support for Wasm ESM integration with
+  `-sWASM_ESM_INTEGRATION`. This is currently only supported in node behind a
+  flag and not in any browsers. (#23985)
 
 4.0.6 - 03/26/25
 ----------------

site/source/docs/tools_reference/settings_reference.rst

@@ -3345,3 +3345,13 @@ and not yet supported by browsers.
 Requires EXPORT_ES6
 
 Default value: false
+
+.. _wasm_esm_integration:
+
+WASM_ESM_INTEGRATION
+====================
+
+Experimental support for wasm ESM integration.
+Requires EXPORT_ES6 and MODULARIZE=instance
+
+Default value: false

src/jsifier.mjs

@@ -857,7 +857,7 @@ var proxiedFunctionTable = [
       includeFile(fileName);
     }
 
-    if (MODULARIZE) {
+    if (MODULARIZE && !WASM_ESM_INTEGRATION) {
       includeSystemFile('postamble_modularize.js');
     }
 

src/postamble.js

@@ -305,7 +305,16 @@ consumedModuleProp('preInit');
 #endif
 #endif
 
+
+#if WASM_ESM_INTEGRATION
+export default function init(moduleArg = {}) {
+  // TODO(sbc): moduleArg processing
+  updateMemoryViews();
+  run();
+}
+#else
 run();
+#endif
 
 #if BUILD_AS_WORKER
 

src/preamble.js

@@ -46,7 +46,9 @@ if (typeof WebAssembly != 'object') {
 
 // Wasm globals
 
+#if !WASM_ESM_INTEGRATION
 var wasmMemory;
+#endif
 
 #if SHARED_MEMORY
 // For sending to workers.
@@ -220,7 +222,11 @@ function initRuntime() {
   <<< ATINITS >>>
 
 #if hasExportedSymbol('__wasm_call_ctors')
+#if WASM_ESM_INTEGRATION
+  ___wasm_call_ctors();
+#else
   wasmExports['__wasm_call_ctors']();
+#endif
 #endif
 
   <<< ATPOSTCTORS >>>
@@ -577,7 +583,7 @@ function resetPrototype(constructor, attrs) {
 }
 #endif
 
-#if !SOURCE_PHASE_IMPORTS
+#if !SOURCE_PHASE_IMPORTS && !WASM_ESM_INTEGRATION
 var wasmBinaryFile;
 
 function findWasmBinary() {
@@ -819,6 +825,7 @@ async function instantiateAsync(binary, binaryFile, imports) {
 #endif // WASM_ASYNC_COMPILATION
 #endif // SOURCE_PHASE_IMPORTS
 
+#if !WASM_ESM_INTEGRATION
 function getWasmImports() {
 #if PTHREADS
   assignWasmImports();
@@ -1058,6 +1065,7 @@ function getWasmImports() {
 #endif // WASM_ASYNC_COMPILATION
 #endif // SOURCE_PHASE_IMPORTS
 }
+#endif
 
 #if !WASM_BIGINT
 // Globals used by JS i64 conversions (see makeSetValue)

src/runtime_shared.js

@@ -54,7 +54,7 @@ var wasmOffsetConverter;
       }
     }
     if (shouldExport) {
-      if (MODULARIZE === 'instance') {
+      if (MODULARIZE === 'instance' && !WASM_ESM_INTEGRATION) {
         return `__exp_${x} = `
       }
       return `Module['${x}'] = `;

src/settings.js

@@ -2188,6 +2188,11 @@ var SIGNATURE_CONVERSIONS = [];
 // [link]
 var SOURCE_PHASE_IMPORTS = false;
 
+// Experimental support for wasm ESM integration.
+// Requires EXPORT_ES6 and MODULARIZE=instance
+// [link]
+var WASM_ESM_INTEGRATION = false;
+
 // For renamed settings the format is:
 // [OLD_NAME, NEW_NAME]
 // For removed settings (which now effectively have a fixed value and can no

src/shell.js

@@ -20,7 +20,9 @@
 // after the generated code, you will need to define   var Module = {};
 // before the code. Then that object will be used in the code, and you
 // can continue to use Module afterwards as well.
-#if MODULARIZE
+#if WASM_ESM_INTEGRATION
+var Module = {};
+#elif MODULARIZE
 var Module = moduleArg;
 #elif USE_CLOSURE_COMPILER
 /** @type{Object} */

test/test_other.py

@@ -360,13 +360,23 @@ def test_esm(self, args):
 
   @requires_node_canary
   def test_esm_source_phase_imports(self):
-    self.node_args += ['--experimental-wasm-modules']
+    self.node_args += ['--experimental-wasm-modules', '--no-warnings']
     self.run_process([EMCC, '-o', 'hello_world.mjs', '-sSOURCE_PHASE_IMPORTS',
                       '--extern-post-js', test_file('modularize_post_js.js'),
                       test_file('hello_world.c')])
     self.assertContained('import source wasmModule from', read_file('hello_world.mjs'))
     self.assertContained('hello, world!', self.run_js('hello_world.mjs'))
 
+  @requires_node_canary
+  def test_esm_integration(self):
+    self.node_args += ['--experimental-wasm-modules', '--no-warnings']
+    self.run_process([EMCC, '-o', 'hello_world.mjs', '-sWASM_ESM_INTEGRATION', '-Wno-experimental', test_file('hello_world.c')])
+    create_file('runner.mjs', '''
+      import init from "./hello_world.mjs";
+      await init();
+    ''')
+    self.assertContained('hello, world!', self.run_js('runner.mjs'))
+
   @parameterized({
     '': ([],),
     'node': (['-sENVIRONMENT=node'],),

tools/emscripten.py

@@ -435,17 +435,18 @@ def emscript(in_wasm, out_wasm, outfile_js, js_syms, finalize=True, base_metadat
     pre = None
 
     receiving = create_receiving(function_exports)
-
-    module = create_module(receiving, metadata, global_exports, forwarded_json['librarySymbols'])
-
-    metadata.library_definitions = forwarded_json['libraryDefinitions']
-
+    if settings.WASM_ESM_INTEGRATION:
+      sending = create_sending(metadata, forwarded_json['librarySymbols'])
+      module = [sending, receiving]
+    else:
+      module = create_module(receiving, metadata, global_exports, forwarded_json['librarySymbols'])
     write_output_file(out, module)
 
     out.write(post)
     module = None
 
-    return metadata
+  metadata.library_definitions = forwarded_json['libraryDefinitions']
+  return metadata
 
 
 @ToolchainProfiler.profile()
@@ -851,6 +852,13 @@ def create_sending(metadata, library_symbols):
           send_items_map[demangled] = f
 
   sorted_items = sorted(send_items_map.items())
+
+  if settings.WASM_ESM_INTEGRATION:
+    elems = []
+    for k, v in sorted_items:
+      elems.append(f'{v} as {k}')
+    return f"export {{ {', '.join(elems)} }};\n\n"
+
   prefix = ''
   if settings.MAYBE_CLOSURE_COMPILER:
     # This prevents closure compiler from minifying the field names in this
@@ -924,6 +932,13 @@ def install_wrapper(sym):
 
 
 def create_receiving(function_exports):
+  if settings.WASM_ESM_INTEGRATION:
+    exports = [f'{f} as {asmjs_mangle(f)}' for f in function_exports]
+    exports.append('memory as wasmMemory')
+    exports.append('__indirect_function_table as wasmTable')
+    exports = ',\n  '.join(exports)
+    return f"import {{\n  {exports}\n}} from './{settings.WASM_BINARY_FILE}';\n\n"
+
   # When not declaring asm exports this section is empty and we instead programmatically export
   # symbols on the global object by calling exportWasmSymbols after initialization
   if not settings.DECLARE_ASM_MODULE_EXPORTS: