Skip to content
Tutorials Center
My learning

Topics

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.

NODE
import { register } from 'node:module';

register('./my-hooks.mjs', import.meta.url);

Try it

Node.js A virtual module made with a load hook

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.

Node.js Aliases and initialize data

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

NODE
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 with node --import ./setup.mjs app.mjs (read-only here).
  • Separate thread, separate state. Hook code cannot touch your main-thread variables. Pass configuration through data and initialize(), or a MessagePort in transferList.
  • Hooks chain. Several register() calls form a chain, last registered runs first. Always call nextResolve/nextLoad unless you intend to finish the job yourself.
  • Keep them fast. Every resolved specifier in the program passes through the hooks.
  • format matters in load. Values include 'module', 'commonjs', 'json' and 'wasm'. For 'commonjs' you may omit source, 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 at module.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.