doc: reorganize docs of module hooks and mark sync hooks as release candidate

[joyeecheung]

doc: mark sync module hooks as release candidate

doc: reorganize docs of module customization hooks

This reorganizes the documentation of module customization hooks to promote the synchronous variant as it has fewer caveats. Previously the documentation was organized as follows:

To do something:

1. For asynchronous hooks, do this, which may have these caveats
2. For synchronous hooks, do this, which does not have the caveats

To do something else:

1. For asynchronous hooks, do this, which may have these caveats
2. For synchronous hooks, do this, which does not have the caveats

It's now organized as follows:

Synchronous hooks:

• To do something, do this.
• To do something else, do this. (No mention that it doesn't have caveats, because users are not supposed to burden themselves with caveats in the other API that they do not use).

Asynchronous hooks: They have these caveats, if they are too complex to deal with, consider use the synchronous variant.

• To do something, do this, which may have these caveats.
• To do something, do this, which may have these caveats.

Refs: https://github.com/nodejs/node/issues/56241

[nodejs-github-bot]

Review requested:

• [ ] @nodejs/loaders

[joyeecheung]

Rebased to resolve the conflicts and addressed reviews. PTAL, thanks @GeoffreyBooth

[joyeecheung]

Applied the suggestions. PTAL, thanks @GeoffreyBooth @aduh95

[nodejs-github-bot]

Commit Queue failed

- Loading data for nodejs/node/pull/60960
✔  Done loading data for nodejs/node/pull/60960
----------------------------------- PR info ------------------------------------
Title      doc: reorganize docs of module hooks and mark sync hooks as release candidate (#60960)
Author     Joyee Cheung <[email protected]> (@joyeecheung)
Branch     joyeecheung:sync-hooks-rc -> nodejs:main
Labels     doc, review wanted
Commits    3
 - doc: reorganize docs of module customization hooks
 - doc: mark sync module hooks as release candidate
 - fixup! doc: reorganize docs of module customization hooks
Committers 2
 - Joyee Cheung <[email protected]>
 - GitHub <[email protected]>
PR-URL: https://github.com/nodejs/node/pull/60960
Refs: https://github.com/nodejs/node/issues/56241
Reviewed-By: Geoffrey Booth <[email protected]>
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/60960
Refs: https://github.com/nodejs/node/issues/56241
Reviewed-By: Geoffrey Booth <[email protected]>
--------------------------------------------------------------------------------
   ℹ  This PR was created on Fri, 05 Dec 2025 11:24:58 GMT
   ✔  Approvals: 1
   ✔  - Geoffrey Booth (@GeoffreyBooth): https://github.com/nodejs/node/pull/60960#pullrequestreview-3558822069
   ✔  Last GitHub CI successful
   ℹ  Green GitHub CI is sufficient
--------------------------------------------------------------------------------
   ✔  No git cherry-pick in progress
   ✔  No git am in progress
   ✔  No git rebase in progress
--------------------------------------------------------------------------------
- Bringing origin/main up to date...
From https://github.com/nodejs/node
 * branch                  main       -> FETCH_HEAD
✔  origin/main is now up-to-date
- Downloading patch for 60960
From https://github.com/nodejs/node
 * branch                  refs/pull/60960/merge -> FETCH_HEAD
✔  Fetched commits as 81e05e124f71..116abd0823f4
--------------------------------------------------------------------------------
Auto-merging doc/api/cli.md
Auto-merging doc/api/module.md
[main 0a64245be1] doc: reorganize docs of module customization hooks
 Author: Joyee Cheung <[email protected]>
 Date: Tue Dec 2 14:28:30 2025 +0800
 2 files changed, 513 insertions(+), 335 deletions(-)
Auto-merging doc/api/module.md
[main 459594c3f6] doc: mark sync module hooks as release candidate
 Author: Joyee Cheung <[email protected]>
 Date: Wed Dec 3 13:26:47 2025 +0800
 1 file changed, 6 insertions(+), 2 deletions(-)
Auto-merging doc/api/module.md
[main 5744595733] fixup! doc: reorganize docs of module customization hooks
 Author: Joyee Cheung <[email protected]>
 Date: Tue Dec 9 17:34:16 2025 +0100
 1 file changed, 5 insertions(+), 13 deletions(-)
   ✔  Patches applied
There are 3 commits in the PR. Attempting autorebase.
(node:2246) [DEP0190] DeprecationWarning: Passing args to a child process with shell option true can lead to security vulnerabilities, as the arguments are not escaped, only concatenated.
(Use `node --trace-deprecation ...` to show where the warning was created)
Rebasing (2/5)
Rebasing (3/5)
Executing: git node land --amend --yes
--------------------------------- New Message ----------------------------------
doc: reorganize docs of module customization hooks
This reorganizes the documentation of module customization hooks
to promote the synchronous variant as it has fewer caveats.
Previously the documentation was organized as follows:
To do something:

For asynchronous hooks, do this, which may have these caveats
For synchronous hooks, do this, which does not have the caveats

To do something else:

For asynchronous hooks, do this, which may have these caveats
For synchronous hooks, do this, which does not have the caveats

It's now organized as follows:
Synchronous hooks:
To do something, do this.
To do something else, do this.
(No mention that it doesn't have caveats, because users are not supposed
to burden themselves with caveats in the other API that they do not
use).
Asynchronous hooks:
They have these caveats, if they are too complex to deal with, consider
use the synchronous variant.
To do something, do this, which may have these caveats.
To do something, do this, which may have these caveats.
PR-URL: https://github.com/nodejs/node/pull/60960
Refs: https://github.com/nodejs/node/issues/56241
Reviewed-By: Geoffrey Booth <[email protected]>
[detached HEAD 4807155eff] doc: reorganize docs of module customization hooks
Author: Joyee Cheung <[email protected]>
Date: Tue Dec 2 14:28:30 2025 +0800
2 files changed, 505 insertions(+), 335 deletions(-)
Rebasing (4/5)
Rebasing (5/5)
Executing: git node land --amend --yes
--------------------------------- New Message ----------------------------------
doc: mark sync module hooks as release candidate
PR-URL: https://github.com/nodejs/node/pull/60960
Refs: https://github.com/nodejs/node/issues/56241
Reviewed-By: Geoffrey Booth <[email protected]>
[detached HEAD eaca4c8c12] doc: mark sync module hooks as release candidate
Author: Joyee Cheung <[email protected]>
Date: Wed Dec 3 13:26:47 2025 +0800
1 file changed, 6 insertions(+), 2 deletions(-)
Successfully rebased and updated refs/heads/main.
ℹ  Add commit-queue-squash label to land the PR as one commit, or commit-queue-rebase to land as separate commits.

https://github.com/nodejs/node/actions/runs/20174007589

[nodejs-github-bot]

Landed in 81e05e124f71b3050cd4e60c95017af975568413...28b11396feb9ae576d492ebee1b5840b9b6689ea