Tracking issue: require(esm)

[joyeecheung]

Before it's unflagged

• Figure out default export interop with transpilers, either adding __esModule to required ESM on our end (module: add __esModule to require()'d ESM #52166), or transpilers update themselves to check the result returned by require():
• conditional exports for module, regardless of whether it's loaded by require or import. Something like module which is recognized by Webpack and Rollup would be good (maybe this doesn't need to block unflagging, but should be done before stablization) module: implement the "module-sync" exports condition #54648
• Move experimental warning to where require() is actually handling a ESM

Before it is promoted to be stable:

• Implement detection module: support ESM detection in the CJS loader #52047
• Some marker to customize the default exports returned by require(esm) module: support 'module.exports' interop export name in require(esm) #54563
• Support module customization hooks doc: add synchronous hooks proposal loaders#198

Nice-to-haves:

• Add API for dumping or inspecting the consolidated CJS and EJS module graph #52180
• Provide some mechanism to conditionally and synchronously import modules (or just builtins) from ESM #52599 (fixed in process: add process.getBuiltinModule(id) #52762)
• Better documentation on how to publish packages in a post-require-esm era/migration guide: https://github.com/nodejs/package-examples

Bug fixes & changes:

• module: disallow CJS <-> ESM edges in a cycle from require(esm) #52264
• module: fix submodules loaded by require() and import() #52487
• module: support ESM detection in the CJS loader #52047
• module: cache synchronous module jobs before linking #52868
• module: add __esModule to require()'d ESM #52166
• module: remove bogus assertion in CJS entrypoint handling with --import #54592
• module: implement the "module-sync" exports condition #54648
• module: check --experimental-require-module separately from detection #55250
• module: include module information in require(esm) warning #55397
• module: trim off internal stack frames for require(esm) warnings #55496
• module: allow ESM that failed to be required to be re-imported #55502
• module: fix error thrown from require(esm) hitting TLA repeatedly #55520
• module: do not warn when require(esm) comes from node_modules #55960
• module: mark evaluation rejection in require(esm) as handled #56122
• module: only emit require(esm) warning under --trace-require-module #56194

Related features that interoperate with require(esm) and need to be considered when being backported together:

• module: unflag detect-module #53619
• module: add --experimental-strip-types #53725

For v22.x backport (see a summary of regression analysis in #55217 (comment))

• process: add process.features.require_module #55241
• module: use kNodeModulesRE to detect node_modules #55243
• src: implement IsInsideNodeModules() in C++ #55286
• [v22.x] backport unflagging of --experimental-require-module and related fixes/refactorings #55217

For v20.x backport: TBD

[GeoffreyBooth]

@nodejs/loaders

[jakebailey]

I just wanted to note it here, but it would be super super awesome if (once stable) this were backported to Node 20/22 or even Node 18 if still in support. I'd love to be able to propose a change to switch TypeScript to ESM (given I have it working without breaking CJS consumers), but the time horizon of Node 22 being the oldest supported version is pretty daunting.

It also seems like there is a hacky way using multiple entrypoints that could allow for TS to grab Node's builtins conditionally without #52599/#52762, though none of that is possible without require(ESM), of course.

Even without TypeScript's use case, I think the feature itself is a really important one for the ecosystem. Backporting would really make ESM changeovers a lot less painful.

[Andarist]

IIRC from some Twitter threads - there is a plan to backport this once the feature stabilizes.

[joyeecheung]

Regarding the conditional exports, @guybedford suggested to implement just the module condition that Rollup and Webpack already recognize. I have a WIP but need to do some testing which involves many combinations of test cases 😵‍💫 but will also do some npm crawling to see if it can be picked up/is in conflict with any existing popular packages.

[GeoffreyBooth]

@guybedford suggested to implement just the module condition that Rollup and Webpack already recognize.

The module top level field, or within exports?

Personally I think require-module makes more sense, as it would complement the existing require and import keys that Node supports.

[joyeecheung]

Opened PR for "module" in #54648

Personally I think require-module makes more sense, as it would complement the existing require and import keys that Node supports.

If we are starting from scratch, yes, but then the "module" condition has already been adopted by bundlers that support require(esm) in the wild, so it seems better to go along with the existing convention. See https://gist.github.com/sokra/e032a0f17c1721c71cfced6f14516c62