Module customization hooks: intercepting resolve and load

The two hooks: resolve and load

Node’s module pipeline has two seams you can splice into, and a customization hook is a function that sits on one of them. resolve(specifier, context, nextResolve) turns a specifier ("lodash", "./util.js", "data:...") into a final, fully-qualified URL plus a declared format ("module", "commonjs", "json", …). load(url, context, nextLoad) takes that URL and returns the actual source (a string or buffer) and its format — and this is where you can transform the bytes before V8 ever sees them. Resolve answers “which file”; load answers “what’s in it”. A transpiler is a load hook: it intercepts a .ts URL, compiles the source, and hands back JavaScript with format: "module".

The third argument is the whole game. nextResolve / nextLoad is the next hook in the chain (or Node’s built-in default if you’re last). You either handle the request yourself, or you call next…(specifier, context) to defer. This is why hooks compose: tsx’s resolver and a coverage tool’s resolver can both be registered, each handling what it cares about and passing the rest down.

// loader.js — a load hook that transpiles TS on the fly
import { readFile } from "node:fs/promises";
import { transform } from "some-fast-transpiler"; // e.g. swc/esbuild

export async function load(url, context, nextLoad) {
  if (!url.endsWith(".ts")) {
    return nextLoad(url, context); // not ours — defer down the chain
  }
  const raw = await readFile(new URL(url), "utf8");
  const { code } = await transform(raw, { sourcemap: "inline" }); // ← keep maps!
  return { format: "module", source: code, shortCircuit: true };
}

Two non-negotiable details live here. shortCircuit: true tells Node you deliberately handled this and are not calling nextLoad — omit it and Node throws to stop a hook silently swallowing the chain. And sourcemap: "inline" is the line that the hook in the intro forgot: without it, every position V8 reports is in the compiled output, not your .ts.

Registering hooks: module.register

You don’t wire hooks by hand — you register() them, and Node spins them up on a dedicated thread.

// app entry, run first: node --import ./register.js app.js
import { register } from "node:module";
register("./loader.js", import.meta.url); // (specifier, parentURL)

register(specifier, parentURL) resolves specifier relative to parentURL (pass import.meta.url so a relative ./loader.js works regardless of cwd), then loads that module on a separate worker thread and starts routing every subsequent import/require through its resolve and load exports. The ordering rule that bites people: hooks only affect modules loaded after register runs, so registration must happen before the app’s own imports — which is exactly what --import guarantees (it runs the file before the main entry). Put register() at the top of app.js instead and the import of app.js itself, and anything it statically imports, was already resolved before your hook existed.

To pass configuration into the off-thread hooks, register takes a data option and a transferList, delivered to an optional initialize hook that runs once on the hook thread:

register("./loader.js", {
  parentURL: import.meta.url,
  data: { tsconfig: "./tsconfig.json" },        // structured-cloned to the hook thread
});

// loader.js
export async function initialize(data) {
  // runs once on the hook thread; stash config, open a MessagePort, etc.
  globalThis.__tsconfig = data.tsconfig;
}

When to reach for a hook — and when not to

Before you wire a custom hook, ask yourself: is this a dev-loop problem, or a production requirement? The answer almost always determines the right choice.

Hooks earn their keep in a tight set of cases: on-the-fly TypeScript/JSX transpilation (tsx, ts-node, swc-node all register a load hook), test mocking and instrumentation, custom protocols (import x from "config:db"), import-map-style remapping, and coverage tools rewriting source. The common thread is development and test ergonomics — running code as authored without a build.

The tradeoffs are real and they compound. (a) A hook runs for every module, so a slow load adds its cost linearly across your dependency tree — a transpile-on-load step that costs ~30–50ms per file cold turns a 400-file app into 12–20 extra seconds of startup, every node invocation. (b) The off-thread model means no cheap shared state — you can’t reach into the app’s globals from a hook; everything crosses a port. (c) It’s an unstable surface. The hooks API was reshaped between Node 18, 20, and 22 (in-thread → off-thread, globalPreload removed, register added), so a loader pinned to one major can break on the next.

Taken together: hooks buy you a faster inner dev loop at the cost of per-invocation startup tax, no cheap shared state, and an API that shifts under you on Node upgrades. The senior call: transpile at build time for production (one cost, source maps emitted to disk, stable artifacts), and reserve hooks for dev/test where the no-build loop is worth the per-run tax.