Eliminate `createRequire`/`require` from `EXPORT_ES6` output by vogel76 · Pull Request #26384 · emscripten-core/emscripten

vogel76 · 2026-03-03T22:57:43Z

When building with -sEXPORT_ES6, the generated JavaScript currently uses createRequire(import.meta.url) to polyfill require(), then calls require() for Node.js built-in modules. This breaks bundlers (webpack, Rollup, esbuild, Vite) and Electron's renderer process, forcing users to post-process emscripten output with sed or custom plugins to strip out the offending calls.

This PR replaces all require() calls with await import() when EXPORT_ES6 is enabled, eliminating the need for createRequire entirely.

Why this is safe

EXPORT_ES6 requires MODULARIZE (enforced in tools/link.py). MODULARIZE wraps the module body in an async function, so await is valid at the top level of the generated code.
The preprocessor already supports this pattern. await import(...) is transformed to an EMSCRIPTEN$AWAIT$IMPORT placeholder during preprocessing (parseTools.mjs:83) and restored during linking (link.py:2136). This mechanism is already used elsewhere in the codebase.
Node.js built-in modules expose identical ESM interfaces. (await import('node:fs')).readFileSync works identically to require('node:fs').readFileSync. For CJS npm packages like ws, .default gives the module.exports value.
No behavioral change for non-ES6 builds. All changes are guarded by #if EXPORT_ES6 / #else preprocessor conditionals. The existing require() code path is untouched.

Approach

The changes split naturally into two categories:

Shell and runtime files (top-level async context where await works directly):

