Repository navigation
modules: add guide to using module customization hooks - #190
GeoffreyBooth wants to merge 3 commits into
Conversation
Node.js 27 removes `module.register()` and the `--experimental-loader` and `--loader` flags (DEP0205). Explain how to move to `module.registerHooks()`, what behaves differently, and what to use when hooks need asynchronous work (`module-register-ponyfill` or `everysync`). Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
👋 Codeowner Review RequestThe following codeowners have been identified for the changed files: Team reviewers: @nodejs/loaders @nodejs/nodejs-website Please review the changes when you have a chance. Thank you! 🙏 |
|
Should this be a learn article or a blog cc @nodejs/nodejs-website |
There was a problem hiding this comment.
🟡 Changes recommended
The migration guide overstates registration-chain compatibility and omits an explicit network-appropriate timeout, so valid hook bootstrapping or module downloads can fail.
2 open issues
What changed in this PR
Adds a migration guide to the Node.js learning documentation for the removal of module.register() and loader flags in Node.js 27.
Changes:
- Explains migration to
registerHooks()with before-and-after examples and behavioral differences. - Covers asynchronous alternatives, worker setup, and troubleshooting.
- Links the guide from the Modules navigation.
| File | Description |
|---|---|
site.json |
Adds the migration guide to the Modules navigation. |
pages/modules/migrating-from-module-register.md |
Documents migration paths, examples, compatibility considerations, and common errors. |
Review effort: Balanced
Document the ponyfill's cross-hook loading divergence, set an explicit `everysync` timeout in the example and explain the default, and show the `ERR_MODULE_REGISTER_REMOVED` error that `module.register()` now throws. Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Perhaps both? This page is meant to be the durable how-to, which is why I put it in Learn: it shows how to migrate, with working examples, and it will stay useful as people upgrade over time. A blog post can announce when nodejs/node#67090 lands and point people to this article. |
ovflowd
left a comment
ovflowd
left a comment
There was a problem hiding this comment.
I'm unsure now what's the precedence. Where do migration guides usually go cc @JakobJingleheimer?
|
Thanks @GeoffreyBooth (and @ovflowd for the ping)! This wasn't quite what I had in mind: The existing Learn migration guides are long-lived type things, helping users adopt a node feature instead of a userland (npm) library/package that will likely continue to exist. Whereas this is a node deprecation migration (so it has an end-date). Individual userland-migrations cover themselves (and then are linked via the Intro to Userland Migrations Learn article). What I had envisioned was a more general-purpose guide, like: Using customisation hooksHow/why it's useful Synchronous workWhat is "synchronous work"How to do with
|
Restructure the page as a general guide to module customization hooks (synchronous work with registerHooks(), asynchronous work with module-register-ponyfill and everysync) instead of a migration guide, with a short end-of-life section for module.register(). The migration steps move to a userland-migrations recipe. Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
GeoffreyBooth
changed the title
|
Okay @JakobJingleheimer, I’ve restructured the page to match your outline: it’s now an evergreen “Using module customization hooks” guide, with sections on synchronous work ( The migration itself is now a codemod recipe in nodejs/userland-migrations#572, so the Intro to Userland Migrations article can link to it. Once it’s published on Learn, I’ll point the end-of-life section there instead of the repo. |
Adds a Learn guide to module customization hooks, written for someone using them for the first time. It lives at
/learn/modules/using-customization-hooksand is linked from the "Modules" group insite.json.This replaces the migration guide this PR originally added. Following review feedback, the page is an evergreen guide, not a migration guide for a deprecation with an end date. The migration lives in a userland-migrations recipe instead: nodejs/userland-migrations#572.
The page covers:
module.registerHooks(): a.txtloader, JSX (esbuild) and CoffeeScript compilers, and notes onrequire(), workers and registration order, with a pointer to@nodejs-loadersmodule-register-ponyfillor a bridge built witheverysyncmodule.register()and the--loaderflags (DEP0205, removed in module: remove async module customization hooks node#67090), with a link to the codemod and a feature-detection snippet for packages that support versions with and withoutregisterHooks()Once the recipe is published on Learn, the codemod link should point to
/learn/userland-migrations/module-register-to-register-hooks; for now it points to the repository.I ran every code example on the page on Node.js 26.12.1 (the network examples against a local HTTPS server).
🤖 Generated with Claude Code