doc: update packages documentation for Node.js 12 EOL by guybedford · Pull Request #43375 · nodejs/node · GitHub

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.
In all "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.
I've updated the version history on subpath patterns to include the history for imports pattern support and pattern trailers support.
I've moved the exports sugar section higher up, this should help make the linear flow a little easier to understand since we jump between forms.
Added a new section on extensionless versus extensioned subpaths

/cc @nodejs/modules

Review requested:

@nodejs/modules

Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com> Co-authored-by: Mohammed Keyvanzadeh <mohammadkeyvanzade94@gmail.com>

It looks like make test-doc is failing.

Suggested change

      
                "./submodule.js": "./src/submodule.js"
          
                "./submodule": "./src/submodule.js"

i still think these examples shouldn't be changed to add the extension.

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.

Suggested change

      
            import submodule from 'es-module-package/submodule.js';
          
            import submodule from 'es-module-package/submodule';

Co-authored-by: Jordan Harband <ljharb@gmail.com>

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.

Thanks for the iteration here; I think this does a great job minimizing editorializing in the node docs. LGTM.

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.

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 <webadmin@geoffreybooth.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

Landed in 74716ad.

PR-URL: #43375 Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

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 <webadmin@geoffreybooth.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

PR-URL: nodejs/node#43375 Backport-PR-URL: nodejs/node#43809 Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

doc: update packages documentation for Node.js 12 EOL

4759735

nodejs-github-bot added the doc Issues and PRs related to the documentations. label Jun 11, 2022

lint fixes

4fad6db

ljharb reviewed Jun 11, 2022

View reviewed changes

Comment thread doc/api/packages.md Outdated

VoltrexKeyva reviewed Jun 11, 2022

View reviewed changes

Comment thread doc/api/packages.md Outdated

aduh95 reviewed Jun 11, 2022

View reviewed changes

Comment thread doc/api/packages.md Outdated

aduh95 reviewed Jun 11, 2022

View reviewed changes

Comment thread doc/api/packages.md Outdated

Apply suggestions from code review

924c758

Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com> Co-authored-by: Mohammed Keyvanzadeh <mohammadkeyvanzade94@gmail.com>

GeoffreyBooth approved these changes Jun 12, 2022

View reviewed changes

Comment thread doc/api/packages.md Outdated

guybedford added 2 commits June 12, 2022 14:01

main -> index, rewordings

894a104

also update conditional example

5cb9eda

GeoffreyBooth approved these changes Jun 13, 2022

View reviewed changes

Comment thread doc/api/packages.md Outdated

Comment thread doc/api/packages.md Outdated

latest suggestions

47c501a

GeoffreyBooth approved these changes Jun 13, 2022

View reviewed changes

aduh95 reviewed Jun 13, 2022

View reviewed changes

Comment thread doc/api/packages.md

aduh95 reviewed Jun 13, 2022

View reviewed changes

Comment thread doc/api/packages.md Outdated

guybedford added 3 commits June 14, 2022 09:22

remove extension in module export case

2c9d7c3

update patterns history

b65c5e5

update imports trailers support

e102fce

aduh95 approved these changes Jun 14, 2022

View reviewed changes

guybedford added 3 commits June 14, 2022 11:08

reorder changes

f4184d6

use patterns extensions variant in interop example

9db527f

note major upgrade path

4cbd77f

guybedford commented Jun 14, 2022

View reviewed changes

Comment thread doc/api/packages.md

ljharb reviewed Jun 14, 2022

View reviewed changes

guybedford and others added 3 commits June 14, 2022 12:03

fixup unextensioned feature export

d339608

Apply suggestions from code review

c83484f

Co-authored-by: Jordan Harband <ljharb@gmail.com>

dedicated section on import maps compat

2dec621

ljharb reviewed Jun 15, 2022

View reviewed changes

GeoffreyBooth reviewed Jun 15, 2022

View reviewed changes

Comment thread doc/api/packages.md Outdated

Comment thread doc/api/packages.md Outdated

