You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Currently we only ship CommonJS versions of all packages. However we might want to ship them as ESM in the future (#10021).
We can't quite easily do this because we haven't really decided on what top-level ES exports would look like from each package. For example, does react have a bunch of named exports, but also a default export called React? Should we encourage people to import * for better tree shaking? What about react-test-renderer/shallow that currently exports a class (and thus would start failing in Node were it converted to be a default export)?
Reacted by Kim Joar Bekkelund, Lukas Taegert-Atkinson, Johnson, Nicolás Parada, Teppei Sato, Kevin Killingsworth, Matej Simek, Vlad Shcherbin, Aman Mahajan, 解夏 and 240 more
Reacted by Marais Rossouw, MichielCornilleESC, Andrei L, johannesklevll, zhangenming, Aziz Khambati, 流浪大法师, Tomas Bruckner, Sumit Datta, Sharmila Jesupaul and 33 more
Reacted by mashaal and Roman
Reacted by mashaal, Adric Saxon, silverwind, Thimo, Bart Louwers, David Adamson, Nadeesh Peiris, Odd Martin Hansen, Owen Buckley, Brian Kim and 3 more
Reacted by Lukas Taegert-Atkinson, Billy Janitsch, Haroen Viaene, Ian Storm Taylor, Alex Bennett, 流浪大法师, Sean Blonien, Brandon Bennett, Dave Houlbrooke, mkabk9231 and 1 more
but it shouldnt be used to reexport other stuff like in this example:
Is there a technical reason why? (Aside from having two ways to do the same thing.)
My impression is that people who would import * (and not use the default) wouldn't have problems tree shaking since default would stay unused. But maybe I overestimate Rollup etc.
That questions can be probably best answered by @lukastaegert. Ain't sure if something has changed since #10021 (comment)
Also Rollup is not the only tree shaker out there, and while webpack's tree-shaking algorithm is worse than the one in rollup, it's usage is probably way higher than rollup's (both tools do excellent jobs ofc, I don't want to offend anyone, just stating facts) and if we can (as the community) help both tools at once we should do so whenever we can.
is tree-shaking going to do anything in React's case, given that everything is preprocessed into a single flat bundle? I wonder what the primary import style is for React, personally i tend to treat it like a default export e.g. React.Component, React.Children but occasionally do the named thing with cloneElement
Reacted by Michael Turkeev, 流浪大法师, Sean Blonien and Brandon Bennett
As @gaearon already stated elsewhere, size improvements in case of react are expected to be minimal. Nevertheless, there ARE advantages:
React.Children might probably be removed in some cases (so I heard 😉)
React itself can be hoisted into the top scope by module bundlers that support this. This could again remove quite a few bytes and might also grant an oh-so-slight performance improvement. The main improvement would lie in the fact that there does not need to be another variable that references React.Component for every module but just one that is shared everywhere (this is how rollup usually does it). Also, though this is just me guessing, this might reduce the chance of webpack's ModuleConcatenationPlugin bailing out
Static analysis for react is easier not only for module bundlers but also for e.g. IDEs and other tools. Many such tools already do a reasonable job at this for CJS modules but in the end, there is a lot of guessing involved on their side. With ES6 modules, analysis is a no-brainer.
As for the kind of exports, of course only named export really provide the benefit of easy tree-shaking (unless you use GCC which might be able to do a little more in its aggressive move and maybe the latest rollup if you are really lucky). The question if you provide a default export as well is more difficult to decide:
PRO: Painless migration for existing ES6 code bases (e.g. what @jquense describes)
CON: Since everything is attached to a common object, once this object is included, all its keys are included at once which again defeats any attempts at tree-shaking. Even GCC might have a hard time here.
As a two-version migration strategy, you might add a default export in the next version for compatibility purposes which is declared deprecated (it might even display a warning via a getter etc.) and then remove it in a later version.
Reacted by Cheng Wang, 流浪大法师, Daniel Garcia, Brandon Bennett, Dave Houlbrooke, Jon Koops, Bruno Henriques, Ghislain B. and Odd Martin Hansen
This is also an interesting case: #11526. While monkeypatching for testing is a bit shady, we'll want to be conscious about breaking this (or having a workaround for it).
Came here via this Twitter conversation. For me, there's a clear correct answer to this question: React and ReactDOM should only export named exports. They're not objects that contain state, or that other libraries can mutate or attach properties to (#11526 notwithstanding) — the only reason they exist is as a place to 'put' Component, createElement and so on. In other words, namespaces, which should be imported as such.
(It also makes life easier for bundlers, but that's neither here nor there.)
Of course, that does present a breaking change for people currently using a default import and transpiling. @lukastaegert probably has the right idea here, using accessors to print deprecation warnings. These could be removed in version 17, perhaps?
I don't have a ready-made suggestion for #11526 though. Perhaps shipping ESM would have wait for v17 for that reason anyway, in which case there'd be no need to worry about deprecation warnings.
Reacted by Bogdan Chadkin, Robert Monfera, Eline Henriksen, Haroen Viaene, Sean Larkin, Billy Janitsch, Rouven Weßling, Jesper Kristensen, Anthony Frehner, Dan Prince and 15 more
To clarify, we need React to be in scope (in this case, as a namespace) because JSX transpiles to React.createElement(). We could break JSX and say it depends on global jsx() function instead. Then imports would look like:
import{jsx,Component}from'react';
which is maybe okay but a huge change. This would also mean React UMD builds now need to set window.jsx too.
Why am I suggesting jsx instead of createElement? Well, createElement is already overloaded (document.createElement) and while it's okay with React. qualifier, without it claiming it on the global is just too much. Tbh I’m not super excited about either of these options, and think this would probably be the best middle ground:
Confession: I always found it slightly odd that you have to explicitly import React in order to use JSX, even though you're not actually using that identifier anywhere. Perhaps in future, transpilers could insert import * as React from 'react' (configurable for the sake of Preact etc) on encountering JSX, if it doesn't already exist? That way you'd only need to do this...
import{Component}from'react';
...and the namespace import would be taken care of automatically.
Reacted by Robert Monfera, Dustin Schau, Cecile Muller, t. m. k., Cameron Bytheway, Billy Janitsch, Zach Wegrzyniak, Sebastien Baudray, Seth Bertalotto, Alexander Myshov and 31 more
In a distant future, maybe. For now we need to make sure transpilers work with other module systems (CommonJS or globals). Making this configurable is also a hurdle, and further splits the community.
What @Rich-Harris suggested (inserting a specific import when jsx is used) is easily done by transpilers plugin. The community would have to upgrade their babel-plugin-transform-react-jsx and that's it. And of course even existing setups would still work if only one adds import * as React from 'react'; to the file.
Of course we need to consider other module systems, but it doesn't seem like a hard problem to solve. Are there any specific gotchas in mind?
I second the suggestion to use https://esm.sh/react@18 as they have provided a proper modern ESM distribution of React for a very long time. Just remember to use the import-map in your html for the "react". It tells what version of react the bare import should resolve to (just as in package.json).
No need for bundlers or arcane legacy module stuff. Bundling is for optimisation and for legacy browser support and should provide compatibility with ESM and not fight against it.
IMHO, a bundler should no longer be a development time dependency in 2023.
Just do:
import React from "react"
Reacted by Samuel Batista and Rafael Arquero Gimeno
Reacted by Jordan Harband, Stef, Vadym Holoveichuk, Bogdan Chadkin, Andy Barron, James and Vladislav
So our current thinking is that when we go ESM, we might want to try go ESM all the way. No CJS at all — or separated in a compat legacy package. This won't happen in React 17 and is unlikely in 18, but is plausible to try in React 19.
@gaearon Now that the new JSX transform has been out for a while, there should no longer be a blocker right? Perhaps the time is right to do this with React 19. How would you feel if I drafted up a renewed proposal along the lines of reactjs/rfcs#38?
Reacted by silverwind, David Alsh, Alessandro Cuppari, whoisYeshua, Andy Barron, Jeff McMahan, ruucm-working, Clément, Gustavo, Dmitriy Petrov and 3 more
Reacted by no, Gabriel Delépine and Edward Dewhurst
Bundling is for optimisation [..] IMHO, a bundler should no longer be a development time dependency in 2023.
While it's not as much of a problem in smaller applications, larger application with hundreds/thousands of sources files will always have a need for a build step as shipping sources directly cannot be as efficient as a tool designed to organize sources into an optimized output.
"Bundlers" are reasonable as they can take advantage of compression, dead code elimination, and consuming invalid browser sources (like JSX syntax, TypeScript, importing css into JS, importing images, markdown, plaintext, json, etc).
You could argue that you could just use a minifier and strip types on your sources before publishing.... but then you're basically making a bundler.
For the most part in 2024, it's practical to think of JavaScript as simply a pseudo "binary" format for the web that compilers target.
should provide compatibility with ESM and not fight against it.
I'm advocating for React being distributed in spec-compliant ESM that can be run directly in the browser - with or without a bundler.
As a bundler developer, I wish wholeheartedly that all web applications/libraries would be written in spec-compliant ESM but it's just not like that in the real world.
Even packages distributed today as ESM packages often still use Nodejs's CJS resolution algorithm, omit extensions from imports, etc. So not even ESM packages are really valid ESM - it's a nightmare.
React, CJS and Optimising Outputs
React being distributed as CJS forces bundlers to de-optimize everything relating to React. It cannot be tree-shaken and forces bundlers to ship CJS emulation/polyfills to the browser when React is present.
One example of a deoptimization is; because CJS exports can be modified at runtime, bundlers cannot assume stable exports for CJS values.
For example, look at this abomination:
const foo = require('./something')
setTimeout(() => {
foo.bar = 'I reassigned a value in another module at runtime'
}, 2000)
Why is this legal?!?! 😆
So bundler CJS emulation involves checking the value of every module.exports property every single time it is accessed. This makes every single property access 10x slower with CJS than ESM (which can be heavily optimised).
In the case of React, how many times do you call createElement? Every call must recompute the exported value at runtime which is absurdly wasteful.
For the love of all things good, please distribute React as unminified, browser compliant, ESM
Reacted by Vadym Holoveichuk, Jaeho Lee (Jay), Audun Meek Olsen, Oleksii, Philippe Rivière, Alessandro Cuppari, Jithya, Matija Marohnić, Steve Dalonzo, Jonas Kello and 57 more
Reacted by Conor O'Flanagan, Ben McGinnis, Dan, Seb Barre, Thimo, Bart Louwers and Odd Martin Hansen
Reacted by Bruno Henriques, Pedro Ladaria, Ben McGinnis, Jeff McMahan, Seb Barre, Dave Houlbrooke, Marcos Pereira, Rafael Arquero Gimeno, Thimo, Bart Louwers and 3 more
My guess would be that making the new JSX transform mandatory was a first step towards this, so perhaps it will be React v20 that will enforce ESM? Still, kind of sad to not see at least a formal plan or acknowledgement since this is in the top 10 most upvoted issues.
Reacted by Gustavo, Dave Houlbrooke, mtornwall and Leonardo Diehl
My impression is that people who would import * (and not use the default) wouldn't have problems tree shaking since default would stay unused. But maybe I overestimate Rollup etc.
there is actually preety good reason to allow users to import esm directly, mixing esm and cjs is costly, and most bundlers do convert this at runtime, eg.
The automatic JSX transform (now mandatory in React 19) removed the main dependency on import React from 'react'
But this was never formally documented as a decision on this issue, and it's blocking downstream tooling from acting. For example, eslint-plugin-react has had a fully reviewed, maintainer-approved PR for a named-import rule sitting in limbo since 2021, partly because there's no official public statement to point to.
Would it be possible to get a definitive comment here confirming that React's future ESM entry points will use named exports only, with no default export? That alone, even without a timeline for actually shipping ESM, would let the ecosystem start preparing: lint rules, codemods, documentation, and gradual migration.
If it would help move things forward, I'd be happy to contribute a formal RFC building on RFC #38 that reflects the current state of the ecosystem (React 19's mandatory JSX transform, Node's mature ESM support, the package.jsonexports field) and lays out a concrete migration path.
Reacted by Ovidiu Cherecheș, Kyℓe Hensel, Owen Buckley, Zhao, Jesper Kristensen, MaxwellCohen, Sagnik Pradhan, Linus Unnebäck, Bruno Henriques, Bart Louwers and 4 more
Reacted by Karl Horky, Linus Unnebäck, Dave Houlbrooke and Bart Louwers
Activity
Andarist commentedon Nov 9, 2017
Imho
import *is a way to go, Im not opposed to having a default export too, but it shouldnt be used to reexport other stuff like in this example:gaearon commentedon Nov 9, 2017
Is there a technical reason why? (Aside from having two ways to do the same thing.)
My impression is that people who would import
*(and not use the default) wouldn't have problems tree shaking since default would stay unused. But maybe I overestimate Rollup etc.Andarist commentedon Nov 9, 2017
That questions can be probably best answered by @lukastaegert. Ain't sure if something has changed since #10021 (comment)
Also Rollup is not the only tree shaker out there, and while webpack's tree-shaking algorithm is worse than the one in rollup, it's usage is probably way higher than rollup's (both tools do excellent jobs ofc, I don't want to offend anyone, just stating facts) and if we can (as the community) help both tools at once we should do so whenever we can.
jquense commentedon Nov 9, 2017
is tree-shaking going to do anything in React's case, given that everything is preprocessed into a single flat bundle? I wonder what the primary import style is for React, personally i tend to treat it like a default export e.g.
React.Component,React.Childrenbut occasionally do the named thing withcloneElementlukastaegert commentedon Nov 10, 2017
As @gaearon already stated elsewhere, size improvements in case of react are expected to be minimal. Nevertheless, there ARE advantages:
React.Componentfor every module but just one that is shared everywhere (this is how rollup usually does it). Also, though this is just me guessing, this might reduce the chance of webpack's ModuleConcatenationPlugin bailing outAs for the kind of exports, of course only named export really provide the benefit of easy tree-shaking (unless you use GCC which might be able to do a little more in its aggressive move and maybe the latest rollup if you are really lucky). The question if you provide a default export as well is more difficult to decide:
As a two-version migration strategy, you might add a default export in the next version for compatibility purposes which is declared deprecated (it might even display a warning via a getter etc.) and then remove it in a later version.
gaearon commentedon Nov 13, 2017
This is also an interesting case: #11526. While monkeypatching for testing is a bit shady, we'll want to be conscious about breaking this (or having a workaround for it).
Rich-Harris commentedon Nov 23, 2017
Came here via this Twitter conversation. For me, there's a clear correct answer to this question: React and ReactDOM should only export named exports. They're not objects that contain state, or that other libraries can mutate or attach properties to (#11526 notwithstanding) — the only reason they exist is as a place to 'put'
Component,createElementand so on. In other words, namespaces, which should be imported as such.(It also makes life easier for bundlers, but that's neither here nor there.)
Of course, that does present a breaking change for people currently using a default import and transpiling. @lukastaegert probably has the right idea here, using accessors to print deprecation warnings. These could be removed in version 17, perhaps?
I don't have a ready-made suggestion for #11526 though. Perhaps shipping ESM would have wait for v17 for that reason anyway, in which case there'd be no need to worry about deprecation warnings.
gaearon commentedon Nov 23, 2017
People have really come to like
so convincing them to give it up might be difficult.
I guess this is not too bad, even if a bit odd:
To clarify, we need
Reactto be in scope (in this case, as a namespace) because JSX transpiles toReact.createElement(). We could break JSX and say it depends on globaljsx()function instead. Then imports would look like:which is maybe okay but a huge change. This would also mean React UMD builds now need to set
window.jsxtoo.Why am I suggesting
jsxinstead ofcreateElement? Well,createElementis already overloaded (document.createElement) and while it's okay withReact.qualifier, without it claiming it on the global is just too much. Tbh I’m not super excited about either of these options, and think this would probably be the best middle ground:and keep JSX transpiling to
React.createElementby default.Rich-Harris commentedon Nov 23, 2017
Confession: I always found it slightly odd that you have to explicitly import
Reactin order to use JSX, even though you're not actually using that identifier anywhere. Perhaps in future, transpilers could insertimport * as React from 'react'(configurable for the sake of Preact etc) on encountering JSX, if it doesn't already exist? That way you'd only need to do this......and the namespace import would be taken care of automatically.
gaearon commentedon Nov 23, 2017
In a distant future, maybe. For now we need to make sure transpilers work with other module systems (CommonJS or globals). Making this configurable is also a hurdle, and further splits the community.
Andarist commentedon Nov 23, 2017
What @Rich-Harris suggested (inserting a specific import when jsx is used) is easily done by transpilers plugin. The community would have to upgrade their
babel-plugin-transform-react-jsxand that's it. And of course even existing setups would still work if only one addsimport * as React from 'react';to the file.Of course we need to consider other module systems, but it doesn't seem like a hard problem to solve. Are there any specific gotchas in mind?
gaearon commentedon Nov 23, 2017
I don’t know, what is your specific suggestion as to how to handle it? Would what the default be for Babel JSX plugin?
jamiewinder commentedon Nov 23, 2017
What people? Come forth so that I may mock thee.
109 remaining items
Starcounter-Jack commentedon Sep 24, 2023
I second the suggestion to use
https://esm.sh/react@18as they have provided a proper modern ESM distribution of React for a very long time. Just remember to use the import-map in your html for the "react". It tells what version of react the bare import should resolve to (just as in package.json).No need for bundlers or arcane legacy module stuff. Bundling is for optimisation and for legacy browser support and should provide compatibility with ESM and not fight against it.
IMHO, a bundler should no longer be a development time dependency in 2023.
Just do:
jonkoops commentedon Nov 15, 2023
@gaearon Now that the new JSX transform has been out for a while, there should no longer be a blocker right? Perhaps the time is right to do this with React 19. How would you feel if I drafted up a renewed proposal along the lines of reactjs/rfcs#38?
luzzif commentedon Dec 7, 2023
Guys please, is there any update on this?
alshdavid commentedon Mar 1, 2024
While it's not as much of a problem in smaller applications, larger application with hundreds/thousands of sources files will always have a need for a build step as shipping sources directly cannot be as efficient as a tool designed to organize sources into an optimized output.
"Bundlers" are reasonable as they can take advantage of compression, dead code elimination, and consuming invalid browser sources (like JSX syntax, TypeScript, importing css into JS, importing images, markdown, plaintext, json, etc).
You could argue that you could just use a minifier and strip types on your sources before publishing.... but then you're basically making a bundler.
For the most part in 2024, it's practical to think of JavaScript as simply a pseudo "binary" format for the web that compilers target.
I'm advocating for React being distributed in spec-compliant ESM that can be run directly in the browser - with or without a bundler.
As a bundler developer, I wish wholeheartedly that all web applications/libraries would be written in spec-compliant ESM but it's just not like that in the real world.
Even packages distributed today as ESM packages often still use Nodejs's CJS resolution algorithm, omit extensions from imports, etc. So not even ESM packages are really valid ESM - it's a nightmare.
React, CJS and Optimising Outputs
React being distributed as CJS forces bundlers to de-optimize everything relating to React. It cannot be tree-shaken and forces bundlers to ship CJS emulation/polyfills to the browser when React is present.
One example of a deoptimization is; because CJS exports can be modified at runtime, bundlers cannot assume stable exports for CJS values.
For example, look at this abomination:
Why is this legal?!?! 😆
So bundler CJS emulation involves checking the value of every
module.exportsproperty every single time it is accessed. This makes every single property access 10x slower with CJS than ESM (which can be heavily optimised).In the case of React, how many times do you call
createElement? Every call must recompute the exported value at runtime which is absurdly wasteful.For the love of all things good, please distribute React as unminified, browser compliant, ESM
hronro commentedon Dec 6, 2024
What a shame that there is still no ESM support in the final React.js v19.0 release, or not even mention it in the release blog post.
jonkoops commentedon Dec 6, 2024
My guess would be that making the new JSX transform mandatory was a first step towards this, so perhaps it will be React v20 that will enforce ESM? Still, kind of sad to not see at least a formal plan or acknowledgement since this is in the top 10 most upvoted issues.
spamshaker commentedon Dec 14, 2024
this is really one liner to build it for production - maybe this way it could be exposed temporarly
bun build --minify --outfile=./dist/react.mjs ./node_modules/react/cjs/react.production.jsand adding "module"="./dist/react.mjs" to a package.json
same goes for other packages
spamshaker commentedon Dec 18, 2024
I'm sorry I can't wait longer. I will switch to the target solution when this issue will be resolved, but now I dealt with it myself => https://github.com/ria-develop/react-esm
till then, I am going to prepare a gitlab action which will rebuild it and sync versions with react releases
aladdin-add commentedon Dec 18, 2024
@spamshaker you don't have to do this - there are several cdns can serve for this, e.g. https://esm.sh/:
alshdavid commentedon Dec 21, 2024
Or just use Preact
alexeyr-ci commentedon Feb 11, 2025
@aladdin-add That's only for Deno or browser, right? Or in @spamshaker's case for Bun. Any simple solution for Node?
Hexagon commentedon Jun 19, 2025
Are we there yet? 👀
codyfrisch commentedon Aug 14, 2025
Aaand this is why we bit the bullet and left the Recrapct ecosystem. Couldn't be happier.
armano2 commentedon Dec 26, 2025
there is actually preety good reason to allow users to import esm directly, mixing esm and cjs is costly, and most bundlers do convert this at runtime, eg.
this is really hard to optimize, and basically not treeshaken at all if you mix cjs + esm
with esm exports, functions eg
createContextcould be optimized away if they are not usedbdw, you can see this clearly in react.dev
its never referenced, and can't be removed https://react.dev/_next/static/chunks/framework-76ad44d61c11f057.js
import *.. is preety trivial to tree-shake compared to cjsjonkoops commentedon May 11, 2026
It seems like the question in this issue's title (what the top-level ES exports should look like) was settled internally years ago:
import React from 'react'; // no"import React from 'react'But this was never formally documented as a decision on this issue, and it's blocking downstream tooling from acting. For example, eslint-plugin-react has had a fully reviewed, maintainer-approved PR for a
named-importrule sitting in limbo since 2021, partly because there's no official public statement to point to.Would it be possible to get a definitive comment here confirming that React's future ESM entry points will use named exports only, with no default export? That alone, even without a timeline for actually shipping ESM, would let the ecosystem start preparing: lint rules, codemods, documentation, and gradual migration.
If it would help move things forward, I'd be happy to contribute a formal RFC building on RFC #38 that reflects the current state of the ecosystem (React 19's mandatory JSX transform, Node's mature ESM support, the
package.jsonexportsfield) and lays out a concrete migration path.