Remove `useESModules` in favor of conditional exports for `@babel/runtime` #12295

nicolo-ribaudo · 2020-11-02T15:56:23Z

Q	A
Fixed Issues?	Ref: #10746 (comment)
Patch: Bug Fix?
Major: Breaking Change?	Yes
Minor: New Feature?
Tests Added + Pass?	Yes
Documentation PR Link
Any Dependency Changes?
License	MIT

Using Node.js' exports mappings, we can get rid of the "useESModules": true option: it will automatically pick up the preferred version based on how the helper is requried/imported.

exports are also supported by webpack and rollup, but I have structured the files in a way that, even if exports isn't supported by some tool, it will load the CJS version because the file is named index.js.

In order to avoid loading both the CommonJS and the ESM version, which can lead to duplicated state, I structured exports so that:

Node.js always loads the CommonJS version. When using require it "just works", when using import it will get the value of module.exports. (The node export condition)
When using Webpack/Rollup, it will always load the .mjs version. Webpack requires that the CJS and ESM files have the same interface, so the CJS helpers also export their function as module.exports.default. (The module condition)
For other targets that don't support the module/node conditions, it will always load the .mjs version. (The default condition)

babel-bot · 2020-11-02T16:00:14Z

Build successful! You can test your changes in the REPL here: https://babeljs.io/repl/build/31682/

codesandbox-ci · 2020-11-02T16:04:36Z

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 948c463:

Sandbox	Source
babel-repl-custom-plugin	Configuration
babel-plugin-multi-config	Configuration

Andarist

Just a single comment so far but I will also have to check out this branch to see what exactly is being built, the dir structure etc - will be easier to check some things that way. Gonna do that later, hopefully today.

Andarist · 2020-11-02T17:36:42Z

packages/babel-plugin-transform-runtime/scripts/build-dist.js

