Enabling#
Module resolution and loading can be customized by:
- Registering a file which exports a set of asynchronous hook functions, using the
register method from node:module,
- Registering a set of synchronous hook functions using the
registerHooks method
from node:module.
The hooks can be registered before the application code is run by using the
--import or --require flag:
node --import ./register-hooks.js ./my-app.js
node --require ./register-hooks.js ./my-app.js
import { register } from 'node:module';
register('./hooks.mjs', import.meta.url);
const { register } = require('node:module');
const { pathToFileURL } = require('node:url');
register('./hooks.mjs', pathToFileURL(__filename));
import { registerHooks } from 'node:module';
registerHooks({
resolve(specifier, context, nextResolve) { },
load(url, context, nextLoad) { },
});
const { registerHooks } = require('node:module');
registerHooks({
resolve(specifier, context, nextResolve) { },
load(url, context, nextLoad) { },
});
The file passed to --import or --require can also be an export from a dependency:
node --import some-package/register ./my-app.js
node --require some-package/register ./my-app.js
Where some-package has an "exports" field defining the /register
export to map to a file that calls register(), like the following register-hooks.js
example.
Using --import or --require ensures that the hooks are registered before any
application files are imported, including the entry point of the application and for
any worker threads by default as well.
Alternatively, register() and registerHooks() can be called from the entry point,
though dynamic import() must be used for any ESM code that should be run after the hooks
are registered.
import { register } from 'node:module';
register('http-to-https', import.meta.url);
await import('./my-app.js');const { register } = require('node:module');
const { pathToFileURL } = require('node:url');
register('http-to-https', pathToFileURL(__filename));
import('./my-app.js');
Customization hooks will run for any modules loaded later than the registration
and the modules they reference via import and the built-in require.
require function created by users using module.createRequire() can only be
customized by the synchronous hooks.
In this example, we are registering the http-to-https hooks, but they will
only be available for subsequently imported modules — in this case, my-app.js
and anything it references via import or built-in require in CommonJS dependencies.
If the import('./my-app.js') had instead been a static import './my-app.js', the
app would have already been loaded before the http-to-https hooks were
registered. This due to the ES modules specification, where static imports are
evaluated from the leaves of the tree first, then back to the trunk. There can
be static imports within my-app.js, which will not be evaluated until
my-app.js is dynamically imported.
If synchronous hooks are used, both import, require and user require created
using createRequire() are supported.
import { registerHooks, createRequire } from 'node:module';
registerHooks({ });
const require = createRequire(import.meta.url);
await import('./my-app.js');
require('./my-app-2.js');const { register, registerHooks } = require('node:module');
const { pathToFileURL } = require('node:url');
registerHooks({ });
const userRequire = createRequire(__filename);
import('./my-app.js');
require('./my-app-2.js');
userRequire('./my-app-3.js');
Finally, if all you want to do is register hooks before your app runs and you
don't want to create a separate file for that purpose, you can pass a data:
URL to --import:
node --import 'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from "node:url"; register("http-to-https", pathToFileURL("./"));' ./my-app.js
Chaining#
It's possible to call register more than once:
import { register } from 'node:module';
register('./foo.mjs', import.meta.url);
register('./bar.mjs', import.meta.url);
await import('./my-app.mjs');
const { register } = require('node:module');
const { pathToFileURL } = require('node:url');
const parentURL = pathToFileURL(__filename);
register('./foo.mjs', parentURL);
register('./bar.mjs', parentURL);
import('./my-app.mjs');
In this example, the registered hooks will form chains. These chains run
last-in, first out (LIFO). If both foo.mjs and bar.mjs define a resolve
hook, they will be called like so (note the right-to-left):
node's default ← ./foo.mjs ← ./bar.mjs
(starting with ./bar.mjs, then ./foo.mjs, then the Node.js default).
The same applies to all the other hooks.
The registered hooks also affect register itself. In this example,
bar.mjs will be resolved and loaded via the hooks registered by foo.mjs
(because foo's hooks will have already been added to the chain). This allows
for things like writing hooks in non-JavaScript languages, so long as
earlier registered hooks transpile into JavaScript.
The register method cannot be called from within the module that defines the
hooks.
Chaining of registerHooks work similarly. If synchronous and asynchronous
hooks are mixed, the synchronous hooks are always run first before the asynchronous
hooks start running, that is, in the last synchronous hook being run, its next
hook includes invocation of the asynchronous hooks.
import { registerHooks } from 'node:module';
const hook1 = { };
const hook2 = { };
registerHooks(hook1);
registerHooks(hook2);
const { registerHooks } = require('node:module');
const hook1 = { };
const hook2 = { };
registerHooks(hook1);
registerHooks(hook2);
Communication with module customization hooks#
Asynchronous hooks run on a dedicated thread, separate from the main
thread that runs application code. This means mutating global variables won't
affect the other thread(s), and message channels must be used to communicate
between the threads.
The register method can be used to pass data to an initialize hook. The
data passed to the hook may include transferable objects like ports.
import { register } from 'node:module';
import { MessageChannel } from 'node:worker_threads';
const { port1, port2 } = new MessageChannel();
port1.on('message', (msg) => {
console.log(msg);
});
port1.unref();
register('./my-hooks.mjs', {
parentURL: import.meta.url,
data: { number: 1, port: port2 },
transferList: [port2],
});const { register } = require('node:module');
const { pathToFileURL } = require('node:url');
const { MessageChannel } = require('node:worker_threads');
const { port1, port2 } = new MessageChannel();
port1.on('message', (msg) => {
console.log(msg);
});
port1.unref();
register('./my-hooks.mjs', {
parentURL: pathToFileURL(__filename),
data: { number: 1, port: port2 },
transferList: [port2],
});
Synchronous module hooks are run on the same thread where the application code is
run. They can directly mutate the globals of the context accessed by the main thread.
Hooks#
Asynchronous hooks accepted by module.register()#
The register method can be used to register a module that exports a set of
hooks. The hooks are functions that are called by Node.js to customize the
module resolution and loading process. The exported functions must have specific
names and signatures, and they must be exported as named exports.
export async function initialize({ number, port }) {
}
export async function resolve(specifier, context, nextResolve) {
}
export async function load(url, context, nextLoad) {
}
Asynchronous hooks are run in a separate thread, isolated from the main thread where
application code runs. That means it is a different realm. The hooks thread
may be terminated by the main thread at any time, so do not depend on
asynchronous operations (like console.log) to complete. They are inherited into
child workers by default.
Synchronous hooks accepted by module.registerHooks()#
Added in: v22.15.0
The module.registerHooks() method accepts synchronous hook functions.
initialize() is not supported nor necessary, as the hook implementer
can simply run the initialization code directly before the call to
module.registerHooks().
function resolve(specifier, context, nextResolve) {
}
function load(url, context, nextLoad) {
}
Synchronous hooks are run in the same thread and the same realm where the modules
are loaded. Unlike the asynchronous hooks they are not inherited into child worker
threads by default, though if the hooks are registered using a file preloaded by
--import or --require, child worker threads can inherit the preloaded scripts
via process.execArgv inheritance. See the documentation of Worker for detail.
In synchronous hooks, users can expect console.log() to complete in the same way that
they expect console.log() in module code to complete.
Conventions of hooks#
Hooks are part of a chain, even if that chain consists of only one
custom (user-provided) hook and the default hook, which is always present. Hook
functions nest: each one must always return a plain object, and chaining happens
as a result of each function calling next<hookName>(), which is a reference to
the subsequent loader's hook (in LIFO order).
A hook that returns a value lacking a required property triggers an exception. A
hook that returns without calling next<hookName>() and without returning
shortCircuit: true also triggers an exception. These errors are to help
prevent unintentional breaks in the chain. Return shortCircuit: true from a
hook to signal that the chain is intentionally ending at your hook.
initialize()#
Added in: v20.6.0, v18.19.0
data <any> The data from register(loader, import.meta.url, { data }).
The initialize hook is only accepted by register. registerHooks() does
not support nor need it since initialization done for synchronous hooks can be run
directly before the call to registerHooks().
The initialize hook provides a way to define a custom function that runs in
the hooks thread when the hooks module is initialized. Initialization happens
when the hooks module is registered via register.
This hook can receive data from a register invocation, including
ports and other transferable objects. The return value of initialize can be a
<Promise>, in which case it will be awaited before the main application thread
execution resumes.
Module customization code:
export async function initialize({ number, port }) {
port.postMessage(`increment: ${number + 1}`);
}
Caller code:
import assert from 'node:assert';
import { register } from 'node:module';
import { MessageChannel } from 'node:worker_threads';
const { port1, port2 } = new MessageChannel();
port1.on('message', (msg) => {
assert.strictEqual(msg, 'increment: 2');
});
port1.unref();
register('./path-to-my-hooks.js', {
parentURL: import.meta.url,
data: { number: 1, port: port2 },
transferList: [port2],
});const assert = require('node:assert');
const { register } = require('node:module');
const { pathToFileURL } = require('node:url');
const { MessageChannel } = require('node:worker_threads');
const { port1, port2 } = new MessageChannel();
port1.on('message', (msg) => {
assert.strictEqual(msg, 'increment: 2');
});
port1.unref();
register('./path-to-my-hooks.js', {
parentURL: pathToFileURL(__filename),
data: { number: 1, port: port2 },
transferList: [port2],
});
resolve(specifier, context, nextResolve)#
specifier <string>
context <Object>
conditions <string[]> Export conditions of the relevant package.json
importAttributes <Object> An object whose key-value pairs represent the
attributes for the module to import
parentURL <string> | <undefined> The module importing this one, or undefined
if this is the Node.js entry point
nextResolve <Function> The subsequent resolve hook in the chain, or the
Node.js default resolve hook after the last user-supplied resolve hook
specifier <string>
context <Object> | <undefined> When omitted, the defaults are provided. When provided, defaults
are merged in with preference to the provided properties.
- Returns: <Object> | <Promise> The asynchronous version takes either an object containing the
following properties, or a
Promise that will resolve to such an object. The
synchronous version only accepts an object returned synchronously.
format <string> | <null> | <undefined> A hint to the load hook (it might be ignored). It can be a
module format (such as 'commonjs' or 'module') or an arbitrary value like 'css' or
'yaml'.
importAttributes <Object> | <undefined> The import attributes to use when
caching the module (optional; if excluded the input will be used)
shortCircuit <undefined> | <boolean> A signal that this hook intends to
terminate the chain of resolve hooks. Default: false
url <string> The absolute URL to which this input resolves
Warning In the case of the asynchronous version, despite support for returning
promises and async functions, calls to resolve may still block the main thread which
can impact performance.
The resolve hook chain is responsible for telling Node.js where to find and
how to cache a given import statement or expression, or require call. It can
optionally return a format (such as 'module') as a hint to the load hook. If
a format is specified, the load hook is ultimately responsible for providing
the final format value (and it is free to ignore the hint provided by
resolve); if resolve provides a format, a custom load hook is required
even if only to pass the value to the Node.js default load hook.
Import type attributes are part of the cache key for saving loaded modules into
the internal module cache. The resolve hook is responsible for returning an
importAttributes object if the module should be cached with different
attributes than were present in the source code.
The conditions property in context is an array of conditions that will be used
to match package exports conditions for this resolution
request. They can be used for looking up conditional mappings elsewhere or to
modify the list when calling the default resolution logic.
The current package exports conditions are always in
the context.conditions array passed into the hook. To guarantee default
Node.js module specifier resolution behavior when calling defaultResolve, the
context.conditions array passed to it must include all elements of the
context.conditions array originally passed into the resolve hook.
export async function resolve(specifier, context, nextResolve) {
const { parentURL = null } = context;
if (Math.random() > 0.5) {
return {
shortCircuit: true,
url: parentURL ?
new URL(specifier, parentURL).href :
new URL(specifier).href,
};
}
if (Math.random() < 0.5) {
return nextResolve(specifier, {
...context,
conditions: [...context.conditions, 'another-condition'],
});
}
return nextResolve(specifier);
}
function resolve(specifier, context, nextResolve) {
}
load(url, context, nextLoad)#
url <string> The URL returned by the resolve chain
context <Object>
conditions <string[]> Export conditions of the relevant package.json
format <string> | <null> | <undefined> The format optionally supplied by the
resolve hook chain. This can be any string value as an input; input values do not need to
conform to the list of acceptable return values described below.
importAttributes <Object>
nextLoad <Function> The subsequent load hook in the chain, or the
Node.js default load hook after the last user-supplied load hook
url <string>
context <Object> | <undefined> When omitted, defaults are provided. When provided, defaults are
merged in with preference to the provided properties. In the default nextLoad, if
the module pointed to by url does not have explicit module type information,
context.format is mandatory.
- Returns: <Object> | <Promise> The asynchronous version takes either an object containing the
following properties, or a
Promise that will resolve to such an object. The
synchronous version only accepts an object returned synchronously.
The load hook provides a way to define a custom method of determining how a
URL should be interpreted, retrieved, and parsed. It is also in charge of
validating the import attributes.
The final value of format must be one of the following:
The value of source is ignored for type 'builtin' because currently it is
not possible to replace the value of a Node.js builtin (core) module.
Caveat in the asynchronous load hook#
When using the asynchronous load hook, omitting vs providing a source for
'commonjs' has very different effects:
- When a
source is provided, all require calls from this module will be
processed by the ESM loader with registered resolve and load hooks; all
require.resolve calls from this module will be processed by the ESM loader
with registered resolve hooks; 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.
- If
source is undefined or null, it will be handled by the CommonJS module
loader and require/require.resolve calls will not go through the
registered hooks. This behavior for nullish source is temporary — in the
future, nullish source will not be supported.
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, and require/require.resolve always go through the registered
hooks.
When node is run with --experimental-default-type=commonjs, the Node.js
internal asynchronous load implementation, which is the value of next for the
last hook in the load chain, returns null for source when format is
'commonjs' for backward compatibility. Here is an example hook that would
opt-in to using the non-default behavior:
import { readFile } from 'node:fs/promises';
export async function load(url, context, nextLoad) {
const result = await nextLoad(url, context);
if (result.format === 'commonjs') {
result.source ??= await readFile(new URL(result.responseURL ?? url));
}
return result;
}
This doesn't apply to the synchronous load hook either, in which case the
source returned contains source code loaded by the next hook, regardless
of module format.
Warning: The asynchronous load hook and namespaced exports from CommonJS
modules are incompatible. Attempting to use them together will result in an empty
object from the import. This may be addressed in the future. This does not apply
to the synchronous load hook, in which case exports can be used as usual.
These types all correspond to classes defined in ECMAScript.
If the source value of a text-based format (i.e., 'json', 'module')
is not a string, it is converted to a string using util.TextDecoder.
The load hook provides a way to define a custom method for retrieving the
source code of a resolved URL. This would allow a loader to potentially avoid
reading files from disk. It could also be used to map an unrecognized format to
a supported one, for example yaml to module.
export async function load(url, context, nextLoad) {
const { format } = context;
if (Math.random() > 0.5) {
return {
format,
shortCircuit: true,
source: '...',
};
}
return nextLoad(url);
}
function load(url, context, nextLoad) {
}
In a more advanced scenario, this can also be used to transform an unsupported
source to a supported one (see Examples below).
Examples#
The various module customization hooks can be used together to accomplish
wide-ranging customizations of the Node.js code loading and evaluation
behaviors.
Import from HTTPS#
The hook below registers hooks to enable rudimentary support for such
specifiers. While this may seem like a significant improvement to Node.js core
functionality, there are substantial downsides to actually using these hooks:
performance is much slower than loading files from disk, there is no caching,
and there is no security.
import { get } from 'node:https';
export function load(url, context, nextLoad) {
if (url.startsWith('https://')) {
return new Promise((resolve, reject) => {
get(url, (res) => {
let data = '';
res.setEncoding('utf8');
res.on('data', (chunk) => data += chunk);
res.on('end', () => resolve({
format: 'module',
shortCircuit: true,
source: data,
}));
}).on('error', (err) => reject(err));
});
}
return nextLoad(url);
}
import { VERSION } from 'https://coffeescript.org/browser-compiler-modern/coffeescript.js';
console.log(VERSION);
With the preceding hooks module, running
node --import 'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from "node:url"; register(pathToFileURL("./https-hooks.mjs"));' ./main.mjs
prints the current version of CoffeeScript per the module at the URL in
main.mjs.
Transpilation#
Sources that are in formats Node.js doesn't understand can be converted into
JavaScript using the load hook.
This is less performant than transpiling source files before running Node.js;
transpiler hooks should only be used for development and testing purposes.
Asynchronous version#
import { readFile } from 'node:fs/promises';
import { findPackageJSON } from 'node:module';
import coffeescript from 'coffeescript';
const extensionsRegex = /\.(coffee|litcoffee|coffee\.md)$/;
export async function load(url, context, nextLoad) {
if (extensionsRegex.test(url)) {
const { source: rawSource } = await nextLoad(url, { ...context, format: 'coffee' });
const transformedSource = coffeescript.compile(rawSource.toString(), url);
return {
format: await getPackageType(url),
shortCircuit: true,
source: transformedSource,
};
}
return nextLoad(url, context);
}
async function getPackageType(url) {
const pJson = findPackageJSON(url);
return readFile(pJson, 'utf8')
.then(JSON.parse)
.then((json) => json?.type)
.catch(() => undefined);
}
Synchronous version#
import { readFileSync } from 'node:fs';
import { registerHooks, findPackageJSON } from 'node:module';
import coffeescript from 'coffeescript';
const extensionsRegex = /\.(coffee|litcoffee|coffee\.md)$/;
function load(url, context, nextLoad) {
if (extensionsRegex.test(url)) {
const { source: rawSource } = nextLoad(url, { ...context, format: 'coffee' });
const transformedSource = coffeescript.compile(rawSource.toString(), url);
return {
format: getPackageType(url),
shortCircuit: true,
source: transformedSource,
};
}
return nextLoad(url, context);
}
function getPackageType(url) {
const pJson = findPackageJSON(url);
if (!pJson) {
return undefined;
}
try {
const file = readFileSync(pJson, 'utf-8');
return JSON.parse(file)?.type;
} catch {
return undefined;
}
}
registerHooks({ load });
Running hooks#
import { scream } from './scream.coffee'
console.log scream 'hello, world'
import { version } from 'node:process'
console.log "Brought to you by Node.js version #{version}"
export scream = (str) -> str.toUpperCase()
For the sake of running the example, add a package.json file containing the
module type of the CoffeeScript files.
{
"type": "module"
}
This is only for running the example. In real world loaders, getPackageType() must be
able to return an format known to Node.js even in the absence of an explicit type in a
package.json, or otherwise the nextLoad call would throw ERR_UNKNOWN_FILE_EXTENSION
(if undefined) or ERR_UNKNOWN_MODULE_FORMAT (if it's not a known format listed in
the load hook documentation).
With the preceding hooks modules, running
node --import 'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from "node:url"; register(pathToFileURL("./coffeescript-hooks.mjs"));' ./main.coffee
or node --import ./coffeescript-sync-hooks.mjs ./main.coffee
causes main.coffee to be turned into JavaScript after its source code is
loaded from disk but before Node.js executes it; and so on for any .coffee,
.litcoffee or .coffee.md files referenced via import statements of any
loaded file.
Import maps#
The previous two examples defined load hooks. This is an example of a
resolve hook. This hooks module reads an import-map.json file that defines
which specifiers to override to other URLs (this is a very simplistic
implementation of a small subset of the "import maps" specification).
Asynchronous version#
import fs from 'node:fs/promises';
const { imports } = JSON.parse(await fs.readFile('import-map.json'));
export async function resolve(specifier, context, nextResolve) {
if (Object.hasOwn(imports, specifier)) {
return nextResolve(imports[specifier], context);
}
return nextResolve(specifier, context);
}
Synchronous version#
import fs from 'node:fs/promises';
import module from 'node:module';
const { imports } = JSON.parse(fs.readFileSync('import-map.json', 'utf-8'));
function resolve(specifier, context, nextResolve) {
if (Object.hasOwn(imports, specifier)) {
return nextResolve(imports[specifier], context);
}
return nextResolve(specifier, context);
}
module.registerHooks({ resolve });
Using the hooks#
With these files:
import 'a-module';
{
"imports": {
"a-module": "./some-module.js"
}
}
console.log('some module!');
Running node --import 'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from "node:url"; register(pathToFileURL("./import-map-hooks.js"));' main.js
or node --import ./import-map-sync-hooks.js main.js
should print some module!.