Свой сборщик: граф импортов, обёртка и реестр

Браузер умеет модули и без сборщика: подключите точку входа с type="module", и остальные файлы он подтянет сам по цепочке import. Мешают три вещи. Голое имя пакета вроде import dayjs from "dayjs" браузер не разрешит: адресом такое имя работает только для инструментов, которые знают про node_modules. Пакет, разложенный на модули, приезжает файлами — у lodash-es их сотни, и каждый стал бы отдельным запросом. А JSX и аннотации типов движку не разобрать вовсе. Всё это сборщик решает до запуска, и начинает он с чтения импортов.

Файлы проекта для сборщика — строки. Возьмём три: main импортирует cart, cart — money. Функция importsOf достаёт из текста пути импортов регуляркой, resolve превращает "./cart.js" в полный адрес от папки файла, а graph обходит зависимости в глубину и отмечает пройденные файлы в seen, чтобы общий модуль не встал в очередь дважды.

Прогноз: в каком порядке встанут файлы? Обход начинается с main.js — окажется ли он первым? И напечатается ли «money выполнен»?

// три файла проекта — просто строки: сборщик читает текст, а не выполняет его
const files: Record<string, string> = {
  "/src/main.js": 'import { total } from "./cart.js";\nconsole.log(total([120, 230]));',
  "/src/cart.js": 'import { rub } from "./money.js";\nexport function total(prices) {\n  return rub(prices.reduce((a, b) => a + b, 0));\n}',
  "/src/money.js": 'console.log("money выполнен");\nexport function rub(n) {\n  return n + " ₽";\n}',
};

function importsOf(code: string): string[] {
  return [...code.matchAll(/import\s*\{[^}]*\}\s*from\s*"([^"]+)"/g)].map((m) => m[1]);
}

function resolve(from: string, spec: string): string {
  return from.slice(0, from.lastIndexOf("/")) + "/" + spec.replace("./", "");
}

function graph(entry: string): string[] {
  const order: string[] = [];
  const seen = new Set<string>();
  const visit = (file: string): void => {
    if (seen.has(file)) return;
    seen.add(file);
    for (const spec of importsOf(files[file])) visit(resolve(file, spec));
    order.push(file); // файл встаёт в очередь после всех своих зависимостей
  };
  visit(entry);
  return order;
}

console.log(graph("/src/main.js").join(" → "));

Первым встал money.js, а точка входа — последней. Всё решает место строки order.push(file): она стоит после цикла, и файл попадает в очередь, только когда пройдены все его зависимости. Значит, всё, что файлу нужно, в очереди всегда стоит раньше него. А «money выполнен» не напечаталось: код модулей никто не запускал, граф выстроен одним чтением текста.

Обход графа вы уже писали, когда считали клиентскую часть от файла с 'use client'. Там важен был только набор файлов, и хватало очереди с сортировкой в конце. Сборщику нужен ещё и порядок — поэтому обход в глубину и запись в очередь на выходе из файла, а не на входе.

Регулярка в importsOf — сознательное упрощение: она видит только импорт с фигурными скобками и двойными кавычками. Где она подводит всерьёз, покажет последний раздел.

Эти строки — не выдумка для песочницы. На диске лежит тот же маленький проект, и дальше его соберут настоящие Vite и esbuild. Отличие одно: в проекте есть четвёртый файл, editor.js, и main грузит его по нажатию кнопки. В песочнице он появится в разделе про куски.

$ for f in src/money.js src/cart.js src/editor.js src/main.js index.html; do echo "// $f"; cat "$f"; echo; done

Очередь есть, но просто склеить файлы подряд нельзя. У каждого модуля своя область видимости: rub из money не должна встретиться с одноимённой функцией из соседнего файла. А строка import { rub } from "./money.js" в склеенном файле пошла бы за файлом, которого на сервере больше нет. Своя область у кода бывает внутри функции — это приём IIFE, которым прятали переменные до модулей. Сборщик берёт его почти без изменений, только функция получает два параметра: require, чтобы брать чужое, и exports, чтобы отдавать своё.

files, resolve и graph из прошлого примера переехали в подложку. wrap делает две замены: строку импорта — на вызов require, объявление export function — на запись в exports. Прогноз: во что превратится первая строка cart.js и какой путь окажется в скобках у require?

// files, resolve и graph — из прошлого примера, едут в подложке
declare const files: Record<string, string>;
declare function resolve(from: string, spec: string): string;

// модуль становится функцией: import — вызовом require, export — записью в exports
function wrap(file: string): string {
  const body = files[file]
    .replace(/import\s*\{([^}]*)\}\s*from\s*"([^"]+)";?/g, (_: string, names: string, spec: string) =>
      `const {${names}} = require("${resolve(file, spec)}");`)
    .replace(/export function (\w+)/g, "exports.$1 = function $1");
  return `"${file}": function (require, exports) {\n${body}\n}`;
}

