Support named exports in Node.js native ES2015 modules implementation #38

dantman · 2018-03-31T06:28:09Z

I would appreciate it if we kept the merits of .mjs and how Node.js chose to implement ES2015 modules out of the discussion here. We should just accept the fact that ES2015 modules are getting a native implementation in Node.js, this is what we have to work with, and focus on fixing React so that it works with the implementation we are getting.

…entation

Jessidhia · 2018-06-15T04:38:29Z

text/0000-native-esmodules.md

+
+- ESM code **must** be inside of a `.mjs` file
+- ESM code **must** use ES2015 `import` and `export` and cannot use `require`
+- ESM code **must** declare all of its named exports in the `.mjs` file or they must come from another `.mjs` file exported using `export * from './somefile'`. (You likely could use `*` on a CommonJS module, but it would only export `default`)


export * from explicitly ignores reexporting a default export; so it'd export nothing.

To completely reexport all exports of a module you need both export * from and export { default } from for the same module.

Jessidhia · 2018-06-15T04:40:06Z

text/0000-native-esmodules.md

+export const cloneElement = React.cloneElement;
+export const createFactory = React.createFactory;
+export const isValidElement = React.isValidElement;
+export const version = React.version;


These can even be drastically simplified to:

export const { Children, createRef, Component, // ... etc } = React

Jessidhia · 2018-06-15T04:41:15Z

text/0000-native-esmodules.md

+  - Alternatively, React.js could exclusively export named exports and an alternative to `index.js` could both `export * from './React';` and `import * as React from 'react'; export default React;` to get the `React` object as a free side effect.
+- The build process will need to output `./esm/react.{production.min,development}.mjs` bundles in addition to the normal `./cjs/` bundles. I expect these will just be the Rollup bundle already being generated but without the module transpilation step.
+- A `index.mjs` will sit at the root beside `index.js`, it will act the same as `index.js` but will export the `./esm` bundles using ES2015 exports instead of the `./cjs` bundles.
+  - Unresolved: It is not actually possible to do the `if (process.env.NODE_ENV === 'production') {` conditional that `index.js` does in ESM, ES modules require that import is at the top of the file and does not permit conditional importing.


It is possible but only with dynamic import(), and that also requires that anything that must go through that code path be made async.

It'd still work without going with async imports if the module body itself has no side-effects; even if imported, it'll just do nothing, and can be removed by dead code elimination.

I think the most natural solution is to do conditional re-exports.
Like

export const createElement = (process.env.NODE_ENV === 'production') ? createElementProd : createElementDev;

in the entry point. I don't think the ecosystem is ready for this yet though, given how fragile tree shaking is.

Here's how you can test treeshakability without assumptions.
https://github.com/TrySound/rollup-plugin-size-snapshot/blob/master/src/treeshakeWithWebpack.js#L15

gaearon · 2018-06-15T14:45:12Z

text/0000-native-esmodules.md

+
+Alternatively we could decide that we are not going to support named imports of React from ESM.
+
+This will not be a breaking change. Use of .mjs and ESM is opt-in functionality. All packages using babel or a bundler to access node will keep working with the non-spec compliant handling of named exports from CommonJS modules.


Unless their build system automatically chooses mjs when it's available. In this case it would be breaking.

.mjs files aren't supposed to be imported from require in .js files (including all current babel ES6 import usage in .js, which really uses require behaviour under the hood).

In fact the esm page explicitly states that "require('./foo.mjs') is unsupported because "ES Modules have differing resolution and timing".

Any build-system automatically choosing .mjs when available would be violating ESM.

gaearon · 2018-06-15T14:45:55Z

text/0000-native-esmodules.md

+
+This will not be a breaking change. Use of .mjs and ESM is opt-in functionality. All packages using babel or a bundler to access node will keep working with the non-spec compliant handling of named exports from CommonJS modules.
+
+The only requirement will be that if someone decides to switch to `.mjs` and opt-in to using ESM instead of transpiling/bundling, they will be required to refactor their entire codebase to use `React.Component` instead of named exports.


Also that 90% of tutorials / examples will be wrong. Seems like a pretty bad situation to be in. On the other hand TS already enforces using named imports only. I dunno.

It seems like it's reasonable to provide a default export but slowly encourage people to using named or namespace imports instead? And maybe eventually drop the default one.

I already migrated in a bunch of react packages. I think the best thing we can do is a migration to import * React from 'react' in docs and blaming import React, { Component } from 'react' which doesn't fit to any way. I could start this migration if you will write clean post in this thread.

You can use default exports with TypeScript. But it is true that using default import for React from TypeScript does not work.

Migrating to import * as React from 'react' is the wrong migration to do; it only "works" if you are using TypeScript's old commonjs emit. You should be using --esModuleInterop and using import React from 'react' instead.

Can't typescript handle both cases with interop like everybody does? Rollup, webpack, babel handle this without problems.

It "can", and you need to give --esModuleInterop. However, my point is that if you use --module es2015 or --module esnext, the resulting output (if renamed to .mjs as it needs to be) will be broken and crash at runtime on node unless you use the default import.

Can this be fixed in perspective so we could start migrating to import * as React from 'react'. Or do you think we stuck with default export forever?

That is what this RFC is meant to address.

chyzwar · 2018-07-22T13:05:13Z

It is unknown when a node will support ESM and what will be the form. https://github.com/nodejs/modules Modules team in node did not publish timeline and previous PRs in the node were postponed. This is already the third attempt of ESM in the node. IMO focus should be on browser ESM implementation that works now.

gaearon · 2018-10-19T04:58:39Z

We also need to consider what to do with react-test-renderer/shallow entry point which currently exports a function in CommonJS.

TrySound · 2018-10-19T07:30:48Z

We can do the same or just change exports to

import { TestRenderer, Shallow } from 'react-test-renderer';

sebmarkbage · 2019-03-02T06:52:22Z

I think the general thinking here is that we want to do something like this but it'd be a breaking change and only worth doing along with other breaking changes...?

dantman · 2019-03-02T07:28:38Z

I think the general thinking here is that we want to do something like this but it'd be a breaking change and only worth doing along with other breaking changes...?

The Node.js ESM implementation has been pushed back to October and has changed a bit in implementation. So the RFC is kind of on hold.

Theoretically this change should not be breaking since it only affects people writing .mjs files. Additionally Node has even changed the behaviour in a way that adding an index.mjs won't break current users using .mjs. That said there's a chance WebPack could completely screw up that plan. So perhaps it should be bundled with breaking changes anyways.

It's tangentially related. But I wonder if we should also revisit TypeScript. It's really annoying having to use import * as React from 'react'; instead of import React, {useState} from 'react';. Which could easily be solved with essentially a const React = {...}; modules.export = {...React, default: React};.

TrySound · 2019-03-02T08:45:32Z

@dantman Default export is not the right way to import from react. React is a namespace. Logically it should not be default export. Default export also requires hacks like babel plugin to transform

React.createElement()
// to
const { createElement } = React
createElement()

When bundler may do this for free and even better will not generate const { createElement } = React in every file.

Treeshaking will not be significant with react but it still can be considered as a feature.

Jessidhia · 2019-03-02T08:47:00Z

React should be a namespace. It currently is not.

dantman · 2019-03-02T08:49:36Z

Default export is not the right way to import from react. React is a namespace.

You're going to have to rally for JSX to be changed then. Because the default is React.createElement and React must be defined in context.

Treeshaking will not be significant with react but it still can be considered as a feature.

Treeshaking will be completely nonexistent. React is bundled into a single file and uses an object export.

TrySound · 2019-03-02T08:54:00Z

You're going to have to rally for JSX to be changed then. Because the default is React.createElement and React must be defined in context.

Not at all. import * as React from 'react'; is universal solution. Default export can be provided as a temporary fix.

Treeshaking will be completely nonexistent. React is bundled into a single file and uses an object export.

I'm talking about the time when react will have esm and named exports.

dantman · 2019-03-02T08:58:43Z

I'm talking about the time when react will have esm and named exports.

React's single file bundles were an intentional choice, even if React ever gets ESM it will likely still use single file bundles.

TrySound · 2019-03-02T09:01:43Z

@dantman Wait, I didn't say anything about react bundles. I like them.

My point was that react should not have default export because it increases user bundle a lot or requires babel plugins to solve the problem and still with trade offs.

gaearon · 2020-02-10T23:42:39Z

How does this proposal hold up against the latest shipped Node implementation?

dantman · 2020-02-11T01:03:25Z

How does this proposal hold up against the latest shipped Node implementation?

There seem to be some changes to the ESM handling. The general idea of the RFC seems to still be valid, but about 10% needs a few tweaks for the ESM changes.

Scanning the new https://nodejs.org/api/esm.html docs here are the things that stand out:

File extensions are now mandatory, so the wrapper would need to explicitly use .mjs and the suggestion of ./index for the main field would be removed.
.js files in a package can also be ESM if you include "type": "module" in the package.json but we're not changing the default (unless you want to switch to ESM code for React 17 with optionally a CommonJS .cjs fallback for compatibility with older node) so we'd do the opposite and explicitly declare "type": "commonjs".
Instead of placing an index.js and index.mjs next to each other, package.json has a new exports field. It supports conditional exports to direct require and import to different files, so this is how you'd setup that instead of an extension-less main.
- It's not relevant here, but if exports gains wider adoption it could mean the disappearance of needing to include lib/dist/es/module folders in imports.
The proposal I made of using an .mjs wrapper file to export named identifiers appears to be the recommended approach for packages vulnerable to the dual package hazard (where one dep doing import and another doing require would result in two instances of React being imported). So the general idea of the RFC seems to be validated by this.
The ESM docs propose a browser conditional export variant (like the variants for import/require/node). If tooling adopts this (whatever tooling people would be using to generate browser native type=module packages) then this could possibly be a solution in the future for supporting browser native module packages without dropping the compatibility with CommonJS-only versions of node. (Basically export a full module version of React and only target it to browsers. This avoids the dual package hazard because Node still uses the wrapper not vulnerable and a browser that only supports ESM won't import the CJS version).

@gaearon Is there any desire to implement this anytime soon? If so I can revisit this now and update the RFC. Otherwise I can revisit it the next time there is new news on Node's ESM implementation (changes from experimental to stable, finishes the loader API, other toolkits adopt the ESM behaviours, or a number of React users indicate they wish to use ESM).

jaydenseric · 2020-02-11T01:06:20Z

How does this proposal hold up against the latest shipped Node implementation?

The import specifiers in ESM .mjs files must contain the full filenames, including extensions (except when using a bare specifier to import from main package exports).

E.g. when importing ESM into ESM:

- import { Foo } from './Foo'
+ import { Foo } from './Foo.mjs'

E.g. when importing CJS into ESM:

- import Foo from './Foo'
+ import Foo from './Foo.js'

gaearon · 2020-02-11T16:21:01Z

@gaearon Is there any desire to implement this anytime soon?

"Soon" is relative but it's always helpful to have an up-to-date plan in case it seems like the right moment to start the work. In particular, I'm worry about how to be compatible with Node, bundlers, Flow/TS, and everything else.

Andarist · 2020-07-24T21:38:20Z

text/0000-native-esmodules.md

+
+Here are the requirements that the ESM implementation in Node.js place on us and it's behaviours we can take advantage of:
+
+- ESM code **must** be inside of a `.mjs` file


This is not technically correct - you can use .js if you put within a directory containing package.json with {"type": "module"} and you can even use .js extension for both CJS and ESM entries, u "just" need to extra package.json files. For example, Rollup is using this "trick": https://unpkg.com/browse/rollup@2.23.0/dist/es/

This could have not been true at the time of writing this RFC though.

This could have not been true at the time of writing this RFC though.

Correct. At the time of writing the RFC this is how the Node.js ESM implementation worked. It was only available in .mjs files and the type in package.json did not exist. The implementation has changed significantly and type was noted in my list of differences.

For React's purpose though, .mjs would still be used for the ES module wrapper unless the project were to make a large breaking change switching entirely to a ES modules codebase.

stefee · 2020-07-25T11:09:49Z

This RFC seems to be getting some attention at the moment. I’d like to direct any folks who are interested in it to the Node.js documentation, and in particular the “Dual CommonJS/ES module packages” section which provides a more complete and up-to-date picture: https://nodejs.org/dist/latest-v14.x/docs/api/packages.html#packages_dual_commonjs_es_module_packages

There is also an ongoing discussion in facebook/react#11503.

gaearon · 2021-08-18T19:07:57Z

Our latest thinking was that we'd drop default exports altogether. Named only.

jonkoops · 2024-08-20T12:03:59Z

Our latest thinking was that we'd drop default exports altogether. Named only.

Perhaps this should be deprecated starting React 19?

Introduce RFC for support of the Node.js native ES2015 modules implem…

81cb48d

…entation

facebook-github-bot added the CLA Signed label Mar 31, 2018

Fix duplication in the index.mjs example

90dc27f

Jessidhia reviewed Jun 15, 2018

View reviewed changes

gaearon reviewed Jun 15, 2018

View reviewed changes

TrySound mentioned this pull request Aug 3, 2018

Provide esm entry point for react-is facebook/react#13321

Closed

gaearon mentioned this pull request Jul 24, 2020

Formalize top-level ES exports facebook/react#11503

Open

Andarist reviewed Jul 24, 2020

View reviewed changes

gaearon mentioned this pull request Aug 17, 2020

createPortal: support option to stop propagation of events in React tree facebook/react#11387

Open


		Alternatively we could decide that we are not going to support named imports of React from ESM.

		This will not be a breaking change. Use of .mjs and ESM is opt-in functionality. All packages using babel or a bundler to access node will keep working with the non-spec compliant handling of named exports from CommonJS modules.


		This will not be a breaking change. Use of .mjs and ESM is opt-in functionality. All packages using babel or a bundler to access node will keep working with the non-spec compliant handling of named exports from CommonJS modules.

		The only requirement will be that if someone decides to switch to `.mjs` and opt-in to using ESM instead of transpiling/bundling, they will be required to refactor their entire codebase to use `React.Component` instead of named exports.


		Here are the requirements that the ESM implementation in Node.js place on us and it's behaviours we can take advantage of:

		- ESM code must be inside of a `.mjs` file

Support named exports in Node.js native ES2015 modules implementation #38

Are you sure you want to change the base?

Support named exports in Node.js native ES2015 modules implementation #38

Conversation

dantman commented Mar 31, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Jessidhia Jun 15, 2018 • edited Loading

Choose a reason for hiding this comment

gaearon Jun 15, 2018 • edited Loading

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

gaearon Jun 15, 2018 • edited Loading

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

Jessidhia Jun 16, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chyzwar commented Jul 22, 2018

gaearon commented Oct 19, 2018

TrySound commented Oct 19, 2018

sebmarkbage commented Mar 2, 2019

dantman commented Mar 2, 2019

TrySound commented Mar 2, 2019

Jessidhia commented Mar 2, 2019

dantman commented Mar 2, 2019

TrySound commented Mar 2, 2019 • edited Loading

dantman commented Mar 2, 2019

TrySound commented Mar 2, 2019 • edited Loading

gaearon commented Feb 10, 2020

dantman commented Feb 11, 2020

jaydenseric commented Feb 11, 2020

gaearon commented Feb 11, 2020

Andarist Jul 24, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stefee commented Jul 25, 2020 • edited Loading

gaearon commented Aug 18, 2021

jonkoops commented Aug 20, 2024

Jessidhia Jun 15, 2018 •

edited

Loading

gaearon Jun 15, 2018 •

edited

Loading

gaearon Jun 15, 2018 •

edited

Loading

Jessidhia Jun 16, 2018 •

edited

Loading

TrySound commented Mar 2, 2019 •

edited

Loading

TrySound commented Mar 2, 2019 •

edited

Loading

Andarist Jul 24, 2020 •

edited

Loading

stefee commented Jul 25, 2020 •

edited

Loading