Unexpected behavior in module customization hooks / loader, for require

It seems I am one of the early adopters of module hooks.
I liked the idea of the module customization hooks, and tried to use it in my project.
However, I believe the current behavior of require handling in the esm loader is buggy.

Relevant source code, here

node/lib/internal/modules/esm/translators.js

Lines 130 to 159 in 69f8794

    
           const requireFn = function require(specifier) { 
        
             let importAttributes = kEmptyObject; 
        
             if (!StringPrototypeStartsWith(specifier, 'node:') && !BuiltinModule.normalizeRequirableId(specifier)) { 
        
               // TODO: do not depend on the monkey-patchable CJS loader here. 
        
               const path = CJSModule._resolveFilename(specifier, module); 
        
               switch (extname(path)) { 
        
                 case '.json': 
        
                   importAttributes = { __proto__: null, type: 'json' }; 
        
                   break; 
        
                 case '.node': 
        
                   return wrapModuleLoad(specifier, module); 
        
                 default: 
        
                     // fall through 
        
               } 
        
               specifier = `${pathToFileURL(path)}`; 
        
             } 
        
             const job = cascadedLoader.getModuleJobForRequireInImportedCJS(specifier, url, importAttributes); 
        
             job.runSync(); 
        
             return cjsCache.get(job.url).exports; 
        
           }; 
        
           setOwnProperty(requireFn, 'resolve', function resolve(specifier) { 
        
             if (!StringPrototypeStartsWith(specifier, 'node:')) { 
        
               const path = CJSModule._resolveFilename(specifier, module); 
        
               if (specifier !== path) { 
        
                 specifier = `${pathToFileURL(path)}`; 
        
               } 
        
             } 
        
             const { url: resolvedURL } = cascadedLoader.resolveSync(specifier, url, kEmptyObject); 
        
             return urlToFilename(resolvedURL); 
        
           });

The resolving of the specifier is done in the main thread, using Module._resolveFilename, before being sent to the customization hooks.
The resolver hook is then receiving a resolved file:// URL, instead of the real specifier.

These are not expected according to the documentation of the module customization hooks.
And for my use case, it has made the hooks useless.

To make it clear there are two bugs:

The cjs specifiers are being resolved in the wrong thread.
The hooks, therefore, cannot really work, because if the "expected" file does not really exist on the hard drive. The cjs Module._resolveFilename will throw an error in the first place.
The resolve hook is receiving a wrong specifier, if the first bug would not trigger.

The root of this issue might be the default resolver in customization hooks does not support resolving CJS modules.
An easy fix would be to move the Module._resolveFilename into the default resolver.
The loading of .node native add-ons may also get in the way.
But IMO it should also go through the hooks, and eventually be loaded as {type: 'commonjs', source: undefined, url: 'file://... .node'}

Maybe I should mention my use case here:

I'm trying to use the module hooks/loader with SEA, to distribute my project, in 1+n files.
Where the node.js binary will be injected with a custom hook/loader, and then load and run code in one or more ASAR archives.

This requires the hooks to resolve and load paths that do not really exist on the hard drive.

@nodejs/loaders

I feel that the approach taken in #47999 is just broken and we should just go back to using Module._load to load import(cjs) instead of trying to re-invent a ESM-loader specific require and require.resolve. That approach just cannot cover all the corner cases and there will always be some holes (like what's mentioned in this issue, and random createRequire(), and the re-exports detection for the cjs-module-lexer). Going back means module.register() will not work for CJS, but then if it's already having all these edge cases in CJS, it's not really reliable anyway, and at least by going back we can make sure module.registerHooks() is always reliable.

@joyeecheung

@joyeecheung I generally liked the idea of having a dedicated loader thread.

I agree with you about reusing cjs loader code, but not Module._load directly. I believe the resolving can happen in the loader thread and module.register() can still work. It's just the code loading part, that needs to be left in the caller thread, similar to how internal modules work.

Mixing the cjs and module loader is probably inevitable because cjs and es modules may load each other in user code.

For this specific issue, it's just a bug-level thing, no need to overturn the whole approach.