+  for (const helperName of helpers.list) {
+    const helperPath = path.join("helpers", helperName);
+    helperSubExports[`./${helperPath}`] = {
+      import: writeHelperFile(runtimeName, pkgDirname, helperPath, helperName, {


for the ideal experience, the very same value should be repeated for a priority "module" condition that is supported by webpack (and will most likely be supported by Rollup as well), in node require cant load ESM so it can lead to the same module being loaded twice (once for ESM loader and once for the CJS loader) which ain't ideal for the web consumers so this condition allows the same file (authored in ESM) to be loaded for both loaders, so this behaves pretty much as the package.json#module

Andarist · 2020-11-02T17:58:15Z

Ok, I've managed to check this quickly while hanging over the phone - one additional thing. I believe that it would generally be best (and required for "module" condition) to keep the same interface of CJS and ESM versions of a single package. That would mean dropping the special-casing of CJS helpers (and other Babel modules) when inserting imports through a helper + changing the content of those modules so they use .default like everything else rather than a direct assignment to module.exports.

As those modules are mostly consumed automatically through plugins this shouldn't be much of a problem even for CJS-only consumers.

Andarist · 2020-11-05T17:07:09Z

packages/babel-runtime/helpers/toArray/index.js

+  return arrayWithHoles(arr) || iterableToArray(arr) || unsupportedIterableToArray(arr) || nonIterableRest();
+}
+
+module.exports = _toArray;


as mentioned on Slack - this won't work because one can write:

// node_modules/cast-array/index.js const toArray = require("@babel/runtime/helpers/toArray") module.exports = maybeArr => toArray(maybeArr) // it doesn't quite matter what's here, the prior line is important

and then one can consume such a package using webpack (4 and 5 included, maybe up to 2) with:

import castArray from 'cast-array' castArray(document.querySelectorAll('.foo'))

Here webpack would consume the first module (cast-array) and assume that what it has imported has the shape of module.exports = { default: toArray } which would fail loudly at runtime (or at build time? not sure actually).

one can write

This package is only meant to be consumed by generated code, not manually. It webpack throws in that case, or generates invalid code, that's ok. Babel will always inject imports like require("@babel/runtime/helpers/toArray").default.

Whats the reason for the direct assignment then? Why it exists? When it will be used?

So that we can emit this code in Node.js:

import toArray from "@babel/runtime/helpers/toArray"

instead of

import toArray_moduleExports from "@babel/runtime/helpers/toArray" const toArray = toArray_moduleExports.default;

because Node.js's default import is the value of module.exports.

Could u describe the scenario end to end?

I believe that a problem is that the output consumer might not be a final consumer. The transform-runtime plugin is often used when building packages and im mostly worried about scenarios related to that while i think u are describing the former scenario - correct me if i have misunderstood your intention

There are different usages I'm thinking of, and I don't think that whether the file is a pre-compiled package or a compiled source file of the final app matters.

.mjs output, used in Node.js (:warning: This is where we need module.exports to be the helper itself)
import toArray from "@babel/runtime/helpers/toArray";
This will load @babel/runtime/helpers/toArray/index.cjs, and it's module.exports will be used by Node.js as the value of toArray. Internally, Node.js does something like const toArray = require("@babel/runtime/helpers/toArray/index.cjs");

.cjs output, used in Node.js
const toArray = require("@babel/runtime/helpers/toArray").default;
This will load @babel/runtime/helpers/toArray/index.cjs, and it's module.exports.default will be used as the value of toArray.

.mjs output, used in [bundler]
import toArray from "@babel/runtime/helpers/toArray";
This will load @babel/runtime/helpers/toArray/index.mjs, and Webpack will internally use the default property of that file's namespace object (import("@babel/runtime/helpers/toArray/index.mjs").default).

.cjs output, used in [bundler]
const toArray = require("@babel/runtime/helpers/toArray").default;
This will load @babel/runtime/helpers/toArray/index.mjs, and it's default will be used as the value of toArray (import("@babel/runtime/helpers/toArray/index.mjs").default).

.mjs output, directly used in browsers (for example, with Snowpack)
import toArray from "@babel/runtime/helpers/toArray";
This will load @babel/runtime/helpers/toArray/index.mjs, and use it's default export as the value of toArray (similarly to bundlers)

.cjs output, directly used in browsers (for example, with Snowpack)
It doesn't work (as expected).

By doing so, Node.js will only load the .cjs file and [bundler] will only load the .mjs file, and they will never be loaded together.

I think this indeed might work 👍 Would not bet money on it though 😉 but that's mainly because how the overall story is complicated, not because of the chosen approach

Andarist · 2020-11-06T20:43:21Z

...ges/babel-plugin-transform-runtime/test/fixtures/use-options/corejs-useES6Modules/output.mjs

-import _inherits from "@babel/runtime-corejs3/helpers/esm/inherits";
-import _possibleConstructorReturn from "@babel/runtime-corejs3/helpers/esm/possibleConstructorReturn";
-import _getPrototypeOf from "@babel/runtime-corejs3/helpers/esm/getPrototypeOf";
+import _classCallCheck from "@babel/runtime-corejs3/helpers/classCallCheck";


is useES6Modules a thing (it's in the fixture path)? Seems like maybe this test is not relevant any longer?

Andarist · 2020-11-06T20:43:52Z

...ges/babel-plugin-transform-runtime/test/fixtures/use-options/useESModules-cjs-auto/output.js

@@ -1,10 +1,10 @@
-var _classCallCheck = require("@babel/runtime/helpers/classCallCheck");
+var _classCallCheck = require("@babel/runtime/helpers/classCallCheck").default;


similarly here but for other reasons - this PR removes useESModules so this fixture can be removed

Andarist · 2020-11-06T20:44:13Z

packages/babel-plugin-transform-runtime/test/fixtures/use-options/useESModules-cjs/output.js

@@ -1,10 +1,10 @@
-var _classCallCheck = require("@babel/runtime/helpers/classCallCheck");
+var _classCallCheck = require("@babel/runtime/helpers/classCallCheck").default;


same as https://github.com/babel/babel/pull/12295/files#r518995477

Andarist · 2020-11-06T20:44:23Z

...es/babel-plugin-transform-runtime/test/fixtures/use-options/useESModules-mjs-auto/output.mjs

-import _inherits from "@babel/runtime/helpers/esm/inherits";
-import _possibleConstructorReturn from "@babel/runtime/helpers/esm/possibleConstructorReturn";
-import _getPrototypeOf from "@babel/runtime/helpers/esm/getPrototypeOf";
+import _classCallCheck from "@babel/runtime/helpers/classCallCheck";


same as https://github.com/babel/babel/pull/12295/files#r518995477

Andarist · 2020-11-06T20:44:30Z

packages/babel-plugin-transform-runtime/test/fixtures/use-options/useESModules-mjs/output.mjs

-import _inherits from "@babel/runtime/helpers/esm/inherits";
-import _possibleConstructorReturn from "@babel/runtime/helpers/esm/possibleConstructorReturn";
-import _getPrototypeOf from "@babel/runtime/helpers/esm/getPrototypeOf";
+import _classCallCheck from "@babel/runtime/helpers/classCallCheck";


same as https://github.com/babel/babel/pull/12295/files#r518995477

Andarist · 2020-11-06T20:53:06Z

packages/babel-runtime/helpers/toArray/index.js

+}
+
+module.exports = _toArray;
+module.exports["default"] = module.exports;


Are we sure that the sole existence of .default is enough here? It seems that it might be because of the same thing being assigned both to module.exports and module.exports.default.

When consuming ESM file webpack 4 would load this file directly (as it would just fallback to /index.js because it's not aware of pkg.json#exports) and if it's using the exact same logic as Babel:

function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }

this would work even though __esModule is not present here 🤔 I'm wondering though if it still wouldn't be worth adding __esModule as maybe some other tools treat this different somehow? Although not sure how that would look like (such a tool's interop logic). Just thinking out loud.

nicolo-ribaudo · 2021-02-19T15:01:37Z

Moved to #12632

nicolo-ribaudo added 2 commits November 2, 2020 16:46

Use conditional exports in @babel/runtime for CJS/ESM

85fe4ee

Remove useESModules option from @babel/transform-runtime

fa0963e

nicolo-ribaudo added the PR: Breaking Change 💥 A type of pull request used for our changelog categories for next major release label Nov 2, 2020

nicolo-ribaudo requested a review from Andarist November 2, 2020 15:56

Andarist reviewed Nov 2, 2020

View reviewed changes

nicolo-ribaudo added 3 commits November 3, 2020 18:27

Align interface of CJS and ESM

39f5547

Update test

b4c981e

Expose package.json

d66b663

nicolo-ribaudo force-pushed the babel-runtime-dual-modules branch from cf95c47 to d66b663 Compare November 3, 2020 22:16

Fix CJS helpers generation

426ef52

nicolo-ribaudo force-pushed the babel-runtime-dual-modules branch from 64b862b to 426ef52 Compare November 4, 2020 00:25

Fix vue e2e tests

948c463

nicolo-ribaudo added the area: helpers label Nov 4, 2020

Andarist reviewed Nov 5, 2020

View reviewed changes

Andarist reviewed Nov 6, 2020

View reviewed changes

Andarist mentioned this pull request Nov 10, 2020

Add useAutoDirectory option to transform-runtime plugin #8885

Closed

JLHwung approved these changes Nov 17, 2020

View reviewed changes

emmatown mentioned this pull request Jan 5, 2021

Babel helper things preconstruct/preconstruct#358

Merged

nicolo-ribaudo mentioned this pull request Jan 14, 2021

Use conditional exports in @babel/runtime for CJS/ESM #12632

Merged

nicolo-ribaudo closed this Feb 19, 2021

nicolo-ribaudo deleted the babel-runtime-dual-modules branch February 19, 2021 15:01

github-actions bot added the outdated A closed issue/PR that is archived due to age. Recommended to make a new issue label May 22, 2021

github-actions bot locked as resolved and limited conversation to collaborators May 22, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Remove `useESModules` in favor of conditional exports for `@babel/runtime` #12295

Remove `useESModules` in favor of conditional exports for `@babel/runtime` #12295

nicolo-ribaudo commented Nov 2, 2020 •

edited by gitpod-io bot

babel-bot commented Nov 2, 2020 •

edited

codesandbox-ci bot commented Nov 2, 2020 •

edited

Andarist left a comment

Andarist Nov 2, 2020

Andarist commented Nov 2, 2020

Andarist Nov 5, 2020 •

edited

nicolo-ribaudo Nov 5, 2020

Andarist Nov 5, 2020

nicolo-ribaudo Nov 5, 2020 •

edited

Andarist Nov 5, 2020

Andarist Nov 5, 2020

nicolo-ribaudo Nov 5, 2020 •

edited

Andarist Nov 6, 2020

Andarist Nov 6, 2020

Andarist Nov 6, 2020

Andarist Nov 6, 2020

Andarist Nov 6, 2020

Andarist Nov 6, 2020

Andarist Nov 6, 2020

nicolo-ribaudo commented Feb 19, 2021

		@@ -1,10 +1,10 @@
		var _classCallCheck = require("@babel/runtime/helpers/classCallCheck");
		var _classCallCheck = require("@babel/runtime/helpers/classCallCheck").default;

Remove useESModules in favor of conditional exports for @babel/runtime #12295

Remove useESModules in favor of conditional exports for @babel/runtime #12295

Conversation

nicolo-ribaudo commented Nov 2, 2020 • edited by gitpod-io bot

babel-bot commented Nov 2, 2020 • edited

codesandbox-ci bot commented Nov 2, 2020 • edited

Andarist left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Andarist commented Nov 2, 2020

Andarist Nov 5, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nicolo-ribaudo Nov 5, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nicolo-ribaudo Nov 5, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nicolo-ribaudo commented Feb 19, 2021

Remove `useESModules` in favor of conditional exports for `@babel/runtime` #12295

Remove `useESModules` in favor of conditional exports for `@babel/runtime` #12295

nicolo-ribaudo commented Nov 2, 2020 •

edited by gitpod-io bot

babel-bot commented Nov 2, 2020 •

edited

codesandbox-ci bot commented Nov 2, 2020 •

edited

Andarist Nov 5, 2020 •

edited

nicolo-ribaudo Nov 5, 2020 •

edited

nicolo-ribaudo Nov 5, 2020 •

edited