doc: update packages documentation for Node.js 12 EOL #43375
Conversation
|
Review requested:
|
Co-authored-by: Antoine du Hamel <[email protected]> Co-authored-by: Mohammed Keyvanzadeh <[email protected]>
|
It looks like |
| ".": "./main.js", | ||
| "./submodule": "./src/submodule.js" | ||
| ".": "./index.js", | ||
| "./submodule.js": "./src/submodule.js" |
There was a problem hiding this comment.
| "./submodule.js": "./src/submodule.js" | |
| "./submodule": "./src/submodule.js" |
There was a problem hiding this comment.
i still think these examples shouldn't be changed to add the extension.
There was a problem hiding this comment.
I don’t really understand what’s motivating this change either, if anything that adds more bloat to the import maps – I mean it adds 3 bytes; jokes aside, it could give the reader the impression that using an extension is required when defining an export path, and/or confuse needlessly the package consumers on why the is no submodule.js file at the trot of the package – whereas extensionless makes a good job signaling we’re not dealing with actual paths imo.
(Same thing for the change main.js -> index.js, I don’t think it’s necessary)
That being said, I don’t feel strongly about this, so feel free to disregard.
| } | ||
| } | ||
| ``` | ||
|
|
||
| Now only the defined subpath in [`"exports"`][] can be imported by a consumer: | ||
|
|
||
| ```js | ||
| import submodule from 'es-module-package/submodule'; | ||
| import submodule from 'es-module-package/submodule.js'; |
There was a problem hiding this comment.
| import submodule from 'es-module-package/submodule.js'; | |
| import submodule from 'es-module-package/submodule'; |
Co-authored-by: Jordan Harband <[email protected]>
|
The docs should only reflect node's present, not node's (quite uncertain) future wrt import maps. When node supports import maps, and the feature is sadly unable to support the most common node ecosystem pattern, then that would be the appropriate time to have opinionated docs - not now, when it's still just wishful thinking from a few collaborators. |
| ".": "./main.js", | ||
| "./submodule": "./src/submodule.js" | ||
| ".": "./index.js", | ||
| "./submodule.js": "./src/submodule.js" |
There was a problem hiding this comment.
i still think these examples shouldn't be changed to add the extension.
|
Added some final clarifications to the extensions guidance and hoping to land this soon. |
| ".": "./main.js", | ||
| "./submodule": "./src/submodule.js" | ||
| ".": "./index.js", | ||
| "./submodule.js": "./src/submodule.js" |
There was a problem hiding this comment.
I don’t really understand what’s motivating this change either, if anything that adds more bloat to the import maps – I mean it adds 3 bytes; jokes aside, it could give the reader the impression that using an extension is required when defining an export path, and/or confuse needlessly the package consumers on why the is no submodule.js file at the trot of the package – whereas extensionless makes a good job signaling we’re not dealing with actual paths imo.
(Same thing for the change main.js -> index.js, I don’t think it’s necessary)
That being said, I don’t feel strongly about this, so feel free to disregard.
PR-URL: #43375 Reviewed-By: Geoffrey Booth <[email protected]> Reviewed-By: Antoine du Hamel <[email protected]>
|
Landed in 74716ad. |
PR-URL: #43375 Reviewed-By: Geoffrey Booth <[email protected]> Reviewed-By: Antoine du Hamel <[email protected]>
|
This needs a backport PR to land on v16.x-staging. There is a conflict because of the "Subpath folder mappings" section and I'm not sure where to put it. |
|
Thanks, I've posted a backport in #43809. |
PR-URL: #43375 Backport-PR-URL: #43809 Reviewed-By: Geoffrey Booth <[email protected]> Reviewed-By: Antoine du Hamel <[email protected]>
PR-URL: #43375 Backport-PR-URL: #43809 Reviewed-By: Geoffrey Booth <[email protected]> Reviewed-By: Antoine du Hamel <[email protected]>
PR-URL: nodejs/node#43375 Backport-PR-URL: nodejs/node#43809 Reviewed-By: Geoffrey Booth <[email protected]> Reviewed-By: Antoine du Hamel <[email protected]>
This updates the packages documentation to update some of the modules
"exports"guidance with the Node.js 12 EOL, specifically:"main"is no longer required as a fallback when using"exports", instead we explain how to decide which to use based on version support. I have gone quite strongly here in recommending the"exports"pattern - this guidance could certainly be relaxed to be more generous to keeping"main"around as well."exports"examples, I've shifted to the pattern of including the file extension in the subpath, as has kind of come to be seen as the better approach to ensure interop with import maps. I've mentioned some brief notes around this and updated all the examples, including the patterns examples to use pattern trailers./cc @nodejs/modules