For context the overturn has already been discussed before: I even have to push back against deprecating or just removing module.register() now when I was adding module.registerHooks() because the off-thread approach have many bugs and edge cases that have not been fixed and there's generally a lack of interest in fixing them. But I was just not in favor in removing the async hooks immediately due to not wanting to disrupt existing usage, not that I think it's a path worth pursuing further (I for one, am not interested in fixing the off-thread code because it just doesn't fit well internally IMO, and provides no good story for CJS monkey patching migration. I would not oppose against others trying to fix it, but you can probably see a lack of interest in fixing it from the radio silence of this issue).

module: do not invoke resolve hooks twice for imported cjs

FWIW if you use module.registerHooks now, resolve hooks will only get invoked once with the specifier if you do not propagate it to the default next steps in your hook i.e. it will not read from the file system if you override early. For module.register this would be much harder given its off-thread design (for example, if Module._resolveFilename gets invoked in the loader thread, it could only work with the cache in the loader thread, which could then lead to a mismatch with the cache in the main thread, which is accessible by users from Module._cache and widely relied upon by various popular packages), and I am not sure if anyone is invested in trying to fix that harder problem...

module: do not invoke resolve hooks twice for imported cjs

Not sure if this is the right issue to report on, or if this effort is already being tracked elsewhere, but I think I ran into this (or something very similar?) when trying out https://github.com/platformatic/vfs, but it seems to be a core bug in Module.registerHooks (not just the "async off thread" version).

Basically, after importing a module which goes through Module.registerHooks, no nested imports or requires branched from that module end up going through the hooks.

e.g

VFS
->  import("virtual-file-1.js")
  # the require or import of this inner dep doesn't go through the `registerHooks`
  ->    require / import("virtual-dep-1.js")

If you use require at the top level, and all the way down, it works fine.

Minimal reproduction (tested on latest node 25 and node 24):

import module, { createRequire } from "node:module";

const require = createRequire(import.meta.url);

const VIRTUAL_MODULES = new Map([
  ["virtual:shared", `module.exports.greet = (name) => "hello " + name;`],
  [
    "virtual:entry",
    `const { greet } = require("virtual:shared");\nmodule.exports.default = greet("world");`,
  ],
]);

// Register hooks that resolve and load "virtual:" specifiers entirely in-memory.
module.registerHooks({
  resolve(specifier, context, nextResolve) {
    if (specifier.startsWith("virtual:")) {
      console.log(`  [resolve hook] ${specifier}`);
      return { url: specifier, format: "commonjs", shortCircuit: true };
    }
    return nextResolve(specifier, context);
  },
  load(url, context, nextLoad) {
    if (url.startsWith("virtual:")) {
      console.log(`  [load hook]    ${url}`);
      return { format: "commonjs", source: VIRTUAL_MODULES.get(url), shortCircuit: true };
    }
    return nextLoad(url, context);
  },
});

function clearCache() {
  for (const key of Object.keys(require.cache)) {
    if (key.startsWith("virtual:")) delete require.cache[key];
  }
}

async function run(label, loadFn) {
  try {
    clearCache();
    console.log(`[${label}]  OK:`, await loadFn());
  } catch (e) {
    console.error(`[${label}]  FAIL:`, e.message.split("\n")[0]);
  }
}

console.log("=== require(virtual:entry) ===");
await run("require", () => require("virtual:entry").default);

console.log("\n=== import(virtual:entry) ===");
await run("import ", async () => (await import("virtual:entry")).default);

Output:

$ node register-hooks-repro.mjs
=== require(virtual:entry) ===
  [resolve hook] virtual:entry
  [load hook]    virtual:entry
  [resolve hook] virtual:shared
  [load hook]    virtual:shared
[require]  OK: hello world

=== import(virtual:entry) ===
  [resolve hook] virtual:entry
  [load hook]    virtual:entry
[import ]  FAIL: Cannot find module 'virtual:shared'

@johnpyp

@johnpyp I think it's a different issue i.e. for virtual resolution, we currently still have to call Module._resolveFilename again for compatbility if it's imported CJS - this is why you don't see it reproduced when you try to load the entrypoint with require, it's an "imported CJS" issue. Can you open a separate issue for this?

module: do not invoke resolve hooks twice for imported cjs

This issue has been marked as stale due to 90 days of inactivity.
It will be automatically closed in 30 days if no further activity occurs. If this is still relevant, please leave a comment or update it to keep it open.

This issue has been automatically closed after 30 days of inactivity following its stale status (no activity for a total of 120 days).
If this is still relevant, feel free to reopen it or leave a comment with additional details so we can continue the discussion.

Navigation Menu

Repository navigation

Unexpected behavior in module customization hooks / loader, for `require` #55808

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	const requireFn = function require(specifier) {
	let importAttributes = kEmptyObject;
	if (!StringPrototypeStartsWith(specifier, 'node:') && !BuiltinModule.normalizeRequirableId(specifier)) {
	// TODO: do not depend on the monkey-patchable CJS loader here.
	const path = CJSModule._resolveFilename(specifier, module);
	switch (extname(path)) {
	case '.json':
	importAttributes = { __proto__: null, type: 'json' };
	break;
	case '.node':
	return wrapModuleLoad(specifier, module);
	default:
	// fall through
	}
	specifier = `${pathToFileURL(path)}`;
	}
	const job = cascadedLoader.getModuleJobForRequireInImportedCJS(specifier, url, importAttributes);
	job.runSync();
	return cjsCache.get(job.url).exports;
	};
	setOwnProperty(requireFn, 'resolve', function resolve(specifier) {
	if (!StringPrototypeStartsWith(specifier, 'node:')) {
	const path = CJSModule._resolveFilename(specifier, module);
	if (specifier !== path) {
	specifier = `${pathToFileURL(path)}`;
	}
	}
	const { url: resolvedURL } = cascadedLoader.resolveSync(specifier, url, kEmptyObject);
	return urlToFilename(resolvedURL);
	});

Unexpected behavior in module customization hooks / loader, for require #55808

Description

Activity

nomagick commented on Nov 10, 2024

GeoffreyBooth commented on Nov 16, 2024

joyeecheung commented on Jan 24, 2025

nomagick commented on Jan 27, 2025

joyeecheung commented on Jan 27, 2025

joyeecheung commented on Feb 8, 2026

johnpyp commented on Apr 12, 2026

joyeecheung commented on Apr 15, 2026

github-actions commented on Jul 20, 2026

github-actions commented on Aug 20, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Unexpected behavior in module customization hooks / loader, for `require` #55808