doc: move and rename loaders section #49261

GeoffreyBooth · 2023-08-20T21:47:53Z

This PR moves the former “Loaders” section from esm.md into a new “Customization Hooks” section in module.md.

The content of the section did not change. You don’t need to review the huge red block in esm.md or the huge green block in module.md. I promise, nothing in there changed, other than some ```js to ```mjs because of the linter. The point of this PR is so that I can follow up this one with another PR that makes edits within that block, without those edits being subsumed by the diff from the move.
I updated bookmarks in both files, and edited some mentions outside of the moved section to refer to the new name.

The reason for the move is that as of #47999, these customization hooks now support CommonJS (when the loader author has written the load hook to do so, which many authors haven’t as of yet because it was previously unsupported; and when the ESM loader handles the application entry point, such as when --import is used). We hope to improve CommonJS support further in the future.

The reason for the rename is that as of nodejs/loaders#95, we decided to rename the overall Loaders API to “Module Customization Hooks” to prepare the way for future similar APIs such as “File System Customization Hooks” and “REPL Customization Hooks” and so on. These are many of the items listed under Milestone 3 on our roadmap. This is also why node:module register was named just register and not registerLoader, to establish the pattern for an eventual import { register } from 'node:fs' and import { register } from 'node:repl' and so on.

I plan to rewrite the moved section in a follow-up PR, to continue the renaming and tackle the to-do list of docs updates per nodejs/loaders#154 (comment).

cc @nodejs/loaders @nodejs/modules, and @nodejs/tsc for visibility.

Notable changes

ESM Loaders are now Module Customization Hooks

Since 20.6.0, what were formerly known as ES module loader hooks can now customize CommonJS modules. Therefore, we have renamed them “module customization hooks” and moved their documentation from https://nodejs.org/api/esm.html to https://nodejs.org/api/module.html#customization-hooks.

nodejs-github-bot · 2023-08-20T21:47:57Z

Review requested:

@nodejs/loaders
@nodejs/modules

mcollina

lgtm

github-actions · 2023-08-21T11:38:41Z

The notable-change PRs with changes that should be highlighted in changelogs. label has been added by @RafaelGSS.

Please suggest a text for the release notes if you'd like to include a more detailed summary, then proceed to update the PR description with the text or a link to the notable change suggested text comment.

nodejs-github-bot · 2023-08-22T21:53:42Z

Landed in 164c57d

PR-URL: #49261 Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Jacob Smith <jacob@frende.me> Reviewed-By: Rafael Gonzaga <rafael.nunu@hotmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>

Notable changes: crypto: * update root certificates to NSS 3.93 (Node.js GitHub Bot) #49341 doc: * move and rename loaders section (Geoffrey Booth) #49261 lib: * (SEMVER-MINOR) add api to detect whether source-maps are enabled (翠 / green) #46391 src,permission: * add multiple allow-fs-* flags (Carlos Espa) #49047 test_runner: * (SEMVER-MINOR) expose location of tests (Colin Ihrig) #48975 PR-URL: TODO

Notable changes: crypto: * update root certificates to NSS 3.93 (Node.js GitHub Bot) #49341 doc: * move and rename loaders section (Geoffrey Booth) #49261 lib: * (SEMVER-MINOR) add api to detect whether source-maps are enabled (翠 / green) #46391 src,permission: * add multiple allow-fs-* flags (Carlos Espa) #49047 test_runner: * (SEMVER-MINOR) expose location of tests (Colin Ihrig) #48975 PR-URL: #49592

Notable changes: crypto: * update root certificates to NSS 3.93 (Node.js GitHub Bot) #49341 doc: * move and rename loaders section (Geoffrey Booth) #49261 lib: * (SEMVER-MINOR) add api to detect whether source-maps are enabled (翠 / green) #46391 src: * support multiple `--env-file` declarations (Yagiz Nizipli) #49542 src,permission: * add multiple allow-fs-* flags (Carlos Espa) #49047 test_runner: * (SEMVER-MINOR) expose location of tests (Colin Ihrig) #48975 PR-URL: #49592

Notable changes: crypto: * update root certificates to NSS 3.93 (Node.js GitHub Bot) #49341 doc: * move and rename loaders section (Geoffrey Booth) #49261 * add release key for Ulises Gascon (Ulises Gascón) #49196 lib: * (SEMVER-MINOR) add api to detect whether source-maps are enabled (翠 / green) #46391 src: * support multiple `--env-file` declarations (Yagiz Nizipli) #49542 src,permission: * add multiple allow-fs-* flags (Carlos Espa) #49047 test_runner: * (SEMVER-MINOR) expose location of tests (Colin Ihrig) #48975 PR-URL: #49592

Notable changes: crypto: * update root certificates to NSS 3.93 (Node.js GitHub Bot) #49341 deps: * upgrade npm to 10.0.0 (npm team) #49423 * upgrade npm to 10.1.0 (npm team) #49570 doc: * move and rename loaders section (Geoffrey Booth) #49261 * add release key for Ulises Gascon (Ulises Gascón) #49196 lib: * (SEMVER-MINOR) add api to detect whether source-maps are enabled (翠 / green) #46391 src: * support multiple `--env-file` declarations (Yagiz Nizipli) #49542 src,permission: * add multiple allow-fs-* flags (Carlos Espa) #49047 test_runner: * (SEMVER-MINOR) expose location of tests (Colin Ihrig) #48975 PR-URL: #49592

Notable changes: crypto: * update root certificates to NSS 3.93 (Node.js GitHub Bot) #49341 deps: * upgrade npm to 10.1.0 (npm team) #49570 * upgrade npm to 10.0.0 (npm team) #49423 doc: * move and rename loaders section (Geoffrey Booth) #49261 * add release key for Ulises Gascon (Ulises Gascón) #49196 lib: * (SEMVER-MINOR) add api to detect whether source-maps are enabled (翠 / green) #46391 src: * support multiple `--env-file` declarations (Yagiz Nizipli) #49542 src,permission: * add multiple allow-fs-* flags (Carlos Espa) #49047 test_runner: * (SEMVER-MINOR) expose location of tests (Colin Ihrig) #48975 PR-URL: #49592

Notable changes: crypto: * update root certificates to NSS 3.93 (Node.js GitHub Bot) nodejs#49341 deps: * upgrade npm to 10.1.0 (npm team) nodejs#49570 * upgrade npm to 10.0.0 (npm team) nodejs#49423 doc: * move and rename loaders section (Geoffrey Booth) nodejs#49261 * add release key for Ulises Gascon (Ulises Gascón) nodejs#49196 lib: * (SEMVER-MINOR) add api to detect whether source-maps are enabled (翠 / green) nodejs#46391 src: * support multiple `--env-file` declarations (Yagiz Nizipli) nodejs#49542 src,permission: * add multiple allow-fs-* flags (Carlos Espa) nodejs#49047 test_runner: * (SEMVER-MINOR) expose location of tests (Colin Ihrig) nodejs#48975 PR-URL: nodejs#49592

PR-URL: nodejs#49261 Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Jacob Smith <jacob@frende.me> Reviewed-By: Rafael Gonzaga <rafael.nunu@hotmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>

Notable changes: crypto: * update root certificates to NSS 3.93 (Node.js GitHub Bot) nodejs#49341 deps: * upgrade npm to 10.1.0 (npm team) nodejs#49570 * upgrade npm to 10.0.0 (npm team) nodejs#49423 doc: * move and rename loaders section (Geoffrey Booth) nodejs#49261 * add release key for Ulises Gascon (Ulises Gascón) nodejs#49196 lib: * (SEMVER-MINOR) add api to detect whether source-maps are enabled (翠 / green) nodejs#46391 src: * support multiple `--env-file` declarations (Yagiz Nizipli) nodejs#49542 src,permission: * add multiple allow-fs-* flags (Carlos Espa) nodejs#49047 test_runner: * (SEMVER-MINOR) expose location of tests (Colin Ihrig) nodejs#48975 PR-URL: nodejs#49592

PR-URL: nodejs#49261 Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Jacob Smith <jacob@frende.me> Reviewed-By: Rafael Gonzaga <rafael.nunu@hotmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>

PR-URL: #49261 Backport-PR-URL: #50669 Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Jacob Smith <jacob@frende.me> Reviewed-By: Rafael Gonzaga <rafael.nunu@hotmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>

Notable changes: deps: * (SEMVER-MINOR) update uvwasi to 0.0.19 (Node.js GitHub Bot) #49908 * (SEMVER-MINOR) upgrade npm to 10.0.0 (npm team) #49423 doc: * add new TSC members (Michael Dawson) #48841 * move and rename loaders section (Geoffrey Booth) #49261 esm: * use import attributes instead of import assertions (Antoine du Hamel) #50140 * --experimental-default-type flag to flip module defaults (Geoffrey Booth) #49869 * unflag import.meta.resolve (Guy Bedford) #49028 * move hook execution to separate thread (Jacob Smith) #44710 * leverage loaders when resolving subsequent loaders (Maël Nison) #43772 lib: * (SEMVER-MINOR) add api to detect whether source-maps are enabled (翠 / green) #46391 * (SEMVER-MINOR) add tracing channel to diagnostics_channel (Stephen Belanger) #44943 src: * (SEMVER-MINOR) add cjs_module_lexer_version base64_version (Jithil P Ponnan) #45629 stream: * use bitmap in readable state (Benjamin Gruenbaum) #49745 test_runner: * (SEMVER-MINOR) accept `testOnly` in `run` (Moshe Atlow) #49753 * (SEMVER-MINOR) add junit reporter (Moshe Atlow) #49614 * (SEMVER-MINOR) expose location of tests (Colin Ihrig) #48975 * (SEMVER-MINOR) add shards support (Raz Luvaton) #48639 * (SEMVER-MINOR) add initial draft for fakeTimers (Erick Wendel) #47775 test_runner, cli: * (SEMVER-MINOR) add --test-concurrency flag (Colin Ihrig) #49996 tls: * (SEMVER-MINOR) add ALPNCallback server option for dynamic ALPN negotiation (Tim Perry) #45190 vm: * (SEMVER-MINOR) use import attributes instead of import assertions (Antoine du Hamel) #50141 wasi: * (SEMVER-MINOR) updates required for latest uvwasi version (Michael Dawson) #49908 PR-URL: TODO

Notable changes: deps: * (SEMVER-MINOR) update uvwasi to 0.0.19 (Node.js GitHub Bot) #49908 * (SEMVER-MINOR) upgrade npm to 10.2.3 (npm team) #50531 doc: * move and rename loaders section (Geoffrey Booth) #49261 esm: * use import attributes instead of import assertions (Antoine du Hamel) #50140 * --experimental-default-type flag to flip module defaults (Geoffrey Booth) #49869 * unflag import.meta.resolve (Guy Bedford) #49028 * move hook execution to separate thread (Jacob Smith) #44710 * leverage loaders when resolving subsequent loaders (Maël Nison) #43772 lib: * (SEMVER-MINOR) add api to detect whether source-maps are enabled (翠 / green) #46391 * (SEMVER-MINOR) add tracing channel to diagnostics_channel (Stephen Belanger) #44943 src: * (SEMVER-MINOR) add cjs_module_lexer_version base64_version (Jithil P Ponnan) #45629 stream: * use bitmap in readable state (Benjamin Gruenbaum) #49745 test_runner: * (SEMVER-MINOR) accept `testOnly` in `run` (Moshe Atlow) #49753 * (SEMVER-MINOR) add junit reporter (Moshe Atlow) #49614 * (SEMVER-MINOR) expose location of tests (Colin Ihrig) #48975 * (SEMVER-MINOR) add shards support (Raz Luvaton) #48639 * (SEMVER-MINOR) add initial draft for fakeTimers (Erick Wendel) #47775 test_runner, cli: * (SEMVER-MINOR) add --test-concurrency flag (Colin Ihrig) #49996 tls: * (SEMVER-MINOR) add ALPNCallback server option for dynamic ALPN negotiation (Tim Perry) #45190 vm: * (SEMVER-MINOR) use import attributes instead of import assertions (Antoine du Hamel) #50141 PR-URL: #50953

