fix(node): use Module.registerHooks instead of deprecated Module.register for Node v26+

[cyphercodes]

Description

Node.js v26 deprecated Module.register() in favor of Module.registerHooks(), causing a deprecation warning when using Tailwind CSS with Node v26:

[DEP0205] DeprecationWarning: `module.register()` is deprecated. Use `module.registerHooks()` instead.

This change uses the new Module.registerHooks() API when available (Node v26+), falling back to the old Module.register() API for older Node versions to maintain backward compatibility.

Changes

• Check for Module.registerHooks first (new API in Node v26+)
• Fall back to Module.register for older Node versions
• Added comment explaining the version requirements

Related Issue

Fixes #19893

[coderabbitai]

Walkthrough

The Node module hook registration logic in the Tailwind CSS Node package was refactored to use a tiered approach. The code now attempts to use Module.registerHooks with a resolve option when available, and falls back to the previous Module.register method if the newer API is unavailable. The loader URL is extracted into a local variable before being passed to either registration method. This change introduces 7 lines and removes 1 line of code, maintaining backward compatibility while supporting newer Node.js module hook APIs.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change: updating to use Module.registerHooks instead of the deprecated Module.register for Node v26+, which aligns with the actual code changes.
Description check	✅ Passed	The description is well-detailed and directly related to the changeset, explaining the deprecation warning, the solution, and backward compatibility approach.
Linked Issues check	✅ Passed	The PR implements the core requirement from issue #19893: using Module.registerHooks() for Node v26+ while maintaining backward compatibility with older versions, eliminating the DEP0205 deprecation warning.
Out of Scope Changes check	✅ Passed	All changes in the PR are directly related to fixing the Module.register deprecation issue; no out-of-scope modifications are present.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/`@tailwindcss-node/src/index.ts:
- Around line 21-24: The code incorrectly attempts to use Module.registerHooks
with the async esm-cache-loader; remove the synchronous registration path and
the conditional that calls Module.registerHooks, and rely solely on
Module.register() with the async loader (the esm-cache-loader / Module.register
usage). Locate the block referencing Module.registerHooks and loaderUrl (the
import/resolution of '@tailwindcss/node/esm-cache-loader' and the if
(Module.registerHooks) branch) and delete the branch that calls
Module.registerHooks (and any passing of loaderUrl), leaving only the async
Module.register() registration flow.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 853d3ae4-7c45-4501-8adf-d6e089ca28c4

📥 Commits

Reviewing files that changed from the base of the PR and between e01946f and 10edd5a.

📒 Files selected for processing (1)

• packages/@tailwindcss-node/src/index.ts

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🌐 Web query:

In Node.js v26 node:module, what is the exact signature of module.registerHooks()and what type is required for theresolve option?

💡 Result:

In Node.js v26, the exact signature of module.registerHooks from the node:module module is: js module.registerHooks(options) Where options is an Object with the following properties: - load {Function|undefined} (optional) The synchronous load hook function. See load hook documentation. Default: undefined. - resolve {Function|undefined} (optional) The synchronous resolve hook function. See resolve hook documentation. Default: undefined. The function returns an object with a deregister method to remove the registered hooks. The resolve option requires a Function type: function resolve(specifier, context, nextResolve) { ... }. It must be synchronous for registerHooks (as opposed to the async version in module.register). It receives a specifier {string}, context {Object}, and nextResolve {Function}, and returns {Object|Promise} (but synchronous in practice for this API). This API registers synchronous, in-thread hooks for customizing module resolution and loading for both ESM and CJS, added in v23.5.0 / v22.15.0, currently at Stability: 1.2 - Release candidate (per v25 docs; stable or higher by v26). Use via --import or --require for early registration, e.g.: js // register-hooks.js import { registerHooks } from 'node:module'; registerHooks({ resolve(specifier, context, nextResolve) { // Custom logic return nextResolve(specifier, context); } }); node --import ./register-hooks.js app.js Official docs: https://nodejs.org/api/module.html#moduleregisterhooksoptions (v25; v26 unchanged per canary/preview). Implementation: nodejs/node@b2e44a8079. Tracking: nodejs/node#56241.

Citations:

• 1: nodejs/node@b2e44a8079
• 2: implement module.registerHooks() to run synchronous module customization hooks in thread nodejs/node#55698
• 3: https://nodejs.org/api/module.html
• 4: https://nodejs.org/docs/latest-v25.x/api/module.html

---

🏁 Script executed:

find . -name "*esm-cache*" -type f | head -20

Repository: tailwindlabs/tailwindcss

Length of output: 121

---

🏁 Script executed:

cat -n ./packages/@tailwindcss-node/src/esm-cache.loader.mts

Repository: tailwindlabs/tailwindcss

Length of output: 784

---

🏁 Script executed:

cat -n ./packages/@tailwindcss-node/src/index.ts

Repository: tailwindlabs/tailwindcss

Length of output: 1240

---

🏁 Script executed:

# Check Node.js documentation to understand the API design difference
# between registerHooks (sync) and register (async)
cat -n ./packages/@tailwindcss-node/src/index.ts | head -27

Repository: tailwindlabs/tailwindcss

Length of output: 1240

---

Module.registerHooks cannot be used with the async loader approach; remove the sync registration path

The esm-cache.loader is designed as an async loader for Module.register() (line 25), not for Module.registerHooks(). These APIs are incompatible—registerHooks requires synchronous hook functions, but the exported resolve hook is async. Passing loaderUrl (line 23) is incorrect, but the proposed import-and-pass approach also fails because the function is async. Either create separate synchronous hooks for registerHooks or remove the conditional and rely on Module.register() alone.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/`@tailwindcss-node/src/index.ts around lines 21 - 24, The code
incorrectly attempts to use Module.registerHooks with the async
esm-cache-loader; remove the synchronous registration path and the conditional
that calls Module.registerHooks, and rely solely on Module.register() with the
async loader (the esm-cache-loader / Module.register usage). Locate the block
referencing Module.registerHooks and loaderUrl (the import/resolution of
'@tailwindcss/node/esm-cache-loader' and the if (Module.registerHooks) branch)
and delete the branch that calls Module.registerHooks (and any passing of
loaderUrl), leaving only the async Module.register() registration flow.

[afurm]

Good migration to registerHooks. One thing to consider - if both registerHooks fails and register falls back, should we warn? Currently silent failure could be hard to debug. Also, any reason not to use feature detection for Node 26+ and skip register entirely?

[WarningImHack3r]

This AI-made PR doesn't compile. I made a PR that should work much better and be much more comprehensive at #20028

[WarningImHack3r]

Suggested change

	// `Module#registerHooks` was added in Node v26.0.0 and is the preferred API
	// `Module#registerHooks` was added in Node v23.5.0 and v22.15.0 and is the preferred API since v25.9.0,
	// runtime-deprecating `Module#register` since v26

Source: https://nodejs.org/docs/latest/api/module.html#moduleregisterhooksoptions

[WarningImHack3r]

This is incorrect usage. As per the docs, the exported resolve function from esm-cache.loader.mts can be used as-is here, no need for a loader URL anymore.