src/shell.js — Remove the createRequire block. Use await import() for worker_threads, fs, path, url, util.
src/shell_minimal.js — Same pattern for worker_threads and fs. Replace __dirname with new URL(..., import.meta.url) for wasm file loading.
src/runtime_debug.js — Skip local require() for fs/util when EXPORT_ES6; reuse outer-scope variables from shell.js.
src/runtime_common.js — Guard perf_hooks require() with EXPORT_ES6 alternative.
src/preamble.js — Hoist await import('node:v8') above instantiateSync() for NODE_CODE_CACHING (can't use await inside a sync function).

Library files (synchronous function bodies where await is unavailable):

Library functions execute in synchronous context, so await import() cannot be called inline. Instead, we define library symbols initialized at module top level (async context) and reference them via __deps:

Symbol	Module	Used by
`$nodeOs`	`node:os`	`libatomic.js`, `libwasm_worker.js`
`$nodeCrypto`	`node:crypto`	`libwasi.js` (`$initRandomFill`)
`$nodeChildProcess`	`node:child_process`	`libcore.js` (`_emscripten_system`)
`$nodeWs`	`ws` (`.default`)	`libsockfs.js` (WebSocket connect + listen)
`$nodePath`	`node:path`	`libnodepath.js` (NODERAWFS)

Shared symbols live in a new src/lib/libnode_imports.js, registered in src/modules.mjs when EXPORT_ES6 is enabled.

Intentionally skipped

src/lib/libembind_gen.js — Build-time code running in Node.js directly, not in emitted runtime JS.
src/closure-externs/closure-externs.js — createRequire extern kept; still needed for the non-ES6 path.

What changes in the output

Before (EXPORT_ES6):

import { createRequire } from 'node:module';
var require = createRequire(import.meta.url);
var fs = require('node:fs');

After (EXPORT_ES6):

var fs = await import('node:fs');

The non-ES6 path remains unchanged:

var fs = require('node:fs');

Files modified

13 files modified, 1 new file — 123 insertions, 12 deletions (source files only).

Testing

All existing ESM tests pass:

Test	Result
`test_esm` (default, node, pthreads variants)	PASS
`test_esm_worker` (default, node variants)	PASS
`test_esm_worker_single_file`	PASS
`test_esm_closure`	PASS
`test_esm_implies_modularize`	PASS
`test_esm_requires_modularize`	PASS
`test_pthread_export_es6` (default, trusted variants)	PASS

Additionally verified:

emcc -sEXPORT_ES6 -sMODULARIZE output contains zero createRequire or require( occurrences
emcc -sEXPORT_ES6 -sMODULARIZE -pthread output contains zero createRequire or require( occurrences
Non-ES6 builds still use require() as before (no regression)

Related issues

Node + Electron environment is getting more difficult to use #24789 — EXPORT_ES6 output contains require() which breaks bundlers
Shouldn't EXPORT_ES6 use only ES6 semantics? #20503 — createRequire breaks Electron renderer
[Feature Request] Support building for both UMD/ESM #21899 — ES module output not compatible with bundlers
Eliminate the circular dependency between the main loader and the worker #20580 — webpack fails on emscripten ES6 output
Build mysteriously fails with {"type":"module"} package.json in the parent directory #17431 — Feature request: native ESM support without require()
Add a new ESM option for ES6 module support #15060 — require() in ESM output breaks Rollup

Related PRs

Prefix node built-in module imports with node:. #18235 — Earlier attempt to address this (partial)
Support ES6 module syntax in Acorn, Babel and Closure #23730 — Related ESM improvements

sbc100

Wow, thanks for working on this! Nice work.

sbc100 · 2026-03-03T23:27:09Z

src/lib/libwasi.js

    if (ENVIRONMENT_IS_NODE) {
+#if EXPORT_ES6
+      return (view) => nodeCrypto.randomFillSync(view);
+#else


To keep thing simpler could we just always use the nodeCrypto global via __deps? (i.e. make the difference only in how nodeCrypto is globally defined?

src/lib/libnode_imports.js

src/shell_minimal.js

sbc100 · 2026-03-03T23:34:21Z

src/shell_minimal.js

+  Module['wasm'] = fs.readFileSync(new URL('{{{ TARGET_BASENAME }}}.wasm', import.meta.url));
+#endif
+#endif
+#else


This seems like a lot of extra complexity/duplication. Is there some way to avoid it maybe?

vogel76 · 2026-03-04T23:20:04Z

@sbc100 I hope your remarks have been addressed in added fixup commits. Once you accept it, I will do autosquash rebase to leave only actual commits in clean history.

sbc100 · 2026-03-05T00:06:01Z

Is it possible to write a test for this?

When you say "This breaks bundlers", do you know why our current bundler tests in test_browser.py are working? (see test_rollup and test_vite). Would you be able to write a failing test for this breakage?

sbc100 · 2026-03-05T00:07:43Z

Re-commiting, we always squash all changes in the emscripten repo.

If you think this change can be split into to commits then please send a two separate PRs. This is just how we do things in emscripten. It helps keep the tests passing on every commit (for the benefit of bisectors).

src/lib/libcore.js

src/preamble.js

sbc100 · 2026-03-05T00:12:48Z

src/preamble.js

+    var v8 = nodeV8;
+#else
    var v8 = require('node:v8');
+#endif


No need for this var anymore if you use makeNodeImport I thinik?

I think you for this globalVar its reasonable to call it v8?

src/runtime_common.js

sbc100 · 2026-03-05T00:16:56Z

src/shell_minimal.js

-  var fs = require('node:fs');
+  var fs = {{{ makeNodeImport('node:fs') }}};
 #if WASM == 2
-  if (globalThis.WebAssembly) Module['wasm'] = fs.readFileSync(__dirname + '/{{{ TARGET_BASENAME }}}.wasm');


Does this code (which uses __dirname) simply not work with EXPORT_EST today?

If not, this seems like maybe a separate fix that we could land in isolation. e.g. Fix for EXPORT_ES6 + MINIMAL_RUNTIME + ???

vogel76 · 2026-03-05T08:17:29Z

Is it possible to write a test for this?

When you say "This breaks bundlers", do you know why our current bundler tests in test_browser.py are working? (see test_rollup and test_vite). Would you be able to write a failing test for this breakage?

Sure - will add such tests. The sake of such work are maintenance problems of our Hive blockchain interfacing library: wax which compiles blockchain protocol C++ code into wasm and uses it at TS/JS level. We have set of tests related to bundlers and different frameworks where we got problems while loading wasm etc.

https://gitlab.syncad.com/hive/wax/-/tree/develop/examples/ts?ref_type=heads

vogel76 · 2026-03-09T07:39:23Z

Is it possible to write a test for this?

When you say "This breaks bundlers", do you know why our current bundler tests in test_browser.py are working? (see test_rollup and test_vite). Would you be able to write a failing test for this breakage?

Deeper analysis gave conclusions why Existing tests don't catch the require() problem.
The browser bundler tests all use -sENVIRONMENT=web, which means the Node.js code paths (containing require('node:fs') etc.) are compiled out entirely. The node-side test_rollup in test_other.py does trigger those paths, but rollup marks node builtins as external by default — so it silently passes them through without error.

The real breakage happens when:

No -sENVIRONMENT=web — output includes both web and node code paths
Bundler targets web — it tries to resolve require('node:fs') and fails
Framework SSR — Next.js/Nuxt process ESM server-side, require() in ESM is a syntax error in strict ESM mode

I extended test to cover more usecases altough adding tests covering whole frameworks seems to heavy for your project. Our wax library covers that...

sbc100 · 2026-03-09T15:44:28Z

The node-side test_rollup in test_other.py does trigger those paths, but rollup marks node builtins as external by default — so it silently passes them through without error.

I'm curious about this case. I'd love to add a test to test_other.py that fails on main due to the "This breaks bundlers" issue you mention.

Are you saying that rollup doesn't actually break (since it marks node builtins as external by default)? If so, is rollup just not effected by this bug?

Is vite effected? Could we add a test to test_other.py alongside test_rollup? We already have a dependency on both vite and rollup for running these tests.

vogel76 · 2026-03-09T20:35:09Z

The node-side test_rollup in test_other.py does trigger those paths, but rollup marks node builtins as external by default — so it silently passes them through without error.

I'm curious about this case. I'd love to add a test to test_other.py that fails on main due to the "This breaks bundlers" issue you mention.

Are you saying that rollup doesn't actually break (since it marks node builtins as external by default)? If so, is rollup just not effected by this bug?

Is vite effected? Could we add a test to test_other.py alongside test_rollup? We already have a dependency on both vite and rollup for running these tests.

Here are new tests targeted to main where they are expected to fail:
#26419

They shall pass here ofc. Once you accept it, I will cherry-pick them to this PR

sbc100 · 2026-03-09T20:44:58Z

Those tests look great thanks!

sbc100

(sorry I forgot the send my pending comment)

sbc100 · 2026-03-09T20:48:37Z

src/lib/libwasi.js


-#if ENVIRONMENT_MAY_BE_SHELL
+#if ENVIRONMENT_MAY_BE_NODE && MIN_NODE_VERSION < 190000
+  $nodeCrypto: "ENVIRONMENT_IS_NODE ? {{{ makeNodeImport('node:crypto') }}} : undefined",


I think maybe the ENVIRONMENT_IS_NODE ? xxx : undefined pattern can just be folded into makeNodeImport?

You might also want to add assert(!ENVIRONMENT_MAY_BE_NODE, "makeNodeImport called when environment can never be node") to the macro.

sbc100 · 2026-03-19T22:36:14Z

test/test_other.py

+    # require() calls for node support which vite externalizes but leaves
+    # as require() in the bundle output.
+    self.run_process([EMCC, test_file('hello_world.c'), '-sEXPORT_ES6', '-sEXIT_RUNTIME',
+                      '-sMODULARIZE', '-o', 'hello.mjs'])


If you pass -sEXPORT_ES6 you can remove -sMODULARIZE here and above.

Also does this test actually need -sEXIT_RUNTIME? If not maybe just delete it.

Also, I think can can even delete -sEXPORTE_ES6 since emcc will enable that by default when the output filename ends in .mjs.

vogel76 · 2026-03-19T23:14:40Z

Changes in this update:

Fixed ws module eager loading regression in libsockfs.js
- The original $nodeWs library symbol caused ws to load eagerly at module init time whenever SOCKFS was included, breaking builds where ws isn't installed (Cannot find module 'ws').
- Replaced with $nodeRequire — a createRequire-based polyfill that's only pulled in when SOCKFS is linked. Socket code uses nodeRequire('ws') for lazy synchronous loading. Non-socket ESM builds remain completely require()-free.
Folded ENVIRONMENT_IS_NODE guard into makeNodeImport (per sbc100's review)
- makeNodeImport(module, guard=true) now wraps the result in ENVIRONMENT_IS_NODE ? ... : undefined by default, eliminating the repetitive pattern in library symbol definitions.
- makeNodeImport(module, false) returns the raw expression for callers already inside if (ENVIRONMENT_IS_NODE) blocks.
- Added assert(ENVIRONMENT_MAY_BE_NODE) to catch misuse.
Rebased onto latest main (includes Binaryen 127 update, fixing ~95% of previous CI failures caused by version mismatch).

Known remaining issues:

Closure Compiler + ESM: Closure runs before the MODULARIZE async wrapper, so it sees await import() at the top level and fails with Parse error. await must be inside asynchronous function. Needs a separate fix (placeholder approach or running MODULARIZE before Closure).
Audio worklet ES6 tests (test_audio_worklet_es6, test_audio_worklet_pthreads_es6): runtime failures — investigating whether top-level await in the module affects AudioWorklet.addModule().

When EXPORT_ES6 is enabled, the generated JS used createRequire() to polyfill require(), which breaks bundlers (webpack, Rollup, esbuild) and Electron's renderer process. Since EXPORT_ES6 requires MODULARIZE, the module body is wrapped in an async function where await is valid. - shell.js: Remove createRequire block entirely. Use await import() for worker_threads, fs, path, url, util. Replace __dirname with import.meta.url for path resolution. - shell_minimal.js: Same pattern for worker_threads and fs. Replace __dirname with new URL(..., import.meta.url) for wasm file loading. - runtime_debug.js: Skip local require() for fs/util when EXPORT_ES6, reuse outer-scope variables from shell.js instead. - runtime_common.js: Guard perf_hooks require() with EXPORT_ES6 alternative. - preamble.js: Hoist await import('node:v8') above instantiateSync() for NODE_CODE_CACHING since await can't be used inside sync functions.

Library functions run in synchronous context where await is unavailable. Define top-level library symbols that use await import() at module init time, then reference them via __deps from synchronous functions. - Add libnode_imports.js with shared $nodeOs symbol, register in modules.mjs when EXPORT_ES6 is enabled. - libatomic.js, libwasm_worker.js: Use $nodeOs for os.cpus().length instead of require('node:os'). - libwasi.js: Define $nodeCrypto for crypto.randomFillSync in $initRandomFill. Combine conditional __deps to avoid override. - libcore.js: Define $nodeChildProcess for _emscripten_system. - libnodepath.js: Switch $nodePath initializer to await import(). - libsockfs.js: Define $nodeWs ((await import('ws')).default) for WebSocket constructor in connect() and Server in listen().

Bundlers (webpack, rollup, vite, esbuild) and frameworks (Next.js, Nuxt) cannot resolve CommonJS require() calls inside ES modules. This test statically verifies that EXPORT_ES6 output uses `await import()` instead of `require()` for Node.js built-in modules, and that the `createRequire` polyfill pattern is not present. Parameterized for default, node-only, and pthreads configurations to cover the various code paths that import Node.js built-ins (fs, path, url, util, worker_threads).

…ire() Add two tests that verify EXPORT_ES6 output is valid ESM and works with bundlers: - test_webpack_esm_output_clean: Compiles with EXPORT_ES6 and default environment (web+node), then builds with webpack. On main, webpack hard-fails because it cannot resolve 'node:module' (used by emscripten's createRequire polyfill). This breaks any webpack/Next.js/Nuxt project. - test_vite_esm_output_clean: Compiles with EXPORT_ES6 and default environment, then builds with vite. On main, vite externalizes 'node:module' for browser compatibility, emitting a warning. The resulting bundle contains code referencing unavailable node modules. These tests are expected to fail on main and pass after eliminating require() from EXPORT_ES6 output.

The previous fix moved await import() for node:fs and node:util outside dbg() to module scope. This broke test_dbg because dbg() can be called from --pre-js before those module-scope imports execute. Use lazy initialization instead: declare dbg_node_fs/dbg_node_utils early but leave them undefined. Initialize them in shell.js after fs and utils are loaded (reusing the same imports). dbg() checks if the modules are available and falls back to console.warn if not. This handles all cases: - dbg() from --pre-js (before init): uses console.warn - dbg() after init on Node.js with pthreads: uses fs.writeSync - dbg() in browser/non-node: uses console.warn

In ESM mode (WASM_ESM_INTEGRATION), the runtime uses dynamic import() instead of require() for node modules. Update the test_environment assertion to check for 'import(' when in ESM mode, rather than always expecting 'require('. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

vogel76 · 2026-03-20T12:05:52Z

@sbc100 could you take a look for test-bun and test-deno failures? Probably I will need some help in getting local env. to reproduce problems. Please point me some doc or scripts how to setup it. Best if you have some docker image to run them in...

vogel76 changed the title ~~eliminate require~~ Eliminate createRequire/require() from EXPORT_ES6 output Mar 3, 2026

sbc100 reviewed Mar 3, 2026

View reviewed changes

sbc100 requested a review from RReverser March 3, 2026 23:34

sbc100 changed the title ~~Eliminate createRequire/require() from EXPORT_ES6 output~~ Eliminate createRequire/require from EXPORT_ES6 output Mar 4, 2026

vogel76 force-pushed the bw_eliminate_require branch from 0ec991e to 6b74d2a Compare March 4, 2026 23:17

vogel76 force-pushed the bw_eliminate_require branch from 6b74d2a to 8f585b7 Compare March 4, 2026 23:31

sbc100 approved these changes Mar 5, 2026

View reviewed changes

vogel76 force-pushed the bw_eliminate_require branch from 8f585b7 to 6c822be Compare March 5, 2026 22:57

vogel76 mentioned this pull request Mar 9, 2026

Add bundler integration tests verifying EXPORT_ES6 output has no requ… #26419

Closed

vogel76 force-pushed the bw_eliminate_require branch from 2270aac to d068717 Compare March 19, 2026 21:31

sbc100 reviewed Mar 19, 2026

View reviewed changes

vogel76 force-pushed the bw_eliminate_require branch from d068717 to 8b2fb1c Compare March 19, 2026 22:25

sbc100 reviewed Mar 19, 2026

View reviewed changes

vogel76 force-pushed the bw_eliminate_require branch from 8b2fb1c to 23863c1 Compare March 19, 2026 23:14

Bartek Wrona added 4 commits March 20, 2026 09:17

vogel76 force-pushed the bw_eliminate_require branch from 23863c1 to 2b964d5 Compare March 20, 2026 09:18

vogel76 force-pushed the bw_eliminate_require branch from 30c1f96 to 14fdc3b Compare March 20, 2026 10:48

Conversation

vogel76 commented Mar 3, 2026 • edited by sbc100 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why this is safe

Approach

Intentionally skipped

What changes in the output

Files modified

Testing

Related issues

Related PRs

Uh oh!

sbc100 left a comment

Choose a reason for hiding this comment

Uh oh!

sbc100 Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

sbc100 Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

vogel76 commented Mar 4, 2026

Uh oh!

sbc100 commented Mar 5, 2026

Uh oh!

sbc100 commented Mar 5, 2026

Uh oh!

Uh oh!

Uh oh!

sbc100 Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sbc100 Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

vogel76 commented Mar 5, 2026

Uh oh!

vogel76 commented Mar 9, 2026

Uh oh!

sbc100 commented Mar 9, 2026

Uh oh!

vogel76 commented Mar 9, 2026

Uh oh!

sbc100 commented Mar 9, 2026

Uh oh!

sbc100 left a comment

Choose a reason for hiding this comment

Uh oh!

sbc100 Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

sbc100 Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

vogel76 commented Mar 19, 2026

Uh oh!

vogel76 commented Mar 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vogel76 commented Mar 3, 2026 •

edited by sbc100

Loading