module: doc-deprecate module.register()

[GeoffreyBooth]

This PR doc-deprecates module.register() in favor of module.registerHooks().

In discussion with @joyeecheung we were thinking of landing this now so it can go out in 25 and 26, and then a runtime deprecation can go out in 26. cc @nodejs/loaders @nodejs/releasers

The module.registerHooks API is nearing stability; at the very least it’s already much more stable than module.register, and lacks the unresolvable issues that plagued module.register.

[nodejs-github-bot]

Review requested:

• @nodejs/loaders
• @nodejs/userland-migrations

[JakobJingleheimer]

In general I support this, but we had previously discussed providing the tools to facilitate in userland. Matteo opened a PR to donate the requisite machina, but that's stalled.

I'm a little fuzzy on when that part should be available. I'm thinking it should be available when the depreciation is announced.

[GeoffreyBooth]

There’s https://github.com/joyeecheung/module-register-ponyfill

[JakobJingleheimer]

Joyee FtW 🙌

For a doc depreciation, I think it's fine. But for a runtime depreciation, I think a replacement solution or requisite pieces need to be available in Core first 😬

[mcollina]

lgtm

[legendecas]

I think it would be more prudent to promote module.registerHooks as stable before marking this as deprecated. Otherwise, there will be no single API that is stable to register a module loader, and a broadly used API is going to be deprecated.

We should encourage people to migrate from a widely-used experimental API to a stable API, rather than another still-technically-experimental API.

Right now, module.registerHooks is still at Release Candidate.

[GeoffreyBooth]

@legendecas I defer to the consensus of the group, but what I was thinking was:

1. Doc-deprecate module.register now. Hopefully release this as part of 26.0.0.
2. Runtime deprecate module.register as soon as module.registerHooks are stable, hopefully sometime this summer, in a 26 minor release.
3. Remove module.register in the following semver-major.

The doc-deprecation sooner than later is to start preparing the users for the shift. Aligning it with the 26 release maximizes visibility. And module.register is itself still experimental, at 1.1, a lower level than module.registerHooks.

[AugustinMauroy]

LGMT !

[legendecas]

Runtime deprecate module.register as soon as module.registerHooks are stable, hopefully sometime this summer, in a 26 minor release.

I think this is what concerns me. The migration takes time and work. Asking library maintainers to migrate should not be taken for granted, not mentioning asking them to migrate to an API that is not stable yet. If we believe it is time for library owners to migrate, we should promote module.registerHooks as stable now.

Also /cc @nodejs/import-in-the-middle-maintainers, as import-in-the-middle is still using module.register.

[GeoffreyBooth]

I think this is what concerns me. The migration takes time and work. Asking library maintainers to migrate should not be taken for granted, not mentioning asking them to migrate to an API that is not stable yet. If we believe it is time for library owners to migrate, we should promote module.registerHooks as stable now.

Yes, so shouldn’t we give them as much warning as possible? And if they start migrating to registerHooks while it’s still release candidate, then it if has any issues discovered by increased adoption we have more flexibility in fixing those issues before marking the API as stable.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.68%. Comparing base (8199f9c) to head (d153a03).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #62395      +/-   ##
==========================================
- Coverage   89.69%   89.68%   -0.02%     
==========================================
  Files         676      676              
  Lines      206693   206693              
  Branches    39577    39584       +7     
==========================================
- Hits       185402   185379      -23     
- Misses      13435    13447      +12     
- Partials     7856     7867      +11     

see 30 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[legendecas]

I'm not arguing if module.register should be deprecated or not. I'm definitely +1 on this.

What I'm arguing is that we should promote module.registerHooks to stable first. We should not deprecate what people are using now, without an alternative that we can confidently recommend people using. If there are still blockers to promote module.registerHooks to stable, we should address these blockers first.

[GeoffreyBooth]

What I’m arguing is that we should promote module.registerHooks to stable first.

