Repository navigation
Recommend node/default conditions instead of require/import as a solution to the dual package hazard #52174
Description
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 |
|---|---|---|
{
"name": "foo",
"exports": {
"require": "./foo.cjs",
"import": "./foo.mjs"
}
} |
exports.object = {}; |
export const object = {}; |
package.json |
bar.js |
|---|---|
{
"name": "bar",
"main": "./bar.js"
} |
const foo = require("foo");
exports.object = foo.object; |
// my app
import { object as fooObj } from "foo";
import { object as barObj } from "bar";
console.log(fooObj === barObj); // false?????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:
{
"name": "foo",
"exports": {
"node": "./foo.cjs",
"default": "./foo.mjs"
}
}Then:
- there would be no dual-package hazard in Node.js, because it only ever loads the CommonJS version
- there would be no dual-package hazard in bundlers, because they would only ever load either the
nodeversion (if they are configured to target Node.js) or thedefaultversion (if they are configured to target other platforms). - the package solves the dual-package hazard while still providing an ESM-only version
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).
Activity
joyeecheung commentedon Apr 11, 2024
Looks like a good first issue. Relevant file is https://github.com/nodejs/node/blob/main/doc/api/packages.md
eliphazbouye commentedon Apr 26, 2024
@joyeecheung , @nicolo-ribaudo this issue is still relevant ?
joyeecheung commentedon Apr 26, 2024
Yes, IMO the doc can still be improved as suggested in the OP.
mewssix commentedon May 19, 2024
Is there still work to be done here?
joyeecheung commentedon Sep 1, 2024
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.
B4nan commentedon Sep 4, 2024
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?
tats-u commentedon Feb 12, 2025
"module-sync"must exist above"node"(or"require") if applicable.{ "name": "foo", "exports": { "module-sync": "./foo.mjs", "node": "./foo.cjs", "default": "./foo.mjs" } }ajeeth-asperand commentedon Nov 27, 2025
Hi, I’d like to work on this issue as my first documentation contribution. Is it still available?
zhanglinqian commentedon Feb 12, 2026
I'd like to work on this issue.
Bikram-pal commentedon Mar 16, 2026
Hi, I’m a new contributor and would like to help with documentation improvements.
Is there still any work needed for this issue, or should new contributions target a different repository?
roshanraj9136 commentedon Apr 4, 2026
can i go for it?
doc: recommend node/default conditions for dual packages
MikeMcC399 commentedon Apr 7, 2026
@joyeecheung
Should this issue still be open, given your comments in #52174 (comment) and creation of the https://github.com/nodejs/package-examples repo?
It's also labeled with good first issueIssues that are suitable for first-time contributors.
.Edit: label removed Jul 21, 2026
New contributors are still attempting to resolve it.
doc: add guidance on using node/default conditions for dual packages
github-actions commentedon Jul 20, 2026
This issue has been marked as stale due to 90 days of inactivity.
It will be automatically closed in 30 days if no further activity occurs. If this is still relevant, please leave a comment or update it to keep it open.
tats-u commentedon Jul 20, 2026
Not stale