[v12 backport] ESM (named exports for CJS, package.json docs, subpath export patterns, warning removal) #35757

aduh95 · 2020-10-22T15:32:48Z

This PR backports a bunch of ESM related PRs:

Named exports for CJS:

`packages.md` and `package.json` fields documentation

subpath export patterns:

doc: edit subpath export patterns introduction #35254

Various documentation improvments:

ESM experimental warning removal:

Other ESM features not yet backported:

~~module: remove dynamicInstantiate loader hook #33501~~ (Not backported, see [v12 backport] ESM (named exports for CJS, package.json docs, subpath export patterns, warning removal) #35757 (comment))
esm: use "node:" internal namespace for builtins #35387

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
documentation is changed or added
commit message follows commit guidelines

nodejs-github-bot · 2020-10-22T15:32:52Z

Review requested:

@nodejs/modules

aduh95 · 2020-10-22T17:22:28Z

@guybedford This PR includes a backport for #34718 and I've also cherry-picked your commit in #35749. Can you have a look to check if I haven't done something odd?

guybedford

Thanks for picking this one up!

I had a brief skim through and couldn't see anything out of place.

I've added this to the list at #35749 as well.

aduh95 · 2020-10-23T13:22:48Z

@guybedford I just realised in #35749 you said that the export pattern support should be backported, but I actually did that in this PR. That's because I cherry-picked all the commits in the packages.md history, so the export pattern one is in there. Maybe I should do that differently?

@nodejs/backporters What should be the process here? Should I split this PR into three (documentation-only commits that landed before the export pattern one, export pattern support, documentation-only after the export pattern commit), or should I keep it all in this PR? I think it makes sense to land all of it in one bulk, but that mixes up semver-minor commits, I wouldn't want to make things difficult for you if that's a problem.

MylesBorins · 2020-10-23T16:25:38Z

@aduh95 a single backport PR to bring the modules implementation in 12.x up to date is preferable imho. Does this include everything that has landed up until now? We might want to bring in more commits, not less :P

PR-URL: nodejs#35249 Reviewed-By: Mary Marchini <oss@mmarchini.me> Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Myles Borins <myles.borins@gmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Zeyu Yang <himself65@outlook.com> Reviewed-By: Richard Lau <riclau@uk.ibm.com>

PR-URL: nodejs#35426 Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Bradley Farias <bradley.meck@gmail.com> Reviewed-By: Myles Borins <myles.borins@gmail.com>

PR-URL: nodejs#35501 Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Masashi Hirano <shisama07@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Myles Borins <myles.borins@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

Using a "Modules:" prefix groups all the related pages together when using alphabetical order. Refs: nodejs/modules#539 PR-URL: nodejs#34663 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Guy Bedford <guybedford@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

This part of the docs aims to contain documentation regarding package configuration that covers both ESM and CJS realms. * Move Enabling section * Update Enabling section * Remove -u flag * Package scopes do not carry through `node_modules` folders Refs: nodejs/modules#539 Co-authored-by: Geoffrey Booth <webmaster@geoffreybooth.com>> Co-authored-by: Guy Bedford <guybedford@gmail.com> PR-URL: nodejs#34748 Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is> Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com> Reviewed-By: Guy Bedford <guybedford@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Ruy Adorno <ruyadorno@github.com>

Fixes: nodejs#33143 PR-URL: nodejs#34970 Reviewed-By: Guy Bedford <guybedford@gmail.com> Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>

PR-URL: nodejs#34718 Reviewed-By: Jan Krems <jan.krems@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com>

* Use parallel construction in the two sentences * Backticks around _package.json_ to match rest of file * Add comma for readability * Own the recommendation ("we recommend") PR-URL: nodejs#35254 Reviewed-By: Jan Krems <jan.krems@gmail.com> Reviewed-By: Michael Dawson <midawson@redhat.com> Reviewed-By: Guy Bedford <guybedford@gmail.com>

PR-URL: nodejs#35311 Reviewed-By: Jan Krems <jan.krems@gmail.com>

PR-URL: nodejs#35370 Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is> Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

Some minor adjustments, mostly moving things to present tense and avoiding the ambiguity of _may_. Refs: nodejs#35370 (comment) PR-URL: nodejs#35427 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com> Reviewed-By: Guy Bedford <guybedford@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Michael Dawson <midawson@redhat.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: James M Snell <jasnell@gmail.com>

PR-URL: nodejs#35428 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Myles Borins <myles.borins@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>

PR-URL: nodejs#35410 Refs: nodejs#34718 Reviewed-By: Rich Trott <rtrott@gmail.com>

Documents which versions of Node.js support which ESM-feature. PR-URL: nodejs#35395 Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com> Reviewed-By: Guy Bedford <guybedford@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>

PR-URL: nodejs#31974 Reviewed-By: Myles Borins <myles.borins@gmail.com> Reviewed-By: Jan Krems <jan.krems@gmail.com> Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com> Reviewed-By: Michaël Zasso <targos@protonmail.com>

Backport-PR-URL: #35757 PR-URL: #35311 Reviewed-By: Jan Krems <jan.krems@gmail.com>

Backport-PR-URL: #35757 PR-URL: #35370 Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is> Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

Some minor adjustments, mostly moving things to present tense and avoiding the ambiguity of _may_. Refs: #35370 (comment) Backport-PR-URL: #35757 PR-URL: #35427 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com> Reviewed-By: Guy Bedford <guybedford@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Michael Dawson <midawson@redhat.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: James M Snell <jasnell@gmail.com>

Backport-PR-URL: #35757 PR-URL: #35428 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Myles Borins <myles.borins@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>

Backport-PR-URL: #35757 PR-URL: #35410 Refs: #34718 Reviewed-By: Rich Trott <rtrott@gmail.com>

Documents which versions of Node.js support which ESM-feature. Backport-PR-URL: #35757 PR-URL: #35395 Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com> Reviewed-By: Guy Bedford <guybedford@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>

Backport-PR-URL: #35757 PR-URL: #31974 Reviewed-By: Myles Borins <myles.borins@gmail.com> Reviewed-By: Jan Krems <jan.krems@gmail.com> Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com> Reviewed-By: Michaël Zasso <targos@protonmail.com>

Backport-PR-URL: #35757 PR-URL: #35750 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Guy Bedford <guybedford@gmail.com>

Backport-PR-URL: #35757 PR-URL: #35387 Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Bradley Farias <bradley.meck@gmail.com> Reviewed-By: Jan Krems <jan.krems@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com>

MylesBorins · 2020-11-03T16:34:57Z

landed in 7da9da5...9099190

Backport-PR-URL: #35757 PR-URL: #35249 Reviewed-By: Mary Marchini <oss@mmarchini.me> Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Myles Borins <myles.borins@gmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Zeyu Yang <himself65@outlook.com> Reviewed-By: Richard Lau <riclau@uk.ibm.com>

Backport-PR-URL: #35757 PR-URL: #35426 Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Bradley Farias <bradley.meck@gmail.com> Reviewed-By: Myles Borins <myles.borins@gmail.com>

Backport-PR-URL: #35757 PR-URL: #35501 Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Masashi Hirano <shisama07@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Myles Borins <myles.borins@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

Using a "Modules:" prefix groups all the related pages together when using alphabetical order. Refs: nodejs/modules#539 Backport-PR-URL: #35757 PR-URL: #34663 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Guy Bedford <guybedford@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

This part of the docs aims to contain documentation regarding package configuration that covers both ESM and CJS realms. * Move Enabling section * Update Enabling section * Remove -u flag * Package scopes do not carry through `node_modules` folders Refs: nodejs/modules#539 Co-authored-by: Geoffrey Booth <webmaster@geoffreybooth.com>> Co-authored-by: Guy Bedford <guybedford@gmail.com> Backport-PR-URL: #35757 PR-URL: #34748 Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is> Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com> Reviewed-By: Guy Bedford <guybedford@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Ruy Adorno <ruyadorno@github.com>

Fixes: #33143 Backport-PR-URL: #35757 PR-URL: #34970 Reviewed-By: Guy Bedford <guybedford@gmail.com> Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>

Backport-PR-URL: #35757 PR-URL: #34718 Reviewed-By: Jan Krems <jan.krems@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com>

* Use parallel construction in the two sentences * Backticks around _package.json_ to match rest of file * Add comma for readability * Own the recommendation ("we recommend") Backport-PR-URL: #35757 PR-URL: #35254 Reviewed-By: Jan Krems <jan.krems@gmail.com> Reviewed-By: Michael Dawson <midawson@redhat.com> Reviewed-By: Guy Bedford <guybedford@gmail.com>