Can we doc-deprecate module.register() now, and then runtime deprecation waits until registerHooks is stable? I’d like to take advantage of the visibility of the 26.0.0 announcement to encourage the migration to begin. Especially since registerHooks will hopefully go stable in a minor release, and therefore the runtime deprecation will also happen in a minor release. Like if both of those happen in August 2026, say, and we remove register in 27.0.0 in April 2027, then that’s only 8 months for people to migrate. Whereas if we announce this now, there’s a full year.

Also we think registerHooks is ready for stability but getting more real users would help confirm it, and this doc deprecation would help with that.

Also I don’t see why registerHooks needs to be stable before deprecating register at all, either doc or runtime. They’re both experimental features, and register is more experimental. I agree that we need a stable migration path before removing register, but just deprecating it I feel shouldn’t require so much effort.

[legendecas]

I'd be happy to +1 if the @nodejs/loaders team has consensus on this plan.

But I'd also like to defer the runtime deprecation of module.register. At least, it should wait a big longer after module.registerHooks is stable, giving library owners enough time to migrate, without noisy runtime warnings.

[joyeecheung]

While I sympathize @legendecas's concerns, I think making module.registerHooks fully stable before we send a stronger signal to nudge people away from module.register could make it harder to do any last-minute updates to module.registerHooks if they are revealed to be necessary by the migration (I don't anticipate any, but one doesn't know what they doesn't know. In recent months all we did were bug fixes instead of any structural issues, the different threading model means some existing module.register handlers need more significant changes e.g. like tapjs, but not having to deal with worker synchronization is usually a relief). I think "release candidate" is a strong enough signal to library authors that it's something they can trust now - if they need more we can go stronger with the wording a bit in the 26 release announcement i.e. module.registerHooks is basically ready to go stable and we are just trying to wait for more feedback to mark it so in October.

Note that this PR only doc-deprecates it. When discussing with @GeoffreyBooth, our rough ideas was like this:

1. For 26 (ideally 26.0.0, or an early version long before it hits LTS), we start emitting warnings and suggest them to migrate to module.registerHooks. Considering that most people won't try out 26 the moment it's out and it requires an explicit upgrade action to receive the extra noise, which won't happen at sccale until 26 goes LTS, I think it's ample time for libraries to pick it up.
2. For <= 25, it's only doc-deprecated. Library authors may get a nudge from their editors etc., but end users would not be disrupted. We won't emit warnings for <= 25.

This means between now until September/October (when 26 goes LTS), we should have even more feedback from migrators to gain more confidence about whether module.registerHooks should go fully stable - we do have some popular libraries using it now like tapjs and vite-ecosystem tools, which is why we are also getting bugfix backport requests to v22, but more battle testing would still be useful. This also plays well with the timeline that v20.x goes EOL after April, and this is when module.registerHooks can be considered as the widely available LTS baseline by library authors. That helps closing a gap by leaving a few months to get feedback from those who are still waiting because v20.x is not yet EOL - I think the phasing out of 20.x is much more important in practice for library authors to rely on module.registerHooks. Flipping the stability index in docs now only gives marginal returns while there's still significant usage of v20.x around, and it's unlikely to be the primary bottleneck at least before Ocotber.

[joyeecheung]

I'd be happy to +1 if the @nodejs/loaders team has consensus on this plan.

FWIW I think the loaders team as an orchestration is like most other informal FYI teams now - many of the recent loader-related changes (e.g. clearCache, VFS) are happening orthogonally to the loader team's roadmap, and AFAICT the loader team meeting has been inactive for some time. A consensus from the loaders team would be like consensus from the performance team - might be useful if it's obtainable, but since it's not consistently coordinated by anyone as a proper venue/owner, it's not more meaningful than the general consensus from collaborators who show up for a PR.

[legendecas]

For <= 25, it's only doc-deprecated. Library authors may get a nudge from their editors etc., but end users would not be disrupted. We won't emit warnings for <= 25.

Sounds good to me! Appreciate all the explainations!