-
Notifications
You must be signed in to change notification settings - Fork 29.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Recommend node
/default
conditions instead of require
/import
as a solution to the dual package hazard
#52174
Comments
Looks like a good first issue. Relevant file is https://github.com/nodejs/node/blob/main/doc/api/packages.md |
@joyeecheung , @nicolo-ribaudo this issue is still relevant ? |
Yes, IMO the doc can still be improved as suggested in the OP. |
Is there still work to be done here? |
In #54648 which adds a new pattern I realize that it just doesn't seem appropriate to document them this way in the API docs. To quote my comments:
I think they should just be placed in their own example repo with some notes on pros/cons and maybe links to threads of discussions. But anyway API docs is the wrong place for them. |
May I ask if there is some schedule for unflagging this? Given the node 22 LTS is nearby, any chance it would happen with that version already? |
Affected URL(s)
https://nodejs.org/api/packages.html#dual-package-hazard
Description of the problem
Publishing packages with dual CommonJS and ESM sources, while has the benefits of supporting both CJS consumers and ESM-only platforms, is known to cause problems because Node.js might load both versions. Example:
package.json
foo.cjs
foo.mjs
package.json
bar.js
The two suggested solutions boil down to "even when you have an ESM entrypoint, still use only CJS internallly". This solves the dual package hazard, but completely defeats the cross-platform benefits of dual modules.
If
foo
instead used these export conditions:Then:
node
version (if they are configured to target Node.js) or thedefault
version (if they are configured to target other platforms).We have been using this
node/default
pattern in@babel/runtime
for a couple years, because we wanted to provide an ESM-only version for browsers while still avoiding the dual-package hazard (@babel/runtime
is mostly stateless, but@babel/runtime/helpers/temporalUndefined
relies on object identity of an object defined in a separate file).The text was updated successfully, but these errors were encountered: