doc: update module customization hooks docs
This PR builds on and follows up https://github.com/nodejs/node/pull/49261.
The aim here was to implement most of this to-do list. In particular:
-
I hopefully removed all references to the “Loaders API” and similar nomenclature, in favor of “module customization hooks” or “hooks” or similar.
-
I moved most of the “how to use this API” text out of the
module.register()
section and into a new section “Enabling” under the “Customization Hooks” heading. -
I removed all references to
--experimental-loader
except incli.md
, rewriting to recommend--import
withregister()
instead. We’re considering removing the--experimental-loader
flag, but for now at least we want to discourage its use. (We anticipate that most third-party libraries likets-node
will need code on the main thread, which--import
withregister()
can enable but--experimental-loader
cannot, so people should get familiar with the more powerful approach and we don’t need a secondary, less capable method.) -
I added CommonJS versions of all code samples that could support them (so anything running on the main thread, since the hooks module needs to export specific named functions).
-
I classified the overall Module Customization Hooks API as stability level “1.1 - Active development” and the
resolve
andload
hooks as “1.2 - Release candidate,” andglobalPreload
as “1.0 - Early development” (since I can’t mark it as deprecated, but its end is near whenever #49144 lands). -
I added some mentions that parts of this work for CommonJS modules and
require
as well. -
The CoffeeScript example seemed to have gotten out of date, so I rewrote it to how I think it should be now that CommonJS is supported.
-
Miscellaneous cleanup.
What’s left for follow-up PRs:
-
Remove the
globalPreload
section as part of #49144. -
Remove the mention of
--experimental-loader
fromcli.md
? -
Update
--experimental-loader
to print a warning that it may be removed in the future, and users should use--import
withregister
instead; this warning could even generate example code that shows--import
with a data URL that includes the value of what was passed to--experimental-loader
(similar to how we have a fancy error message with suggested new code for unknown named exports from CommonJS modules).
Also fixes https://github.com/nodejs/node/issues/49282.
cc @nodejs/loaders @nodejs/modules @aduh95 @JakobJingleheimer