PR-URL: nodejs/node#49261 Backport-PR-URL: nodejs/node#50669 Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Jacob Smith <jacob@frende.me> Reviewed-By: Rafael Gonzaga <rafael.nunu@hotmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>

Notable changes: deps: * (SEMVER-MINOR) update uvwasi to 0.0.19 (Node.js GitHub Bot) nodejs/node#49908 * (SEMVER-MINOR) upgrade npm to 10.2.3 (npm team) nodejs/node#50531 doc: * move and rename loaders section (Geoffrey Booth) nodejs/node#49261 esm: * use import attributes instead of import assertions (Antoine du Hamel) nodejs/node#50140 * --experimental-default-type flag to flip module defaults (Geoffrey Booth) nodejs/node#49869 * unflag import.meta.resolve (Guy Bedford) nodejs/node#49028 * move hook execution to separate thread (Jacob Smith) nodejs/node#44710 * leverage loaders when resolving subsequent loaders (Maël Nison) nodejs/node#43772 lib: * (SEMVER-MINOR) add api to detect whether source-maps are enabled (翠 / green) nodejs/node#46391 * (SEMVER-MINOR) add tracing channel to diagnostics_channel (Stephen Belanger) nodejs/node#44943 src: * (SEMVER-MINOR) add cjs_module_lexer_version base64_version (Jithil P Ponnan) nodejs/node#45629 stream: * use bitmap in readable state (Benjamin Gruenbaum) nodejs/node#49745 test_runner: * (SEMVER-MINOR) accept `testOnly` in `run` (Moshe Atlow) nodejs/node#49753 * (SEMVER-MINOR) add junit reporter (Moshe Atlow) nodejs/node#49614 * (SEMVER-MINOR) expose location of tests (Colin Ihrig) nodejs/node#48975 * (SEMVER-MINOR) add shards support (Raz Luvaton) nodejs/node#48639 * (SEMVER-MINOR) add initial draft for fakeTimers (Erick Wendel) nodejs/node#47775 test_runner, cli: * (SEMVER-MINOR) add --test-concurrency flag (Colin Ihrig) nodejs/node#49996 tls: * (SEMVER-MINOR) add ALPNCallback server option for dynamic ALPN negotiation (Tim Perry) nodejs/node#45190 vm: * (SEMVER-MINOR) use import attributes instead of import assertions (Antoine du Hamel) nodejs/node#50141 PR-URL: nodejs/node#50953

PR-URL: nodejs/node#49261 Backport-PR-URL: nodejs/node#50669 Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Jacob Smith <jacob@frende.me> Reviewed-By: Rafael Gonzaga <rafael.nunu@hotmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>

