Хуки кастомизации модулей: перехват resolve и load

Два хука: resolve и load

В пайплайне модулей Node есть два шва, в которые можно врезаться, и хук кастомизации — это функция, сидящая на одном из них. resolve(specifier, context, nextResolve) превращает спецификатор ("lodash", "./util.js", "data:...") в финальный, полностью квалифицированный URL плюс объявленный format ("module", "commonjs", "json", …). load(url, context, nextLoad) берёт этот URL и возвращает сам source (строку или буфер) и его format — и именно здесь можно преобразовать байты до того, как их увидит V8. Resolve отвечает на «какой файл»; load — на «что в нём». Транспайлер — это load-хук: он перехватывает .ts-URL, компилирует исходник и отдаёт JavaScript с format: "module".

Третий аргумент — это вся суть. nextResolve / nextLoad — это следующий хук в цепочке (или встроенный дефолт Node, если ты последний). Либо ты обрабатываешь запрос сам, либо вызываешь next…(specifier, context), чтобы делегировать дальше. Поэтому хуки композируются: резолвер tsx и резолвер инструмента покрытия могут быть оба зарегистрированы, каждый обрабатывает то, что ему важно, и передаёт остальное вниз.

// 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 };
}

Здесь живут две обязательные детали. shortCircuit: true говорит Node, что ты намеренно обработал запрос и не вызываешь nextLoad — опусти его, и Node бросит ошибку, чтобы хук тихо не съел цепочку. А sourcemap: "inline" — та самая строка, которую хук во вступлении забыл: без неё каждая позиция, о которой сообщает V8, — в скомпилированном выводе, а не в твоём .ts.

Регистрация хуков: module.register

Хуки не подключают вручную — их register()-ят, и Node поднимает их в отдельном потоке.

// 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) резолвит specifier относительно parentURL (передавай import.meta.url, чтобы относительный ./loader.js работал независимо от cwd), затем загружает этот модуль в отдельном worker-потоке и начинает направлять каждый последующий import/require через его экспорты resolve и load. Правило порядка, на котором обжигаются: хуки влияют только на модули, загруженные после запуска register, поэтому регистрация должна произойти до собственных импортов приложения — что как раз и гарантирует --import (он запускает файл до главной точки входа). Поставь register() в начало app.js — и импорт самого app.js, и всё, что он статически импортирует, уже зарезолвилось до того, как твой хук вообще существовал.

Чтобы передать конфигурацию внутрь хуков, работающих вне потока, register принимает опцию data и transferList, доставляемые в опциональный хук initialize, который выполняется один раз в потоке хука:

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;
}

Когда тянуться за хуком — и когда нет

Прежде чем подключать кастомный хук, спроси себя: это проблема dev-цикла или требование прода? Ответ почти всегда определяет верный выбор.

Хуки оправдывают себя в узком наборе случаев: транспиляция TypeScript/JSX на лету (tsx, ts-node, swc-node — все регистрируют load-хук), моки и инструментирование в тестах, кастомные протоколы (import x from "config:db"), ремаппинг в стиле import-map и инструменты покрытия, переписывающие исходник. Общий мотив — эргономика разработки и тестов: запуск кода как написан, без сборки.

Компромиссы реальны и накапливаются. (а) Хук выполняется для каждого модуля, так что медленный load добавляет свою стоимость линейно по всему дереву зависимостей — шаг транспиляции на load по ~30–50 мс на файл вхолодную превращает приложение из 400 файлов в лишние 12–20 секунд старта на каждый запуск node. (б) Модель «вне потока» означает отсутствие дешёвого общего состояния — из хука не дотянуться до глобалов приложения; всё идёт через порт. (в) Это нестабильная поверхность. API хуков переделывали между Node 18, 20 и 22 (в потоке → вне потока, удаление globalPreload, добавление register), так что загрузчик, привязанный к одной мажорной версии, может сломаться на следующей.

В совокупности: хуки дают быстрее dev-цикл ценой налога на старт каждого вызова, отсутствия дешёвого общего состояния и API, который скачет между мажорами. Сеньорское решение: транспилируй на этапе сборки для прода (одна стоимость, source maps выписаны на диск, стабильные артефакты), а хуки оставь для dev/тестов, где цикл без сборки стоит платы за каждый запуск.