Skip to content

Conversation

@joyeecheung
Copy link
Member

@joyeecheung joyeecheung commented Dec 5, 2025

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: #56241

@nodejs-github-bot
Copy link
Collaborator

Review requested:

  • @nodejs/loaders

@nodejs-github-bot nodejs-github-bot added the doc Issues and PRs related to the documentations. label Dec 5, 2025
@joyeecheung joyeecheung force-pushed the sync-hooks-rc branch 2 times, most recently from 3154919 to b38dcae Compare December 5, 2025 14:31
Copy link
Member

@GeoffreyBooth GeoffreyBooth left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestions. Thank you for doing this.

@joyeecheung joyeecheung force-pushed the sync-hooks-rc branch 2 times, most recently from 2944f29 to e33e818 Compare December 8, 2025 16:02
@joyeecheung joyeecheung added the review wanted PRs that need reviews. label Dec 8, 2025
@joyeecheung
Copy link
Member Author

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

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.
#### Caveats of asynchronous customization hooks
The asynchronous customization hooks have many caveats and the it is uncertain if their
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The asynchronous customization hooks have many caveats and the it is uncertain if their
The asynchronous customization hooks have many caveats and it is uncertain if their

are registered.
##### Registering hooks before application code runs programmatically
Alternatively, `registerHooks()` can be called from the entry point.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Alternatively, `registerHooks()` can be called from the entry point.
Alternatively, `registerHooks()` can be called from the entry point.

```
In this example, the registered hooks will form chains. These chains run
last-in, first out (LIFO). If both `hook1` and `hook2` define a `resolve`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
last-in, first out (LIFO). If both `hook1` and `hook2` define a `resolve`
last-in, first-out (LIFO). If both `hook1` and `hook2` define a `resolve`

Comment on lines +784 to +788
<!-- lint disable prohibited-strings remark-lint-->
Node.js' default ← `hook1.resolve``hook2.resolve`
<!--lint enable prohibited-strings-->
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<!-- lint disable prohibited-strings remark-lint-->
Node.js' default ← `hook1.resolve``hook2.resolve`
<!--lint enable prohibited-strings-->
Node.js default `resolve``hook1.resolve``hook2.resolve`

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And the other similar case later on.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

doc Issues and PRs related to the documentations. review wanted PRs that need reviews.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants