Registration of synchronous customization hooks#

To register synchronous customization hooks, usemodule.registerHooks(), whichtakessynchronous hook functions directly in-line.

// register-hooks.jsimport { registerHooks }from'node:module';registerHooks({resolve(specifier, context, nextResolve) {/* implementation */ },load(url, context, nextLoad) {/* implementation */ },});// register-hooks.jsconst { registerHooks } =require('node:module');registerHooks({resolve(specifier, context, nextResolve) {/* implementation */ },load(url, context, nextLoad) {/* implementation */ },});copy

node --import ./register-hooks.js ./my-app.jsnode --require ./register-hooks.js ./my-app.jscopy

node --import some-package/register ./my-app.jsnode --require some-package/register ./my-app.jscopy

import { registerHooks }from'node:module';registerHooks({/* implementation of synchronous hooks */ });// If loaded using static import, the hooks would not be applied when loading// my-app.mjs, because statically imported modules are all executed before its// importer regardless of where the static import appears.// import './my-app.mjs';// my-app.mjs must be loaded dynamically to ensure the hooks are applied.awaitimport('./my-app.mjs');const { registerHooks } =require('node:module');registerHooks({/* implementation of synchronous hooks */ });import('./my-app.mjs');// Or, if my-app.mjs does not have top-level await or it's a CommonJS module,// require() can also be used:// require('./my-app.mjs');copy

node --import'data:text/javascript,import {registerHooks} from "node:module"; registerHooks(/* hooks code */);' ./my-app.jscopy

Convention of hooks and chaining#

Hooks are part of a chain, even if that chain consists of only onecustom (user-provided) hook and the default hook, which is always present.

Hook functions nest: each one must always return a plain object, and chaining happensas a result of each function callingnext<hookName>(), which is a reference tothe subsequent loader's hook (in LIFO order).

It's possible to callregisterHooks() more than once:

// entrypoint.mjsimport { registerHooks }from'node:module';const hook1 = {/* implementation of hooks */ };const hook2 = {/* implementation of hooks */ };// hook2 runs before hook1.registerHooks(hook1);registerHooks(hook2);// entrypoint.cjsconst { registerHooks } =require('node:module');const hook1 = {/* implementation of hooks */ };const hook2 = {/* implementation of hooks */ };// hook2 runs before hook1.registerHooks(hook1);registerHooks(hook2);copy

In this example, the registered hooks will form chains. These chains runlast-in, first-out (LIFO). If bothhook1 andhook2 define aresolvehook, they will be called like so (note the right-to-left,starting withhook2.resolve, thenhook1.resolve, then the Node.js default):

Node.js defaultresolve ←hook1.resolve ←hook2.resolve

The same applies to all the other hooks.

A hook that returns a value lacking a required property triggers an exception. Ahook that returns without callingnext<hookName>()and without returningshortCircuit: true also triggers an exception. These errors are to helpprevent unintentional breaks in the chain. ReturnshortCircuit: true from ahook to signal that the chain is intentionally ending at your hook.

If a hook should be applied when loading other hook modules, the other hookmodules should be loaded after the hook is registered.

Hook functions accepted bymodule.registerHooks()#

Themodule.registerHooks() method accepts the following synchronous hook functions.

