Repository navigation
Missing documentation for exports alternative paths #58600
Description
Affected URL(s)
https://nodejs.org/api/packages.html
Description of the problem
Packages documentation is really helpful to understand motivations and practical usage of exports, from the simplest setup to nested conditions, wildcards, etc. However, it seems to lack a description and examples of "alternative paths" within exports, which I think is really powerful stuff, but currently underrated and not very popular (maybe because of the lack in documentation).
With "alternative paths" what I mean is using arrays as follows:
{
"exports": {
".": {
"development": {
"types": "./src/index.ts",
"import": "./src/index.js",
"require": "./src/index.cjs",
"default": "./src/index.cjs"
},
"import": {
"types": "./types/index.d.ts",
"default": [
"./src/index.js",
"./esm/index.js"
]
},
"require": [
"./src/index.cjs",
"./cjs/index.cjs"
],
"default": [
"./src/index.cjs",
"./cjs/index.cjs"
]
}
}
}The only hint I found in the documentation, is string[] syntax under exports.
Beside that, there are some mentions around:
- Webpack's official docs citing Node.js behaviour: https://webpack.js.org/guides/package-exports/#alternatives.
- Notable TypeScript issue requesting aligning to Node.js behaviour: Conditional exports doesn't respect alternative paths #37928
I think that "alternative paths" is the perfect solution for situations like using your own package without having to build it first during development (e.g., TypeScript, transpiling, polyfilling, etc.)
If there is a spec I would love to update the docs myself.
Activity
ernestostifano commentedon Jun 6, 2025
I am just figuring that the array paths are matched without caring if the specified file exists or not. In that case, what is the practical purpose of the array? I mean, an invalid path is always invalid, right?
EDIT: Found the answer here. However, it's a shame because it would have been very helpful solving today's limitations instead of future compatibility.
Prakhar2275 commentedon Feb 14, 2026
Hi, I’d like to work on documenting the “alternative paths” behavior under exports.
@ernestostifano — would you be able to confirm if the examples shared reflect the intended usage to be documented?
Happy to draft a PR once aligned.
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.