Node.js Reference ยท Module Systems
Node.js module.register() method
Reference for module.register() in Node.js: register resolve and load hooks that run off-thread to rewrite specifiers, virtual modules and file loading.
module.register() installs module customization hooks. A hooks module exports resolve and load functions (and optionally initialize) that Node calls whenever an import or require resolves a specifier or loads source text. With them you can add virtual modules, map aliases, load unusual file types or transpile on the fly.
The hooks module runs on a separate thread, so it cannot see your program's variables and a slow hook does not block your code directly. Node 24 also offers synchronous in-thread hooks through module.registerHooks(), which suit CommonJS require.
import { register } from 'node:module'; register('./my-hooks.mjs', import.meta.url);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
import { register } from 'node:module'; register(specifier: string | URL, parentURL?: string | URL, options?: { parentURL?: string | URL, data?: any, transferList?: object[] }): void // Hooks module exports initialize?(data): void | Promise<void> resolve(specifier, context, nextResolve): { url, format?, importAttributes?, shortCircuit? } load(url, context, nextLoad): { format, source, shortCircuit? }
| Name | Description |
|---|---|
specifier |
The hooks module to load: a relative path, a package name or a data: URL. |
parentURL |
Base to resolve specifier against. Use import.meta.url. Defaults to data:, which only works for absolute specifiers. |
options.data |
Value passed to the hooks module's initialize(). Copied with structured clone. |
options.transferList |
Transferable objects (such as a MessagePort) to hand over with data. |
nextResolve / nextLoad |
Call the next hook in the chain (the default behavior comes last). |
shortCircuit |
Must be true when a hook does not call the next one. Otherwise Node throws ERR_LOADER_CHAIN_INCOMPLETE. |
Returns: nothing. Hooks are active for every later import() and for require() calls that go through the ES loader, from the moment register() returns.
Errors: a hook that returns the wrong shape, or forgets shortCircuit, causes ERR_INVALID_RETURN_PROPERTY_VALUE or ERR_LOADER_CHAIN_INCOMPLETE. A specifier no hook can resolve produces ERR_MODULE_NOT_FOUND.
Usage notes
- Hooks apply only to later loads. Modules already loaded, including the file that called
register(), are not affected. Register in a tiny setup file and load it withnode --import ./setup.mjs app.mjs(read-only here). - Separate thread, separate state. Hook code cannot touch your main-thread variables. Pass configuration through
dataandinitialize(), or aMessagePortintransferList. - Hooks chain. Several
register()calls form a chain, last registered runs first. Always callnextResolve/nextLoadunless you intend to finish the job yourself. - Keep them fast. Every resolved specifier in the program passes through the hooks.
formatmatters inload. Values include'module','commonjs','json'and'wasm'. For'commonjs'you may omitsource, and Node reads the file itself.- Status. The asynchronous, off-thread API is in active development and its details have changed between versions. For synchronous needs, or to affect
require()directly, look atmodule.registerHooks(), which runs on the main thread. - Not a security boundary. Hooks see and may rewrite everything that loads afterwards, so only register code you trust.