Notable changes: deps: * (SEMVER-MINOR) update uvwasi to 0.0.19 (Node.js GitHub Bot) nodejs/node#49908 * (SEMVER-MINOR) upgrade npm to 10.2.3 (npm team) nodejs/node#50531 doc: * move and rename loaders section (Geoffrey Booth) nodejs/node#49261 esm: * use import attributes instead of import assertions (Antoine du Hamel) nodejs/node#50140 * --experimental-default-type flag to flip module defaults (Geoffrey Booth) nodejs/node#49869 * unflag import.meta.resolve (Guy Bedford) nodejs/node#49028 * move hook execution to separate thread (Jacob Smith) nodejs/node#44710 * leverage loaders when resolving subsequent loaders (Maël Nison) nodejs/node#43772 lib: * (SEMVER-MINOR) add api to detect whether source-maps are enabled (翠 / green) nodejs/node#46391 * (SEMVER-MINOR) add tracing channel to diagnostics_channel (Stephen Belanger) nodejs/node#44943 src: * (SEMVER-MINOR) add cjs_module_lexer_version base64_version (Jithil P Ponnan) nodejs/node#45629 stream: * use bitmap in readable state (Benjamin Gruenbaum) nodejs/node#49745 test_runner: * (SEMVER-MINOR) accept `testOnly` in `run` (Moshe Atlow) nodejs/node#49753 * (SEMVER-MINOR) add junit reporter (Moshe Atlow) nodejs/node#49614 * (SEMVER-MINOR) expose location of tests (Colin Ihrig) nodejs/node#48975 * (SEMVER-MINOR) add shards support (Raz Luvaton) nodejs/node#48639 * (SEMVER-MINOR) add initial draft for fakeTimers (Erick Wendel) nodejs/node#47775 test_runner, cli: * (SEMVER-MINOR) add --test-concurrency flag (Colin Ihrig) nodejs/node#49996 tls: * (SEMVER-MINOR) add ALPNCallback server option for dynamic ALPN negotiation (Tim Perry) nodejs/node#45190 vm: * (SEMVER-MINOR) use import attributes instead of import assertions (Antoine du Hamel) nodejs/node#50141 PR-URL: nodejs/node#50953

GeoffreyBooth added doc Issues and PRs related to the documentations. module Issues and PRs related to the module subsystem. esm Issues and PRs related to the ECMAScript Modules implementation. loaders Issues and PRs related to ES module loaders labels Aug 20, 2023

doc: move and rename loaders section

b9a97ab

GeoffreyBooth force-pushed the move-module-customization-hooks branch from cc88f17 to b9a97ab Compare August 20, 2023 21:52

fix code blocks per linter

1c660aa

mcollina approved these changes Aug 21, 2023

View reviewed changes

This was referenced Aug 21, 2023

doc: update module customization hooks docs #49265

Merged

Node.js Loaders Team Meeting 2023-08-15 nodejs/loaders#154

Closed

JakobJingleheimer approved these changes Aug 21, 2023

View reviewed changes

aymen94 approved these changes Aug 21, 2023

View reviewed changes

RafaelGSS added the notable-change PRs with changes that should be highlighted in changelogs. label Aug 21, 2023

RafaelGSS approved these changes Aug 21, 2023

View reviewed changes

benjamingr approved these changes Aug 21, 2023

View reviewed changes

nodejs-github-bot removed the commit-queue Add this label to land a pull request using GitHub Actions. label Aug 22, 2023

nodejs-github-bot merged commit 164c57d into nodejs:main Aug 22, 2023
26 checks passed

GeoffreyBooth deleted the move-module-customization-hooks branch August 23, 2023 15:19

UlisesGascon mentioned this pull request Sep 10, 2023

v20.7.0 proposal #49592

Merged

targos mentioned this pull request Nov 11, 2023

[v18.x] Backport most ESM and customization hook changes #50669

Closed

targos added the backported-to-v18.x PRs backported to the v18.x-staging branch. label Nov 23, 2023

targos mentioned this pull request Nov 28, 2023

v18.19.0 release proposal #50953

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: move and rename loaders section #49261

doc: move and rename loaders section #49261

GeoffreyBooth commented Aug 20, 2023 •

edited

nodejs-github-bot commented Aug 20, 2023

mcollina left a comment

github-actions bot commented Aug 21, 2023

nodejs-github-bot commented Aug 22, 2023

doc: move and rename loaders section #49261

doc: move and rename loaders section #49261

Conversation

GeoffreyBooth commented Aug 20, 2023 • edited

Notable changes

ESM Loaders are now Module Customization Hooks

nodejs-github-bot commented Aug 20, 2023

mcollina left a comment

Choose a reason for hiding this comment

github-actions bot commented Aug 21, 2023

nodejs-github-bot commented Aug 22, 2023

GeoffreyBooth commented Aug 20, 2023 •

edited