console.log(wrap("/src/cart.js"));

В скобках "/src/money.js", а не "./money.js": путь разрешён на сборке, и рантайму искать уже нечего — ему достаточно найти строку в реестре. Вторая замена сделала из объявления запись: exports.total = function total. Функция та же, но теперь она лежит в объекте, который получит всякий, кто позовёт require с адресом cart.

Осталось сложить обёртки туда, где их найдут по адресу, и написать саму require. В разделе про CommonJS статьи о модулях она описана словами — находит файл, выполняет его один раз, запоминает exports в кеше — и показана реестром на четырёх строках, без функции и без кеша. Дерево require в один файл склеивали ещё Browserify и webpack; теперь такой рантайм целиком пишет наш сборщик.

bundle кладёт обёртки в объект modules — адрес → функция — и дописывает к ним рантайм: объект cache и функцию require. Первый вызов с адресом заводит в кеше пустой exports, выполняет тело модуля и оставляет в этом объекте всё, что модуль записал. Следующий вызов с тем же адресом тело уже не трогает и сразу отдаёт запомненный объект. Весь бандл — одна строка, и запускает её new Function.

Чтобы кешу было что делать, main в примере импортирует money и сам, в обход cart: теперь этот модуль нужен двоим. Прогноз: сколько раз напечатается «money выполнен» и что выйдет раньше — эта строка или «350 ₽»?

// files, graph и wrap — из прошлых примеров, едут в подложке
declare const files: Record<string, string>;
declare function graph(entry: string): string[];
declare function wrap(file: string): string;

function bundle(entry: string): string {
  const modules = graph(entry).map(wrap).join(",\n");
  // рантайм: реестр функций по адресу и кеш готовых exports
  return `const modules = {\n${modules}\n};
const cache = {};
function require(id) {
  if (!(id in cache)) {
    cache[id] = {};
    modules[id](require, cache[id]);
  }
  return cache[id];
}
require("${entry}");`;
}

// main теперь импортирует money и сам, в обход cart
files["/src/main.js"] = 'import { rub } from "./money.js";\n' + files["/src/main.js"];

console.log("модулей в бандле:", graph("/src/main.js").length);
new Function(bundle("/src/main.js"))();

Пустой exports кладётся в кеш до выполнения тела, а не после. Почему именно так, выяснится в первой задаче, где два файла импортируют друг друга.

Реестр «строка → функция» вы уже встречали в своём Server Action: там по идентификатору искали функцию действия, а наполнял реестр манифест, собранный сборщиком.

$ npx next build --webpack

$ npx next build

$ npx vite build --minify false

Зачем резать бандл, разобрано в статье про динамический импорт: всё, что нужно не сразу, не должно задерживать первую загрузку. Здесь — как именно режется. В проект приходит четвёртый файл, editor.js, и main зовёт его через import().

split кладёт в main.js граф от точки входа. Для каждого import("./x.js") в тексте main он строит граф x и выбрасывает из него всё, что уже взято в main, — остаток уезжает в свой файл. Сам вызов переписывается: вместо import() в main встаёт require.load("editor.js"), который грузит файл, а следом — обычный require. У webpack такая функция называется __webpack_require__.e. Рантайм run в подложке изображает сеть: файл «приходит» через 50 мс и дописывает свои модули в реестр.

Прогноз: какие модули окажутся в каждом файле и в каком порядке выйдут шесть строк — две про файлы и четыре от самих модулей?

// files, graph и wrap — в подложке. У main появляется import(): граница куска
declare const files: Record<string, string>;
declare function graph(entry: string): string[];
declare function wrap(file: string): string;
declare function run(network: Record<string, string>): void; // рантайм с загрузкой кусков

files["/src/editor.js"] = 'console.log("editor выполнен");\nexport function open() {\n  return "редактор открыт";\n}';
files["/src/main.js"] += '\nimport("./editor.js").then((m) => console.log(m.open()));';

function split(entry: string): Record<string, string> {
  const main = graph(entry);
  const out: Record<string, string> = {};
  const define = (list: string[]) => `define({\n${list.map(wrap).join(",\n")}\n});`;
  // import("./x.js") в тексте становится загрузкой файла x.js по сети
  out["main.js"] = define(main).replace(/import\("\.\/([^"]+)"\)/g,
    (_: string, name: string) => `require.load("${name}").then(() => require("/src/${name}"))`);
  for (const [, name] of files[entry].matchAll(/import\("\.\/([^"]+)"\)/g)) {
    out[name] = define(graph("/src/" + name).filter((file) => !main.includes(file)));
  }
  return out;
}

