Skip to content

doc: update module customization hooks docs

Rodrigo Muino Tomonari requested to merge github/fork/GeoffreyBooth/update-module-customization-hooks-docs into main

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 in cli.md, rewriting to recommend --import with register() 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 like ts-node will need code on the main thread, which --import with register() 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 and load hooks as “1.2 - Release candidate,” and globalPreload 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 from cli.md?

  • Update --experimental-loader to print a warning that it may be removed in the future, and users should use --import with register 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

Merge request reports