CJS module customized by synchronous customization hooks uses synthetic `require` with any use of `--loader`

[clemyan]

Version

All versions 24.12.0 ~ 24.15.0 and 25.2.0 ~ 25.9.0

Platform

Linux 6.6.87.2-microsoft-standard-WSL2 #1 SMP PREEMPT_DYNAMIC Thu Jun  5 18:30:46 UTC 2025 x86_64 GNU/Linux

Subsystem

module

What steps will reproduce the bug?

// hook.cjs
require('module').registerHooks({
  load(url, context, next) {
    return url.endsWith('entry.js') ? {
      source: 'console.log("intercepted", require.cache)',
      format: 'commonjs',
      shortCircuit: true
    } : next(url, context)
  }
})

plus empty files empty.mjs and entry.js

$ node --no-warnings -r ./hooks.cjs --loader ./empty.mjs ./entry.js

How often does it reproduce? Is there a required condition?

Always

What is the expected behavior? Why is that the expected behavior?

Logs:

1. intercepted, showing the loading of entry.js was customized by the synchronous load hook
2. The require.cache object

The docs mention, in part, under "Asynchronous load(url, context, nextLoad)":

When a source is provided, [...] only a subset of the CommonJS API will be available (e.g. no require.extensions, no require.cache, no require.resolve.paths) and monkey-patching on the CommonJS module loader will not apply.
These caveats do not apply to the synchronous load hook, in which case the complete set of CommonJS APIs available to the customized CommonJS modules

This is, as far as I can tell, the only mention of this "synthetic require" behavior. And it should not apply to this case as the module is only customized by a synchronous load hook. There are no asynchronous customization hooks registered.

What do you see instead?

Logs: intercepted undefined

This shows entry.js is using the synthetic require, despite what the docs say.

The mere use of the --loader flag triggers this, even when using empty file as a loader (so no asynchronous customization hooks are registered). Using module.register to register a loader file behaves the same as the --loader flag. The only way to avoid the synthetic require behvaior is to not use --loader or module.register at all.

Additional information

For a few weeks now I have been trying to migrate Yarn to synchronous customization hooks in response to #62012. The current stopgap we introduced in Yarn 4.14.0 falls into the documented caveats of "synthetic require" mentioned above. See #62012 (comment)

The issue reported here means that to properly fix to #62012 on our end, we can't just move module loading via our fs patch layer to synchronous hooks. Instead we must do an all-or-nothing migration from --loader into module.registerHooks.