functionresolve(specifier, context, nextResolve) {// Take an `import` or `require` specifier and resolve it to a URL.}functionload(url, context, nextLoad) {// Take a resolved URL and return the source code to be evaluated.}copy

Synchronous hooks are run in the same thread and the samerealm where the modulesare loaded, the code in the hook function can pass values to the modules being referenceddirectly via global variables or other shared states.

Unlike the asynchronous hooks, the synchronous hooks are not inherited into child workerthreads by default, though if the hooks are registered using a file preloaded by--import or--require, child worker threads can inherit the preloaded scriptsviaprocess.execArgv inheritance. Seethe documentation ofWorker for details.

Synchronousresolve(specifier, context, nextResolve)#

• specifier<string>
• context<Object>
  • conditions<string[]> Export conditions of the relevantpackage.json
  • importAttributes<Object> An object whose key-value pairs represent theattributes for the module to import
  • parentURL<string> |<undefined> The module importing this one, or undefinedif this is the Node.js entry point
• nextResolve<Function> The subsequentresolve hook in the chain, or theNode.js defaultresolve hook after the last user-suppliedresolve hook
  • specifier<string>
  • context<Object> |<undefined> When omitted, the defaults are provided. When provided, defaultsare merged in with preference to the provided properties.
• Returns:<Object>
  • format<string> |<null> |<undefined> A hint to theload hook (it might be ignored). It can be amodule format (such as'commonjs' or'module') or an arbitrary value like'css' or'yaml'.
  • importAttributes<Object> |<undefined> The import attributes to use whencaching the module (optional; if excluded the input will be used)
  • shortCircuit<undefined> |<boolean> A signal that this hook intends toterminate the chain ofresolve hooks.Default:false
  • url<string> The absolute URL to which this input resolves

Theresolve hook chain is responsible for telling Node.js where to find andhow to cache a givenimport statement or expression, orrequire call. It canoptionally return a format (such as'module') as a hint to theload hook. Ifa format is specified, theload hook is ultimately responsible for providingthe finalformat value (and it is free to ignore the hint provided byresolve); ifresolve provides aformat, a customload hook is requiredeven if only to pass the value to the Node.js defaultload hook.

Import type attributes are part of the cache key for saving loaded modules intothe internal module cache. Theresolve hook is responsible for returning animportAttributes object if the module should be cached with differentattributes than were present in the source code.

Theconditions property incontext is an array of conditions that will be usedto matchpackage exports conditions for this resolutionrequest. They can be used for looking up conditional mappings elsewhere or tomodify the list when calling the default resolution logic.

The currentpackage exports conditions are always inthecontext.conditions array passed into the hook. To guaranteedefaultNode.js module specifier resolution behavior when callingdefaultResolve, thecontext.conditions array passed to itmust includeall elements of thecontext.conditions array originally passed into theresolve hook.

import { registerHooks }from'node:module';functionresolve(specifier, context, nextResolve) {// When calling `defaultResolve`, the arguments can be modified. For example,// to change the specifier or to add applicable export conditions.if (specifier.includes('foo')) {    specifier = specifier.replace('foo','bar');returnnextResolve(specifier, {      ...context,conditions: [...context.conditions,'another-condition'],    });  }// The hook can also skip default resolution and provide a custom URL.if (specifier ==='special-module') {return {url:'file:///path/to/special-module.mjs',format:'module',shortCircuit:true,// This is mandatory if nextResolve() is not called.    };  }// If no customization is needed, defer to the next hook in the chain which would be the// Node.js default resolve if this is the last user-specified loader.returnnextResolve(specifier);}registerHooks({ resolve });copy

Synchronousload(url, context, nextLoad)#

• url<string> The URL returned by theresolve chain
• context<Object>
  • conditions<string[]> Export conditions of the relevantpackage.json
  • format<string> |<null> |<undefined> The format optionally supplied by theresolve hook chain. This can be any string value as an input; input values do not need toconform to the list of acceptable return values described below.
  • importAttributes<Object>
• nextLoad<Function> The subsequentload hook in the chain, or theNode.js defaultload hook after the last user-suppliedload hook
  • url<string>
  • context<Object> |<undefined> When omitted, defaults are provided. When provided, defaults aremerged in with preference to the provided properties. In the defaultnextLoad, ifthe module pointed to byurl does not have explicit module type information,context.format is mandatory.
• Returns:<Object>
  • format<string> One of the acceptable module formats listedbelow.
  • shortCircuit<undefined> |<boolean> A signal that this hook intends toterminate the chain ofload hooks.Default:false
  • source<string> |<ArrayBuffer> |<TypedArray> The source for Node.js to evaluate

Theload hook provides a way to define a custom method for retrieving thesource code of a resolved URL. This would allow a loader to potentially avoidreading files from disk. It could also be used to map an unrecognized format toa supported one, for exampleyaml tomodule.

import { registerHooks }from'node:module';import {Buffer }from'node:buffer';functionload(url, context, nextLoad) {// The hook can skip default loading and provide a custom source code.if (url ==='special-module') {return {source:'export const special = 42;',format:'module',shortCircuit:true,// This is mandatory if nextLoad() is not called.    };  }// It's possible to modify the source code loaded by the next - possibly default - step,// for example, replacing 'foo' with 'bar' in the source code of the module.const result =nextLoad(url, context);const source =typeof result.source ==='string' ?    result.source :Buffer.from(result.source).toString('utf8');return {source: source.replace(/foo/g,'bar'),    ...result,  };}registerHooks({ resolve });copy

In a more advanced scenario, this can also be used to transform an unsupportedsource to a supported one (seeExamples below).

Caveats of asynchronous customization hooks#

The asynchronous customization hooks have many caveats and it is uncertain if theirissues can be resolved. Users are encouraged to use the synchronous customization hooksviamodule.registerHooks() instead to avoid these caveats.

• Asynchronous hooks run on a separate thread, so the hook functions cannot directlymutate the global state of the modules being customized. It's typical to use messagechannels and atomics to pass data between the two or to affect control flows.SeeCommunication with asynchronous module customization hooks.
• Asynchronous hooks do not affect allrequire() calls in the module graph.
  • Customrequire functions created usingmodule.createRequire() are notaffected.
  • If the asynchronousload hook does not override thesource for CommonJS modulesthat go through it, the child modules loaded by those CommonJS modules via built-inrequire() would not be affected by the asynchronous hooks either.
• There are several caveats that the asynchronous hooks need to handle whencustomizing CommonJS modules. Seeasynchronousresolve hook andasynchronousload hook for details.
• Whenrequire() calls inside CommonJS modules are customized by asynchronous hooks,Node.js may need to load the source code of the CommonJS module multiple times to maintaincompatibility with existing CommonJS monkey-patching. If the module code changes betweenloads, this may lead to unexpected behaviors.
  • As a side effect, if both asynchronous hooks and synchronous hooks are registered and theasynchronous hooks choose to customize the CommonJS module, the synchronous hooks may beinvoked multiple times for therequire() calls in that CommonJS module.

Registration of asynchronous customization hooks#

Asynchronous customization hooks are registered usingmodule.register() which takesa path or URL to another module that exports theasynchronous hook functions.

Similar toregisterHooks(),register() can be called in a module preloaded by--import or--require, or called directly within the entry point.

// Use module.register() to register asynchronous hooks in a dedicated thread.import { register }from'node:module';register('./hooks.mjs',import.meta.url);// If my-app.mjs is loaded statically here as `import './my-app.mjs'`, since ESM// dependencies are evaluated before the module that imports them,// it's loaded _before_ the hooks are registered above and won't be affected.// To ensure the hooks are applied, dynamic import() must be used to load ESM// after the hooks are registered.import('./my-app.mjs');const { register } =require('node:module');const { pathToFileURL } =require('node:url');// Use module.register() to register asynchronous hooks in a dedicated thread.register('./hooks.mjs',pathToFileURL(__filename));import('./my-app.mjs');copy

Inhooks.mjs:

// hooks.mjsexportasyncfunctionresolve(specifier, context, nextResolve) {/* implementation */}exportasyncfunctionload(url, context, nextLoad) {/* implementation */}copy

Unlike synchronous hooks, the asynchronous hooks would not run for these modules loaded in the filethat callsregister():

// register-hooks.jsimport { register, createRequire }from'node:module';register('./hooks.mjs',import.meta.url);// Asynchronous hooks does not affect modules loaded via custom require()// functions created by module.createRequire().const userRequire =createRequire(__filename);userRequire('./my-app-2.cjs');// Hooks won't affect thiscopy

// register-hooks.jsconst { register, createRequire } =require('node:module');const { pathToFileURL } =require('node:url');register('./hooks.mjs',pathToFileURL(__filename));// Asynchronous hooks does not affect modules loaded via built-in require()// in the module calling `register()`require('./my-app-2.cjs');// Hooks won't affect this// .. or custom require() functions created by module.createRequire().const userRequire =createRequire(__filename);userRequire('./my-app-3.cjs');// Hooks won't affect thiscopy

Asynchronous hooks can also be registered using adata: URL with the--import flag:

node --import'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from "node:url"; register("my-instrumentation", pathToFileURL("./"));' ./my-app.jscopy

Chaining of asynchronous customization hooks#

Chaining ofregister() work similarly toregisterHooks(). If synchronous and asynchronoushooks are mixed, the synchronous hooks are always run first before the asynchronoushooks start running, that is, in the last synchronous hook being run, its nexthook includes invocation of the asynchronous hooks.

// entrypoint.mjsimport { register }from'node:module';register('./foo.mjs',import.meta.url);register('./bar.mjs',import.meta.url);awaitimport('./my-app.mjs');// entrypoint.cjsconst { 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');copy

Iffoo.mjs andbar.mjs define aresolve hook, they will be called like so(note the right-to-left, starting with./bar.mjs, then./foo.mjs, then the Node.js default):

Node.js default ←./foo.mjs ←./bar.mjs

When using the asynchronous hooks, the registered hooks also affect subsequentregister calls, which takes care of loading hook modules. In the example above,bar.mjs will be resolved and loaded via the hooks registered byfoo.mjs(becausefoo's hooks will have already been added to the chain). This allowsfor things like writing hooks in non-JavaScript languages, so long asearlier registered hooks transpile into JavaScript.

Theregister() method cannot be called from the thread running the hook module thatexports the asynchronous hooks or its dependencies.

Communication with asynchronous module customization hooks#

Asynchronous hooks run on a dedicated thread, separate from the mainthread that runs application code. This means mutating global variables won'taffect the other thread(s), and message channels must be used to communicatebetween the threads.

Theregister method can be used to pass data to aninitialize hook. Thedata passed to the hook may include transferable objects like ports.

import { register }from'node:module';import {MessageChannel }from'node:worker_threads';// This example demonstrates how a message channel can be used to// communicate with the hooks, by sending `port2` to the hooks.const { port1, port2 } =newMessageChannel();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');// This example showcases how a message channel can be used to// communicate with the hooks, by sending `port2` to the hooks.const { port1, port2 } =newMessageChannel();port1.on('message',(msg) => {console.log(msg);});port1.unref();register('./my-hooks.mjs', {parentURL:pathToFileURL(__filename),data: {number:1,port: port2 },transferList: [port2],});copy

Asynchronous hooks accepted bymodule.register()#

Theregister method can be used to register a module that exports a set ofhooks. The hooks are functions that are called by Node.js to customize themodule resolution and loading process. The exported functions must have specificnames and signatures, and they must be exported as named exports.

exportasyncfunctioninitialize({ number, port }) {// Receives data from `register`.}exportasyncfunctionresolve(specifier, context, nextResolve) {// Take an `import` or `require` specifier and resolve it to a URL.}exportasyncfunctionload(url, context, nextLoad) {// Take a resolved URL and return the source code to be evaluated.}copy

Asynchronous hooks are run in a separate thread, isolated from the main thread whereapplication code runs. That means it is a differentrealm. The hooks threadmay be terminated by the main thread at any time, so do not depend onasynchronous operations (likeconsole.log) to complete. They are inherited intochild workers by default.

initialize()#

• data<any> The data fromregister(loader, import.meta.url, { data }).

Theinitialize hook is only accepted byregister.registerHooks() doesnot support nor need it since initialization done for synchronous hooks can be rundirectly before the call toregisterHooks().

Theinitialize hook provides a way to define a custom function that runs inthe hooks thread when the hooks module is initialized. Initialization happenswhen the hooks module is registered viaregister.

This hook can receive data from aregister invocation, includingports and other transferable objects. The return value ofinitialize can be a<Promise>, in which case it will be awaited before the main application threadexecution resumes.

Module customization code:

// path-to-my-hooks.jsexportasyncfunctioninitialize({ number, port }) {  port.postMessage(`increment:${number +1}`);}copy

Caller code:

import assertfrom'node:assert';import { register }from'node:module';import {MessageChannel }from'node:worker_threads';// This example showcases how a message channel can be used to communicate// between the main (application) thread and the hooks running on the hooks// thread, by sending `port2` to the `initialize` hook.const { port1, port2 } =newMessageChannel();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');// This example showcases how a message channel can be used to communicate// between the main (application) thread and the hooks running on the hooks// thread, by sending `port2` to the `initialize` hook.const { port1, port2 } =newMessageChannel();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],});copy

Asynchronousresolve(specifier, context, nextResolve)#

• specifier<string>
• context<Object>
  • conditions<string[]> Export conditions of the relevantpackage.json
  • importAttributes<Object> An object whose key-value pairs represent theattributes for the module to import
  • parentURL<string> |<undefined> The module importing this one, or undefinedif this is the Node.js entry point
• nextResolve<Function> The subsequentresolve hook in the chain, or theNode.js defaultresolve hook after the last user-suppliedresolve hook
  • specifier<string>
  • context<Object> |<undefined> When omitted, the defaults are provided. When provided, defaultsare merged in with preference to the provided properties.
• Returns:<Object> |<Promise> The asynchronous version takes either an object containing thefollowing properties, or aPromise that will resolve to such an object.
  • format<string> |<null> |<undefined> A hint to theload hook (it might be ignored). It can be amodule format (such as'commonjs' or'module') or an arbitrary value like'css' or'yaml'.
  • importAttributes<Object> |<undefined> The import attributes to use whencaching the module (optional; if excluded the input will be used)
  • shortCircuit<undefined> |<boolean> A signal that this hook intends toterminate the chain ofresolve hooks.Default:false
  • url<string> The absolute URL to which this input resolves

The asynchronous version works similarly to the synchronous version, only that thenextResolve function returns aPromise, and theresolve hook itself can return aPromise.

Warning In the case of the asynchronous version, despite support for returningpromises and async functions, calls toresolve may still block the main thread whichcan impact performance.

Warning Theresolve hook invoked forrequire() calls inside CommonJS modulescustomized by asynchronous hooks does not receive the original specifier passed torequire(). Instead, it receives a URL already fully resolved using the defaultCommonJS resolution.

Warning In the CommonJS modules that are customized by the asynchronous customization hooks,require.resolve() andrequire() will use"import" export condition instead of"require", which may cause unexpected behaviors when loading dual packages.

exportasyncfunctionresolve(specifier, context, nextResolve) {// When calling `defaultResolve`, the arguments can be modified. For example,// to change the specifier or add conditions.if (specifier.includes('foo')) {    specifier = specifier.replace('foo','bar');returnnextResolve(specifier, {      ...context,conditions: [...context.conditions,'another-condition'],    });  }// The hook can also skips default resolution and provide a custom URL.if (specifier ==='special-module') {return {url:'file:///path/to/special-module.mjs',format:'module',shortCircuit:true,// This is mandatory if not calling nextResolve().    };  }// If no customization is needed, defer to the next hook in the chain which would be the// Node.js default resolve if this is the last user-specified loader.returnnextResolve(specifier);}copy

Asynchronousload(url, context, nextLoad)#

• url<string> The URL returned by theresolve chain
• context<Object>
  • conditions<string[]> Export conditions of the relevantpackage.json
  • format<string> |<null> |<undefined> The format optionally supplied by theresolve hook chain. This can be any string value as an input; input values do not need toconform to the list of acceptable return values described below.
  • importAttributes<Object>
• nextLoad<Function> The subsequentload hook in the chain, or theNode.js defaultload hook after the last user-suppliedload hook
  • url<string>
  • context<Object> |<undefined> When omitted, defaults are provided. When provided, defaults aremerged in with preference to the provided properties. In the defaultnextLoad, ifthe module pointed to byurl does not have explicit module type information,context.format is mandatory.
• Returns:<Promise> The asynchronous version takes either an object containing thefollowing properties, or aPromise that will resolve to such an object.
  • format<string>
  • shortCircuit<undefined> |<boolean> A signal that this hook intends toterminate the chain ofload hooks.Default:false
  • source<string> |<ArrayBuffer> |<TypedArray> The source for Node.js to evaluate

Warning: The asynchronousload hook and namespaced exports from CommonJSmodules are incompatible. Attempting to use them together will result in an emptyobject from the import. This may be addressed in the future. This does not applyto the synchronousload hook, in which case exports can be used as usual.

The asynchronous version works similarly to the synchronous version, thoughwhen using the asynchronousload hook, omitting vs providing asource for'commonjs' has very different effects:

• When asource is provided, allrequire calls from this module will beprocessed by the ESM loader with registeredresolve andload hooks; allrequire.resolve calls from this module will be processed by the ESM loaderwith registeredresolve hooks; only a subset of the CommonJS API will beavailable (e.g. norequire.extensions, norequire.cache, norequire.resolve.paths) and monkey-patching on the CommonJS module loaderwill not apply.
• Ifsource is undefined ornull, it will be handled by the CommonJS moduleloader andrequire/require.resolve calls will not go through theregistered hooks. This behavior for nullishsource is temporary — in thefuture, nullishsource will not be supported.

These caveats do not apply to the synchronousload hook, in which casethe complete set of CommonJS APIs available to the customized CommonJSmodules, andrequire/require.resolve always go through the registeredhooks.

The Node.js internal asynchronousload implementation, which is the value ofnext for thelast hook in theload chain, returnsnull forsource whenformat is'commonjs' for backward compatibility. Here is an example hook that wouldopt-in to using the non-default behavior:

import { readFile }from'node:fs/promises';// Asynchronous version accepted by module.register(). This fix is not needed// for the synchronous version accepted by module.registerHooks().exportasyncfunctionload(url, context, nextLoad) {const result =awaitnextLoad(url, context);if (result.format ==='commonjs') {    result.source ??=awaitreadFile(newURL(result.responseURL ?? url));  }return result;}copy

This doesn't apply to the synchronousload hook either, in which case thesource returned contains source code loaded by the next hook, regardlessof module format.

Import from HTTPS#

The hook below registers hooks to enable rudimentary support for suchspecifiers. While this may seem like a significant improvement to Node.js corefunctionality, 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.

// https-hooks.mjsimport { get }from'node:https';exportfunctionload(url, context, nextLoad) {// For JavaScript to be loaded over the network, we need to fetch and// return it.if (url.startsWith('https://')) {returnnewPromise((resolve, reject) => {get(url,(res) => {let data ='';        res.setEncoding('utf8');        res.on('data',(chunk) => data += chunk);        res.on('end',() =>resolve({// This example assumes all network-provided JavaScript is ES module// code.format:'module',shortCircuit:true,source: data,        }));      }).on('error',(err) =>reject(err));    });  }// Let Node.js handle all other URLs.returnnextLoad(url);}copy

// main.mjsimport {VERSION }from'https://coffeescript.org/browser-compiler-modern/coffeescript.js';console.log(VERSION);copy

With the preceding hooks module, runningnode --import 'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from "node:url"; register(pathToFileURL("./https-hooks.mjs"));' ./main.mjsprints the current version of CoffeeScript per the module at the URL inmain.mjs.

Transpilation#

Sources that are in formats Node.js doesn't understand can be converted intoJavaScript using theload hook.

This is less performant than transpiling source files before running Node.js;transpiler hooks should only be used for development and testing purposes.

// coffeescript-hooks.mjsimport { readFile }from'node:fs/promises';import { findPackageJSON }from'node:module';import coffeescriptfrom'coffeescript';const extensionsRegex =/\.(coffee|litcoffee|coffee\.md)$/;exportasyncfunctionload(url, context, nextLoad) {if (extensionsRegex.test(url)) {// CoffeeScript files can be either CommonJS or ES modules. Use a custom format// to tell Node.js not to detect its module type.const {source: rawSource } =awaitnextLoad(url, { ...context,format:'coffee' });// This hook converts CoffeeScript source code into JavaScript source code// for all imported CoffeeScript files.const transformedSource = coffeescript.compile(rawSource.toString(), url);// To determine how Node.js would interpret the transpilation result,// search up the file system for the nearest parent package.json file// and read its "type" field.return {format:awaitgetPackageType(url),shortCircuit:true,source: transformedSource,    };  }// Let Node.js handle all other URLs.returnnextLoad(url, context);}asyncfunctiongetPackageType(url) {// `url` is only a file path during the first iteration when passed the// resolved url from the load() hook// an actual file path from load() will contain a file extension as it's// required by the spec// this simple truthy check for whether `url` contains a file extension will// work for most projects but does not cover some edge-cases (such as// extensionless files or a url ending in a trailing space)const pJson =findPackageJSON(url);returnreadFile(pJson,'utf8')    .then(JSON.parse)    .then((json) => json?.type)    .catch(() =>undefined);}copy

// coffeescript-sync-hooks.mjsimport { readFileSync }from'node:fs';import { registerHooks, findPackageJSON }from'node:module';import coffeescriptfrom'coffeescript';const extensionsRegex =/\.(coffee|litcoffee|coffee\.md)$/;functionload(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,    };  }returnnextLoad(url, context);}functiongetPackageType(url) {const pJson =findPackageJSON(url);if (!pJson) {returnundefined;  }try {const file =readFileSync(pJson,'utf-8');returnJSON.parse(file)?.type;  }catch {returnundefined;  }}registerHooks({ load });copy

Running hooks#

# main.coffeeimport { scream }from'./scream.coffee'console.log scream'hello, world'import { version }from'node:process'console.log"Brought to you by Node.js version#{version}"copy

# scream.coffeeexport scream =(str) -> str.toUpperCase()copy

For the sake of running the example, add apackage.json file containing themodule type of the CoffeeScript files.

{"type":"module"}copy

This is only for running the example. In real world loaders,getPackageType() must beable to return anformat known to Node.js even in the absence of an explicit type in apackage.json, or otherwise thenextLoad call would throwERR_UNKNOWN_FILE_EXTENSION(if undefined) orERR_UNKNOWN_MODULE_FORMAT (if it's not a known format listed intheload hook documentation).

With the preceding hooks modules, runningnode --import 'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from "node:url"; register(pathToFileURL("./coffeescript-hooks.mjs"));' ./main.coffeeornode --import ./coffeescript-sync-hooks.mjs ./main.coffeecausesmain.coffee to be turned into JavaScript after its source code isloaded from disk but before Node.js executes it; and so on for any.coffee,.litcoffee or.coffee.md files referenced viaimport statements of anyloaded file.

Import maps#

The previous two examples definedload hooks. This is an example of aresolve hook. This hooks module reads animport-map.json file that defineswhich specifiers to override to other URLs (this is a very simplisticimplementation of a small subset of the "import maps" specification).

// import-map-hooks.jsimport fsfrom'node:fs/promises';const { imports } =JSON.parse(await fs.readFile('import-map.json'));exportasyncfunctionresolve(specifier, context, nextResolve) {if (Object.hasOwn(imports, specifier)) {returnnextResolve(imports[specifier], context);  }returnnextResolve(specifier, context);}copy

// import-map-sync-hooks.jsimport fsfrom'node:fs/promises';importmodulefrom'node:module';const { imports } =JSON.parse(fs.readFileSync('import-map.json','utf-8'));functionresolve(specifier, context, nextResolve) {if (Object.hasOwn(imports, specifier)) {returnnextResolve(imports[specifier], context);  }returnnextResolve(specifier, context);}module.registerHooks({ resolve });copy

// main.jsimport'a-module';copy

// import-map.json{"imports":{"a-module":"./some-module.js"}}copy

// some-module.jsconsole.log('some module!');copy

new SourceMap(payload[, { lineLengths }])#

• payload<Object>
• lineLengths<number[]>

Creates a newsourceMap instance.

payload is an object with keys matching theSource map format:

• file<string>
• version<number>
• sources<string[]>
• sourcesContent<string[]>
• names<string[]>
• mappings<string>
• sourceRoot<string>

lineLengths is an optional array of the length of each line in thegenerated code.

sourceMap.payload#

• Returns:<Object>

Getter for the payload used to construct theSourceMap instance.

sourceMap.findEntry(lineOffset, columnOffset)#

• lineOffset<number> The zero-indexed line number offset inthe generated source
• columnOffset<number> The zero-indexed column number offsetin the generated source
• Returns:<Object>

Given a line offset and column offset in the generated sourcefile, returns an object representing the SourceMap range in theoriginal file if found, or an empty object if not.

The object returned contains the following keys:

• generatedLine<number> The line offset of the start of therange in the generated source
• generatedColumn<number> The column offset of start of therange in the generated source
• originalSource<string> The file name of the original source,as reported in the SourceMap
• originalLine<number> The line offset of the start of therange in the original source
• originalColumn<number> The column offset of start of therange in the original source
• name<string>

The returned value represents the raw range as it appears in theSourceMap, based on zero-indexed offsets,not 1-indexed line andcolumn numbers as they appear in Error messages and CallSiteobjects.

To get the corresponding 1-indexed line and column numbers from alineNumber and columnNumber as they are reported by Error stacksand CallSite objects, usesourceMap.findOrigin(lineNumber, columnNumber)

sourceMap.findOrigin(lineNumber, columnNumber)#

• lineNumber<number> The 1-indexed line number of the callsite in the generated source
• columnNumber<number> The 1-indexed column numberof the call site in the generated source
• Returns:<Object>

Given a 1-indexedlineNumber andcolumnNumber from a call site inthe generated source, find the corresponding call site locationin the original source.

If thelineNumber andcolumnNumber provided are not found in anysource map, then an empty object is returned. Otherwise, thereturned object contains the following keys:

• name<string> |<undefined> The name of the range in thesource map, if one was provided
• fileName<string> The file name of the original source, asreported in the SourceMap
• lineNumber<number> The 1-indexed lineNumber of thecorresponding call site in the original source
• columnNumber<number> The 1-indexed columnNumber of thecorresponding call site in the original source