const network = split("/src/main.js");
for (const [name, text] of Object.entries(network)) {
  console.log(name + ":", [...text.matchAll(/"(\/src\/[^"]+)": function/g)].map((m) => m[1]).join(", "));
}
run(network);

В editor.js лёг один модуль. money и cart редактор не импортирует, а если бы импортировал — они уже в main, и второй раз их не везут. Порядок строк повторяет сеть: main выполнился целиком, со своими «money выполнен» и «350 ₽», и только когда кусок «пришёл», в реестре появился editor и выполнился он. Вызов import() превратился в три шага: загрузить файл, пополнить реестр, отдать модуль.

На месте setTimeout у настоящего рантайма сеть. webpack вставляет в страницу тег script с адресом куска, а Vite оставляет браузеру настоящий import().

Настоящий кусок устроен так же. Vite на тех же четырёх файлах с диска положил editor в отдельный файл, а import("./editor.js") в тексте main переписал на имя этого файла и обернул своим помощником __vitePreload: тот сначала подгружает то, что куску нужно заранее (здесь список пуст), и только потом зовёт import().

$ npx vite build --minify false --outDir dist-a

Модули проекта в главном файле идут в той же очерёдности, что у graph: money, cart, main. Только обёрток нет: Vite склеил их в одну область, как говорилось в разделе про реестр, а свой служебный код вставил рядом — в выводе он пропущен.

Последний шаг — имя файла. Браузер кеширует файлы по адресу, и если назвать бандл просто main.js, после выката посетитель рискует получить из кеша вчерашний. Поэтому в имя вписывают хеш — короткую свёртку содержимого. Свёртку возьмём простую, FNV-1a: пройти по символам, смешать каждый с накопленным числом и напечатать восемь шестнадцатеричных знаков.

Прогноз: совпадут ли имена у двух одинаковых строк? И насколько похожими выйдут имена у строк, которые различаются одним словом?

// FNV-1a: короткая свёртка текста в 8 шестнадцатеричных знаков
function hash(text: string): string {
  let h = 0x811c9dc5;
  for (let i = 0; i < text.length; i++) {
    h ^= text.charCodeAt(i);
    h = Math.imul(h, 0x01000193) >>> 0;
  }
  return h.toString(16).padStart(8, "0");
}

console.log("editor-" + hash('return "редактор открыт";') + ".js");
console.log("editor-" + hash('return "редактор открыт";') + ".js");
console.log("editor-" + hash('return "редактор готов";') + ".js");

Одинаковый текст — одинаковое имя, сколько ни считай: хеш зависит только от содержимого. Одно слово — и имя меняется целиком, а не в паре знаков. На этом держится весь приём: по адресу с хешем содержимое не изменится никогда, поэтому файл можно держать в кеше сколько угодно, а новая версия придёт под новым именем.

Теперь применим хеш к кускам. emit называет каждый кусок хешем его текста, вписывает новое имя туда, где main этот кусок зовёт, и только потом считает хеш самого main. Правка — одно слово в editor.js: «открыт» становится «готов». Главный прогноз статьи: сколько имён сменится — одно или два?

// files, split и hash — в подложке. Имя файла — хеш его содержимого
declare const files: Record<string, string>;
declare function split(entry: string): Record<string, string>;
declare function hash(text: string): string;

function emit(entry: string): Record<string, string> {
  const out = split(entry);
  const names: Record<string, string> = {};
  for (const name of Object.keys(out).filter((n) => n !== "main.js")) {
    names[name] = name.replace(".js", "-" + hash(out[name]) + ".js");
    // main зовёт кусок по имени — значит, имя куска вписано в текст main
    out["main.js"] = out["main.js"].replace(`"${name}"`, `"${names[name]}"`);
  }
  names["main.js"] = "main-" + hash(out["main.js"]) + ".js";
  return names;
}

const before = emit("/src/main.js");
files["/src/editor.js"] = files["/src/editor.js"].replace("открыт", "готов");
const after = emit("/src/main.js");

for (const name of Object.keys(before)) {
  console.log(name, before[name] === after[name] ? "имя то же" : "новое имя");
}

Два. Имя editor сменилось честно — поменялся его текст. main никто не трогал, но его текст всё равно другой: в нём записано имя куска, require.load("editor-….js"). Новое имя куска — новый текст main — новый хеш. Это и называют каскадом: правка в глубине поднимается по цепочке файлов, которые зовут друг друга по имени, и посетитель заново скачивает файлы, где не поменялось ни строчки кода.

Настоящий Vite ведёт себя так же. Та же правка в editor.js на диске, вторая сборка рядом с первой — и два главных файла отличаются одной строкой:

$ sed -i "" "s/редактор открыт/редактор готов/" src/editor.js
$ npx vite build --minify false --outDir dist-b

Лечат каскад так: main зовёт кусок не настоящим именем, а постоянным ключом, а соответствие «ключ → имя» живёт снаружи. У Vite для этого есть экспериментальная настройка build.chunkImportMap. Соответствие она кладёт в HTML картой импортов — тегом <script type="importmap">, по которому браузер сам подставляет настоящий адрес, когда модуль просит ключ. Та же правка, две сборки:

$ cat vite.config.js
export default { build: { chunkImportMap: true, minify: false } }
$ npx vite build --outDir dist-map-a
# та же правка editor.js
$ npx vite build --outDir dist-map-b

Главный файл сохранил имя: в его тексте стоит ключ, и после правки ключ тот же. Сменились только те места, где настоящее имя куска записано на самом деле, — сам кусок и карта в index.html. Имена в этом листинге у вас будут другими: с картой они зависят ещё и от пути к проекту, поэтому смотрите на устройство, а не на буквы.

У Next каскад тоже есть, только на уровень выше. Правка клиентского компонента без import() меняет имя одного его куска: адреса кусков клиентских компонентов лежат в HTML, в потоке серверных компонентов и в манифесте, а не в текстах соседних кусков. А кусок, который грузится через import(), вписан в текст куска, который его грузит, — и правка ленивого модуля снова меняет два имени, как у нашего emit.

# chunks-a.txt и chunks-b.txt — списки файлов .next/static после next build
# до и после правки в ui/price.tsx: {count} × {rub(base)} → {count} x {rub(base)}
$ diff chunks-a.txt chunks-b.txt

$ cat lib/editor.ts
export function open(): string {
  return "editor open";
}
$ cat ui/price.tsx
"use client";
import { useState } from "react";
import { rub } from "../lib/money";

export function Price({ base }: { base: number }) {
  const [count, setCount] = useState(1);
  const edit = () => import("../lib/editor").then((m) => console.log(m.open()));
  return <button onClick={() => { setCount(count + 1); edit(); }}>{count} × {rub(base)}</button>;
}

Отсюда правило раздачи, общее для всех сборщиков. Файл с хешем в имени можно кешировать навсегда, с пометкой immutable: под этим именем другого содержимого не будет. А HTML отдают с no-cache: именно он несёт новые имена, и вчерашний HTML из кеша поведёт посетителя к вчерашним файлам. Как эти заголовки выставляют папке с кусками и страницам, разобрано в статье про статический экспорт.

$ npx vite build --sourcemap --outDir dist-sm

Сборщик собран: граф, обёртка, реестр, куски, хеш. Самое хрупкое в нём — самое первое, importsOf. Регулярка не знает, что читает: код, комментарий или строку. Прогноз: сколько зависимостей она найдёт в файле, где настоящий импорт один?

declare function importsOf(code: string): string[]; // из первого примера — в подложке

const tricky = [
  '// раньше здесь было: import { old } from "./legacy.js";',
  "const help = 'пишите import { rub } from \"./money.js\"';",
  'import { total } from "./cart.js";',
].join("\n");

console.log(importsOf(tricky));

Три. Первую регулярка вытащила из комментария — так выглядит закомментированная старая строка. Вторую — из строки-подсказки внутри кода. Сборщик с такой регуляркой пошёл бы искать ./legacy.js и ./money.js, которых этот файл не импортирует: удалённый файл уронил бы сборку, а существующий встал бы в граф этого файла без всякого импорта.

Поэтому настоящие сборщики импорты регуляркой не ищут. Они отдают файл компилятору, получают от него дерево, где комментарий — это комментарий, а строка — строка, и берут импорты из узлов этого дерева. Компилятор файла — второй слой сборки, ему посвящена следующая статья. А как граф, куски и манифест устроены внутри Next, где один граф делится на сервер и клиент, — статья после неё.

Напоследок — те же четыре файла с диска через esbuild с включённой нарезкой на куски. Сравните с тем, что напечатал split в разделе про куски, и со сборкой Vite:

$ npx esbuild src/main.js --bundle --format=esm --splitting --charset=utf8 --outdir=out-esb-utf8 --entry-names='[name]-[hash]' --chunk-names='[name]-[hash]'

Два файла, как у нас: в главном money, cart и main, в куске — editor, а import() ведёт к имени с хешем. Обёрток нет: esbuild, как и Rolldown, поднял код модулей в одну область. Граф, куски и хеш у настоящих сборщиков те же, что у нашего. Обёртка и реестр у Rolldown и esbuild появляются там, где модули нельзя склеить, а webpack и Turbopack держат реестр всегда — только кладут в одну его функцию сразу несколько модулей.