fix(node): prefer Module#registerHooks over Module#register

[WarningImHack3r]

Summary

Fix this warning when building apps with TailwindCSS with Node 26+:

(node:25346) [DEP0205] DeprecationWarning: `module.register()` is deprecated. Use `module.registerHooks()` instead.
    at node:internal/util:129:11
    at Module.register (node:internal/modules/esm/loader:969:3)
    at file:///Users/antoine/Developer/my-app/node_modules/.pnpm/@tailwindcss+node@4.3.0/node_modules/@tailwindcss/node/dist/index.mjs:18:214
    at ...

This PR:

• Correctly prefers using Module#registerHooks instead of Module#register by checking its availability at runtime
• Adjusts the exports of the hooks’ file by creating a synchronous version for the new API
• Remove now unused exports from the package.json, relying on the recommended usage in the docs for the Module#register calls

Test plan

I'd be happy to ensure this works correctly on my end before merging this, but it's not as trivial to test locally as a logic fix. Can you guide me through what I need to do to test this?

I extensively based my change on the docs, following those guides:

• Fixing imports for Module#register
• Using the new Module#registerHooks function

(and other more detailed sections of the same docs page)

---

Fixes #19893
Closes #19907

[coderabbitai]

Walkthrough

This PR refactors the ESM cache loader's module hook registration mechanism. The esm-cache.loader.mts extracts shared URL/id rewriting logic into a processResolve helper and introduces a new synchronous resolveSync hook alongside the existing async resolve hook. Both index.cts and index.ts entry points are updated to register hooks via Module.registerHooks when available, with fallback to Module.register. Package exports are updated to replace ./esm-cache-loader with ./require-cache.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: preferring Module#registerHooks over Module#register to fix the Node.js deprecation warning.
Description check	✅ Passed	The description is directly related to the changeset, explaining the deprecation warning, the solution approach, and referencing the specific Node.js documentation followed.
Linked Issues check	✅ Passed	The PR addresses both linked issues #19893 and #19907 by implementing Module#registerHooks with fallback to Module#register, creating a synchronous hook version, and removing obsolete exports.
Out of Scope Changes check	✅ Passed	All changes are directly related to addressing the deprecation warning: updating hook registration logic, adding synchronous hook support, and removing unused package.json exports.

