Missing documentation for exports alternative paths
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 65/100
- Issue type
- Documentation
- Clarity
- Mostly clear
- Activity status
- Quiet
- Tech stack
- javascript, nodejs
- Domain
- documentation
Research direction
Start with the exports section of the packages documentation at nodejs.org/api/packages.html and review the linked Webpack and TypeScript references for the alternative-path behavior. Add a description and practical examples for array-valued export paths, with the documentation clearly explaining when the examples apply.
Written by the indexing model from the issue text.
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: https://github.com/nodejs/node/issues/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.
- Dominant language
- JavaScript
- Stars
- 122k
- Forks
- 37.4k
- Avg merge
- 4d 3h
- Merged PRs (30d)
- 273
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from nodejs/node
-
doc
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
-
build
Difficulty 1/5 Under an hour Newbie friendliness 88/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
-
Difficulty 1/5 Under an hour Newbie friendliness 90/100
-
feature request
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
HarperFast/skills#96 ·
-
[Block] Latest Posts [Type] Bug
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Automattic/studio#4908 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 86/100
sugarlabs/musicblocks#8847 ·