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

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).

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!

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

Bartek Wrona added 2 commits March 5, 2026 14:57

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

Open

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vogel76 commented Mar 3, 2026 •

edited by sbc100

Loading