_{✏️ 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 current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/`@tailwindcss-node/src/esm-cache.loader.mts:
- Around line 1-7: The import list includes a non-existent type ResolveHookSync
from 'node:module'; remove ResolveHookSync from the import statement in
packages/@tailwindcss-node/src/esm-cache.loader.mts and either use the correct
Node exported type (e.g., ResolveHook or ResolveFnOutput) or add a local type
alias if you need a synchronous resolve-hook signature; update any usages of
ResolveHookSync to the chosen correct type name (e.g., ResolveHook) so the
module import and type references are consistent.

🪄 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: 795f172f-edda-4b85-995c-53de79a937da

📥 Commits

Reviewing files that changed from the base of the PR and between f9216b2 and fdccada.

📒 Files selected for processing (4)

• packages/@tailwindcss-node/package.json
• packages/@tailwindcss-node/src/esm-cache.loader.mts
• packages/@tailwindcss-node/src/index.cts
• packages/@tailwindcss-node/src/index.ts

💤 Files with no reviewable changes (1)

• packages/@tailwindcss-node/package.json

[greptile-apps]

Confidence Score: 4/5

The change is safe to merge. The registerHooks and register paths are mutually exclusive and both correctly locate esm-cache.loader.mjs relative to the built output.

The core logic is sound and the deprecation fix is correct. The one subtlety worth watching is that tsup bundles esm-cache.loader.mts into the index outputs, so import.meta.url inside processResolve will refer to index.mjs/index.js rather than the loader file itself — changing the intended semantics of the self-reference guard. The id === null guard below it provides a functional backstop, so there is no observed behavioral regression, but it is a latent inconsistency that could confuse future maintainers.

esm-cache.loader.mts — specifically the import.meta.url guard in processResolve, whose URL will differ between the registerHooks (bundled) and register (separate-file) code paths.

_{Reviews (1): Last reviewed commit: "fix(node): prefer Module#registerHooks i..." | Re-trigger Greptile}

[greptile-apps]

import.meta.url points to the wrong file when bundled

When tsup builds index.cts/index.ts, it inlines esm-cache.loader.mts into the output bundle (it is a local import without an external rule). Inside the bundled output, import.meta.url resolves to dist/index.mjs (or dist/index.js), not dist/esm-cache.loader.mjs. The self-reference guard if (resolve.url === import.meta.url) therefore compares against the wrong file — it will skip processing when index.mjs itself is resolved, rather than the loader. In practice this is benign because the id === null check at line 27 already short-circuits for any module whose parent has no ?id= query param, but the semantic intent of this guard is no longer correct in the registerHooks code path.

[WarningImHack3r]

@greptile-apps How did it work before this PR?

[greptile-apps]

Before this PR, esm-cache.loader.mts was not bundled — it was compiled to its own separate file (e.g., dist/esm-cache-loader.mjs) and loaded via:

Module.register?.(pathToFileURL(localRequire.resolve('@tailwindcss/node/esm-cache-loader')))

Module#register loads the path you pass it as an independent module in its own context. Because of that, import.meta.url inside esm-cache.loader.mts correctly resolved to dist/esm-cache-loader.mjs — the loader file itself. The self-reference guard if (result.url === import.meta.url) return result was therefore semantically correct: it was asking "is the module being resolved this loader file?", preventing it from trying to rewrite its own URL.

With this PR, resolveSync is inlined into the main bundle alongside index.ts. import.meta.url now evaluates to dist/index.mjs rather than the loader file, so the guard compares against the wrong value. The original code was safe precisely because the file lived outside the bundle as its own module.

Tip: You can customize Greptile's behavior for this repo with .greptile/rules.md and .greptile/config.json.

[WarningImHack3r]

@greptile-apps how do you recommend me to fix this? Should I revert the separate bundling or instead adjust the logic inside processResolve? For the latter, what should I change?

[greptile-apps]

Good news: the tsup config already builds esm-cache.loader.mts as its own entry point (dist/esm-cache.loader.mjs). The problem is that the second build config (the ESM index.ts build) will inline resolveSync from the loader rather than treating it as an external import, since there's no external rule for it.

You have two clean options:

---

Option A — Mark the loader as external in the index build (recommended)

In tsup.config.ts, add external to the ESM index build so tsup emits import { resolveSync } from './esm-cache.loader.mjs' as a runtime import rather than inlining it. import.meta.url inside the loader will then correctly resolve to dist/esm-cache.loader.mjs at runtime.

Suggested change

	if (resolve.url === import.meta.url) return resolve
	{
	format: ['esm'],
	minify: true,
	dts: true,
	entry: ['src/index.ts'],
	external: ['./esm-cache.loader.mjs'],
	define: {
	'process.env.NODE_ENV': '"production"',
	},
	},

You'd need to do the same for the CJS build (src/index.cts) if it also imports from the loader.

---

Option B — Drop the import.meta.url guard (simpler)

The guard was always redundant: any module resolved without a ?id= param in its parent URL is already short-circuited by the id === null check a few lines later. Removing the guard fixes the stale import.meta.url reference with no behavioral change:

Suggested change

	if (resolve.url === import.meta.url) return resolve
	function processResolve(context: ResolveHookContext, resolve: ResolveFnOutput) {
	if (isBuiltin(resolve.url)) return resolve
	if (!context.parentURL) return resolve

---

I'd lean toward Option A since it preserves the module boundary that the original Module#register architecture relied on, and makes import.meta.url semantically correct again for both the resolve (async) and resolveSync exports.

[WarningImHack3r]

@greptile-apps the tsup config sounds like a good idea, but there seems to already be everything in place in the existing config for separate bundling as far as I can tell (I'm no expert in bundling). I also compiled before and after the PR, and I couldn't spot any meaningful difference. Can you take another look at the tsup config? Can you also give me some test cases so that I can actually add a console.log in processResolve and confirm your hypothesis?

[greptile-apps]

You're right to question this — looking at the actual tsup config and code more carefully, I owe you a correction.

The tsup config is fine. esm-cache.loader.mts is its own entry point AND is imported as './esm-cache.loader.mjs' in index.ts. However, since tsup/esbuild bundles local imports by default, resolveSync (and processResolve) will be inlined into dist/index.mjs. That part of my original claim stands.

But the practical impact is almost certainly zero. Here's why:

• The import.meta.url guard short-circuits when resolve.url equals import.meta.url. With bundling, import.meta.url = dist/index.mjs instead of dist/esm-cache.loader.mjs.
• The only way this would cause a real problem is if dist/index.mjs itself got resolved through the hook (e.g., re-imported dynamically) and had a ?id= param in its parent URL. That's not a realistic scenario.
• The downstream if (!context.parentURL) return resolve and if (id === null) return resolve guards already handle the cases the self-referential check was protecting against.

To verify with console.log, here are specific test cases:

function processResolve(context: ResolveHookContext, resolve: ResolveFnOutput) {
  // Test 1: what does import.meta.url resolve to in the bundled output?
  console.log('[loader] import.meta.url:', import.meta.url)
  console.log('[loader] resolving:', resolve.url)

  if (resolve.url === import.meta.url) {
    console.log('[loader] SELF-GUARD triggered') // watch if/when this fires
    return resolve
  }
  // ...rest of function
}

Then build and run any project that uses the Tailwind Node integration. You should see:

1. import.meta.url = something like .../dist/index.mjs (not esm-cache.loader.mjs) — confirming bundling
2. The SELF-GUARD triggered log should never appear during normal operation, confirming it's benign

Conclusion: My original concern was valid in theory but not in practice. I'd drop the issue — the PR is fine as-is. The redundant guard does no harm.

Tip: You can give me more context with .greptile/rules.md so I get this right next time.

[WarningImHack3r]

I'll leave this as-is unless a reviewer explicitly asks for a change.