further clarifications

14a9f4e

GeoffreyBooth approved these changes Jun 15, 2022

View reviewed changes

guybedford added 2 commits June 14, 2022 22:45

final recommendataion cleanup

eebd97d

correct patterns change

b0a0df3

aduh95 reviewed Jun 15, 2022

View reviewed changes

Comment thread doc/api/packages.md Outdated

aduh95 approved these changes Jun 15, 2022

View reviewed changes

guybedford added 2 commits June 15, 2022 12:02

extensioned v extensionless -> extensions in subpaths

03e84ea

casing

757bb60

guybedford added a commit that referenced this pull request Jun 15, 2022

doc: packages documentation updates for 12 EOL

74716ad

PR-URL: #43375 Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

guybedford closed this Jun 15, 2022

guybedford deleted the esm-docs-12-deprecate branch June 15, 2022 20:44

danielleadams pushed a commit that referenced this pull request Jun 16, 2022

doc: packages documentation updates for 12 EOL

f91babe

PR-URL: #43375 Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

danielleadams mentioned this pull request Jun 16, 2022

v18.4.0 proposal #43385

Merged

targos added the backport-requested-v16.x label Jul 12, 2022

guybedford mentioned this pull request Jul 12, 2022

[v16.x backport] doc: packages documentation updates for 12 EOL (43375) #43809

Closed

richardlau added backport-open-v16.x and removed backport-requested-v16.x labels Jul 12, 2022

targos added backported-to-v16.x and removed backport-open-v16.x labels Jul 18, 2022

targos pushed a commit that referenced this pull request Jul 18, 2022

doc: packages documentation updates for 12 EOL

f3d3a7b

PR-URL: #43375 Backport-PR-URL: #43809 Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

targos pushed a commit that referenced this pull request Jul 31, 2022

doc: packages documentation updates for 12 EOL

3f1ec10

PR-URL: #43375 Backport-PR-URL: #43809 Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

targos mentioned this pull request Aug 3, 2022

v16.17.0 release proposal #44098

Merged

	"./submodule.js": "./src/submodule.js"
	"./submodule": "./src/submodule.js"

	import submodule from 'es-module-package/submodule.js';
	import submodule from 'es-module-package/submodule';

doc: update packages documentation for Node.js 12 EOL by guybedford · Pull Request #43375 · nodejs/node · GitHub

Uh oh!

Uh oh!

doc: update packages documentation for Node.js 12 EOL - #43375

doc: update packages documentation for Node.js 12 EOL#43375guybedford wants to merge 31 commits intonodejs:mainnodejs/node:mainfrom guybedford:esm-docs-12-deprecateguybedford/node:esm-docs-12-deprecateCopy head branch name to clipboard

Conversation

guybedford commented Jun 11, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nodejs-github-bot commented Jun 11, 2022

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aduh95 commented Jun 14, 2022

Uh oh!

Uh oh!

Uh oh!

ljharb Jun 14, 2022

Choose a reason for hiding this comment

Uh oh!

ljharb Jun 15, 2022

Choose a reason for hiding this comment

Uh oh!

aduh95 Jun 15, 2022

Choose a reason for hiding this comment

Uh oh!

ljharb Jun 14, 2022

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ljharb commented Jun 15, 2022

Uh oh!

ljharb left a comment

Choose a reason for hiding this comment

Uh oh!

ljharb Jun 15, 2022

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

guybedford commented Jun 15, 2022

Uh oh!

Uh oh!

aduh95 Jun 15, 2022

Choose a reason for hiding this comment

Uh oh!

Uh oh!

guybedford commented Jun 15, 2022

Uh oh!

targos commented Jul 12, 2022

Uh oh!

guybedford commented Jul 12, 2022

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

doc: update packages documentation for Node.js 12 EOL#43375
guybedford wants to merge 31 commits into
nodejs:mainfrom
guybedford:esm-docs-12-deprecate

guybedford commented Jun 11, 2022 •
edited
Loading