Turbopack внутри Next: один граф на сервер и клиент

Приложение — то же, что в статье про свой сборщик: страница app/page.tsx рисует клиентский компонент Price из ui/price.tsx, где стоит "use client", а Price берёт rub из lib/money.ts. Рядом вторая страница, app/admin/page.tsx, — один заголовок. Приложение собрано дважды: командой next build и командой next build --webpack. Прогноз: чем будут отличаться два лога?

$ rm -rf .next && npx next build

$ rm -rf .next && npx next build --webpack

Первая строка называет сборщик: (Turbopack) без флага и (webpack) с флагом --webpack. В 16-й версии Next Turbopack — сборщик по умолчанию и для next build, и для next dev, а webpack остался запасным путём. Дальше логи почти совпадают. Running TypeScript — отдельный шаг, та же проверка типов, что у tsc: сам сборщик типы только стирает. Таблицу маршрутов в конце читать учит статья про режимы отрисовки.

Различаются куски. webpack собирает имя из маршрута и хеша — app/page-c7cc6525f8ec2e9b.js, а Turbopack называет куски непрозрачно — 0uk_002q-0_-r.js, и по имени не понять, что внутри. Что лежит в этом куске, покажет следующий раздел.

Отдельной программы Turbopack в проекте нет. Пакет turbopack на npm — заглушка, а сам сборщик скомпилирован в нативный модуль Next: пакет @next/swc-… под вашу платформу, в котором живёт и компилятор файла SWC. Где такого модуля нет, например на FreeBSD, Next берёт сборку SWC на WebAssembly, и Turbopack там не работает — остаётся --webpack. Сам webpack Next тоже везёт внутри себя, ставить его отдельно не нужно.

Сайт, который вы читаете, тоже собирает Next:

$ next build --turbopack   # скрипт build сайта учебника

Флаг --turbopack остался в скрипте с тех пор, когда Turbopack для сборки включали руками. В 16-й версии он ничего не меняет — первая строка та же, (Turbopack), — и из скриптов сайта его убрали вместе с этой главой. Нужен этот флаг в одном случае, о нём — в разделе про webpack. А заканчивается сборка сайта не сервером, а папкой файлов: учебник собран статическим экспортом.

В статье про границу клиента вы считали клиентскую часть обходом графа: всё, до чего дотянутся импорты файла с "use client", уезжает в браузер. В Next этот обход делает сборщик, и вопрос у него не «браузер или сервер». ui/price.tsx нужен трём сторонам. Серверным компонентам — ссылкой: на месте Price в их выводе стоит ссылка на модуль, а не его код. Серверной отрисовке первого HTML — кодом: кнопку нужно нарисовать в разметку. И браузеру — кодом, который эту кнопку оживит.

Turbopack держит все три стороны в одном графе модулей и помечает каждый модуль слоем. Пометки видны в идентификаторах модулей, которые dev-сервер пишет в свои файлы. Прогноз: сколько записей с разными пометками окажется у ui/price.tsx и в каких слоях будет lib/money.ts, который импортирует только Price?

$ grep -rhoa -E '\[project\]/(ui/price\.tsx|lib/money\.ts|app/page\.tsx|app/admin/page\.tsx) \[[a-z-]+\] \([a-z, ]+\)' .next/dev/server .next/dev/static | sort | uniq -c

Слоёв три: [app-rsc] — серверные компоненты, [app-ssr] — отрисовка клиентских компонентов в HTML на сервере, [app-client] — браузер. А записей у ui/price.tsx четыре: в слое серверных компонентов он встречается дважды. Запись (client reference proxy) — та самая ссылка-заглушка, которую получает page.tsx вместо кода. Вторая, (ecmascript), — модуль того же файла в том же слое; зачем он там, листинг не говорит, и гадать не будем. Числа слева — сколько раз строка нашлась в файлах сборки, это счётчик uniq -c, а не число слоёв.

lib/money.ts есть только в [app-ssr] и [app-client]: серверные компоненты его не импортируют, он пришёл вслед за Price. Страницы — только в [app-rsc]. Это та же заразность по импортам, только посчитанная сборщиком: всё ниже границы ушло в клиентские слои, а по другую сторону осталась ссылка. Граница режет граф, а не папки проекта: один и тот же файл лежит в нескольких слоях, если до него дотягиваются с разных сторон.

Итог разреза — манифест клиентских ссылок. В статье про свою границу читатель находил по строке I модуль и брал его из бандла через манифест. Вот манифест, строка I и кусок в настоящей сборке того же приложения:

$ npx next build

Через все три выдержки идёт одно число — 20501. В манифесте это id модуля ui/price.tsx и два куска, которые нужно загрузить. Строка 4:I[20501,[…]] в потоке несёт тот же id и те же куски — ровно то, что в статье про свою границу было упрощено до одного адреса. А кусок 0uk_002q-0_-r.js кладёт в массив globalThis.TURBOPACK функцию модуля с тем же номером: это реестр из статьи про свой сборщик, где этот кусок уже встречался.

Манифест пишет сборка, а не React: только она знает, в какие куски легли модули. В режиме webpack его пишет плагин Next — к этому вернёмся в разделе про webpack.

Граф на три слоя — много работы, и dev-сервер не делает её целиком. Он собирает то, что открыли в браузере, и не повторяет то, что уже сделал. Оба правила видны на модели. Ключ работы — файл, сторона и хеш содержимого; функция hash из статьи про свой сборщик едет в подложке. compile идёт по импортам от открытого маршрута, а на файле с "use client" отдаёт серверу заглушку и переходит на клиентскую сторону. Сторон в модели две, а не три слоя: для ключа этого хватает.

Прогноз: сколько работ насчитает первый заход на /, второй заход и заход после правки в money? И соберётся ли /admin?

declare function hash(text: string): string; // из статьи про свой сборщик, в подложке

const files: Record<string, string> = {
  "app/page.tsx": 'import "ui/price.tsx";',
  "app/admin/page.tsx": 'import "lib/db.ts";',
  "ui/price.tsx": '"use client";\nimport "lib/money.ts";',
  "lib/money.ts": "export const rub = (n) => n + ' ₽';",
  "lib/db.ts": "export const db = {};",
};
const done = new Set<string>(); // ключ работы — файл, сторона и хеш содержимого
let work = 0;

function compile(file: string, side: "server" | "client"): void {
  const text = files[file];
  const toClient = side === "server" && text.startsWith('"use client"');
  const key = `${file} [${side}${toClient ? ", заглушка" : ""}] ${hash(text)}`;
  if (!done.has(key)) { work++; done.add(key); }
  // на границе серверу достаётся заглушка, а сам файл уходит на клиентскую сторону
  if (toClient) return compile(file, "client");
  for (const [, dep] of text.matchAll(/import "([^"]+)"/g)) compile(dep, side);
}

const visitRoute = (route: string) => { work = 0; compile(route, "server"); return work; };
console.log("открыли /: работ", visitRoute("app/page.tsx"));
console.log([...done].map((key) => key.slice(0, key.lastIndexOf(" "))).join("; "));
console.log("ещё раз /: работ", visitRoute("app/page.tsx"));
files["lib/money.ts"] = files["lib/money.ts"].replace("₽", "руб.");
console.log("правка money, снова /: работ", visitRoute("app/page.tsx"));
console.log("/admin собирался:", [...done].some((key) => key.startsWith("app/admin")));

Четыре, ноль, одна. Первый заход прошёл страницу, заглушку Price для сервера, сам Price и money на клиентской стороне; клиентская сторона в модели одна, а в листинге слоёв ей соответствуют два слоя, [app-ssr] и [app-client]. Второй заход нашёл все четыре ключа в done. После правки новый хеш только у money, и новый ключ только у него: ключ Price собран из его собственного текста, а текст не менялся. Каскада из статьи про свой сборщик здесь нет — ключ работы не вписан ни в чей текст. /admin не собирался: туда никто не заходил.

Это модель ключа, ленивости и разреза, а не движок. У настоящего Turbopack кеш хранит результаты вплоть до отдельных функций, а куски собираются отдельно от компиляции модулей.

Настоящий dev-сервер ведёт себя так же. Лог next dev, пока в браузере открывали /, ещё раз / и потом /admin:

$ npx next dev -p 3600 -H 127.0.0.1

Строка GET /admin появилась только после захода на /admin — до него страница не собиралась. Первый GET / занял 848 мс, повторный — 19: собирать уже нечего, осталась отрисовка. Приложение крошечное, поэтому смотрите на порядок чисел, а не на сами числа.

Кеш переживает и перезапуск. В Next из этих листингов Turbopack по умолчанию пишет его на диск: для next dev — в .next/dev/cache/turbopack, для next build — в .next/cache/turbopack. Выключают это настройками experimental.turbopackFileSystemCacheForDev и experimental.turbopackFileSystemCacheForBuild. Вторая сборка того же приложения сразу после первой из начала статьи:

$ npx next build   # вторая подряд, .next/cache на месте

Compiled successfully in 134ms против 1502 мс у первой сборки: на порядок быстрее, и снова это порядок, а не замер. Выигрыш есть, только если .next/cache дожил до следующей сборки. Сборка в чистой папке — в CI или в слое сборки образа — кеша не находит и каждый раз идёт холодной, пока папку с кешем не сохранить и не вернуть явно. Тот же принцип — не делать работу, ключ которой уже есть, — встретится и для данных: в статье про свой кеш ключ собирают из того, что вошло в функцию.

Ни ленивость, ни кеш на диске Turbopack не придумал. next dev --webpack тоже собирает маршрут при первом заходе и хранит кеш webpack в .next/dev/cache/webpack. Чем Turbopack отличается на самом деле, разберём в разделе про webpack.

Vite тоже держит dev-сервер и тоже собирает проект, но в разработке отдаёт код иначе. Сравнивать число скриптов на странице бессмысленно: ниже два разных проекта — приложение Next из этой статьи и шаблон Vite с картинками и стилями. Сравнивать стоит другое — сколько модулей проекта приходит одним ответом сервера. Прогноз: у какого инструмента в одном файле dev-сервера окажется больше одного модуля проекта?

$ npx next dev -p 3600 -H 127.0.0.1
# страница / открыта в Chrome, ответы сняты по протоколу отладки Chrome

$ npx vite --port 3600
# страница открыта в Chrome; потом npx vite build && npx vite preview --port 3600 — и снова

У Vite в разработке один ответ — один модуль. /src/main.tsx и /src/App.tsx пришли отдельно, и даже index.css с App.css — отдельными ответами. Склеены заранее только зависимости: react.js в /node_modules/.vite/deps/ — один ответ на весь пакет. У Next в том же режиме куски: в одном _0ngubum._.js шесть модулей, среди них lib/money.ts и ui/price.tsx. А после vite build скрипт на странице один: бандл Vite собирает только на сборке.

Отдаваемый модуль Vite переписывает на лету. Начало main.tsx, каким его получает браузер, уже было в статье про компилятор файла: голые имена пакетов заменены адресами в /node_modules/.vite/deps/, импорт App стал адресом /src/App.tsx — за ним браузер придёт следующим запросом, — а в хвосте встроена карта кода:

$ curl http://127.0.0.1:3600/src/main.tsx

Горячая замена, последняя строка таблицы из статьи про фреймворки, видна в обоих списках: у Vite это /@vite/client и /@react-refresh, у Next — куски hmr-client. В списке ответов vite preview этих запросов уже нет, а среди кусков next build из начала статьи нет кусков hmr-client.

Почему Turbopack бандлит и в разработке, объясняет его документация: отдавать нативные модули по одному хорошо на маленьком приложении, а большое замедляет число запросов. По той же причине у самого Vite появился экспериментальный режим разработки с бандлом. А если серверная половина Next вашему приложению не нужна, Vite с роутером — честный выбор.

$ npm create vite@9.2.1 vite-app -- --template react-ts --no-interactive && cd vite-app && npm i && npm run build

До Turbopack Next собирался webpack-ом, и с флагом --webpack собирается им до сих пор. Устроен webpack проще, чем выглядят его конфиги. Конфиг называет точки входа, и webpack обходит граф сразу от всех: в глубину, с пометкой пройденных файлов, как свой сборщик, только входов несколько. Каждый файл проходит цепочку лоадеров из правил module.rules. Лоадер — функция над текстом файла, и в конце цепочки должен получиться JavaScript: так webpack делает модуль из чего угодно, от картинки до TypeScript, и так же зовёт компилятор файла — babel-loader отдаёт текст Babel.

Всё остальное делают плагины. Плагин — объект с методом apply(compiler): webpack передаёт ему компилятор, и плагин подписывается на его события — hooks.beforeCompile.tap до компиляции, hooks.emit.tap перед записью файлов — и получает внутренние объекты сборки. По словам README webpack, этим же интерфейсом сделана большая часть возможностей самого webpack. apply здесь — просто имя метода, который зовёт webpack, а не apply функции: plugin.apply(compiler) — обычный вызов метода с одним аргументом.

Модель ниже — проект из модели Turbopack, только вместо компонента картинка ui/logo.svg. hook — событие: плагин подписывается через tap, компилятор зовёт подписчиков через call. webpack() подключает плагины, объявляет beforeCompile, собирает граф от всех точек входа через лоадеры и объявляет emit. Имена — как у настоящего API. Прогноз: что напечатается раньше, beforeCompile или emit, и попадёт ли в сборку app/admin/page.js, если в браузере открыта только /?

// проект из модели Turbopack, только вместо компонента — картинка; файлы — строки
const files = {
  "app/page.js": 'import "ui/logo.svg";\nimport "lib/money.js";',
  "app/admin/page.js": 'import "lib/db.js";',
  "ui/logo.svg": "<svg><title>logo</title></svg>",
  "lib/money.js": "export const rub = (n) => n + ' ₽';",
  "lib/db.js": "export const db = {};",
};
// событие компилятора: плагин подписывается через tap, компилятор зовёт call
const hook = (taps = []) => ({ tap: (name, fn) => taps.push(fn), call: (arg) => taps.forEach((fn) => fn(arg)) });

function webpack({ entry, rules, plugins }) {
  const compiler = { hooks: { beforeCompile: hook(), emit: hook() } };
  plugins.forEach((plugin) => plugin.apply(compiler));
  compiler.hooks.beforeCompile.call();
  const modules = {};
  const build = (file) => {
    if (file in modules) return;
    // лоадеры правила — цепочка функций над текстом файла, справа налево
    const loaders = rules.find((rule) => rule.test.test(file))?.use ?? [];
    modules[file] = loaders.reduceRight((text, loader) => loader(text), files[file]);
    for (const [, dep] of modules[file].matchAll(/import "([^"]+)"/g)) build(dep);
  };
  Object.values(entry).forEach(build); // весь граф от всех точек входа — сразу
  compiler.hooks.emit.call({ modules });
  return modules;
}

const svgLoader = (source) => `export default ${JSON.stringify(source)};`;
const reportPlugin = {
  apply(compiler) {
    compiler.hooks.beforeCompile.tap("Report", () => console.log("beforeCompile"));
    compiler.hooks.emit.tap("Report", ({ modules }) => console.log("emit:", Object.keys(modules).join(", ")));
  },
};

const modules = webpack({
  entry: { page: "app/page.js", admin: "app/admin/page.js" },
  rules: [{ test: /\.svg$/, use: [svgLoader] }],
  plugins: [reportPlugin],
});
console.log(modules["ui/logo.svg"]);

И сразу оговорка, без которой сравнение webpack с моделью Turbopack соврёт. Next на webpack в разработке всё подряд не собирает: он сам добавляет страницу в компиляцию при первом заходе на неё и хранит кеш webpack на диске, а webpack в режиме наблюдения пересобирает только изменённый модуль. Голый dev-сервер webpack держит собранное в памяти и умеет слать браузеру горячие обновления, а Next в режиме --webpack пишет сборку на диск, в .next/dev. Разница с Turbopack не «лениво против сразу», а в том, где живут ленивость и кеш.

Где они живут у Next на webpack, видно через функцию webpack() в next.config.ts. Next с самого начала собирался webpack-ом, а вскоре отдал его настройку наружу этой функцией — туда и дописывают свои лоадеры и плагины. Функция ниже ничего не меняет, только печатает, для какого компилятора её позвали и сколько у него плагинов:

$ cat next.config.ts

Функция вызвана трижды: для сервера на Node, для сервера в среде edge — урезанной, без половины API Node, — и для браузера. Это три компилятора webpack, и у каждого свой список плагинов и свой кеш — три папки в .next/cache/webpack. Большая часть плагинов в этих списках — код самого Next, хотя есть и встроенные плагины webpack вроде DefinePlugin. Манифест клиентских ссылок из раздела про один граф в этом режиме пишет плагин Next ClientReferenceManifestPlugin в компиляторе браузера. Ленивость Next достраивает поверх трёх компиляторов, а каждая пересборка — новый проход компиляции со всеми событиями плагинов.

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

Что из мира webpack Turbopack понимает? Лоадеры — да. Он исполняет их библиотекой loader-runner из проекта webpack — так пишет документация turbopack.rules, — а вписывают их в конфиг, как в следующем разделе. Ограничения два: годятся только лоадеры, которые возвращают JavaScript, а их опции — только данные, то есть примитивы, объекты и массивы, но не функции и не модули через require(). Лоадеры, которые команда Next проверила, перечислены в той же документации. Плагины — нет. Плагин написан против событий и объектов компилятора webpack, как reportPlugin в модели, а у Turbopack таких событий нет. Документация говорит прямо: плагины webpack не поддерживаются, функция webpack() из next.config не читается. У части плагинов есть замена настройкой самого Next — например, у DefinePlugin, — но это другой механизм, а не тот же плагин под Turbopack; такие замены разбирает последняя статья главы.

Отсюда ошибка, которую Next печатает, найдя в конфиге функцию webpack() без ключа turbopack:

# next.config.ts: const nextConfig = { webpack: (config) => config };
$ npx next build

Сборка упала, и next dev с таким конфигом тоже не работает: напечатает Ready, следом ту же ошибку и завершится. Выхода три, и выбирают по тому, что лежит в webpack().

Третий выход коварнее, чем выглядит. Руководство по переходу на 16-ю версию предлагает флаг --turbopack, подсказка TIP в самой ошибке — пустой turbopack: {}. Та же функция-счётчик, в конфиг дописан пустой ключ:

$ # в next.config.ts первой строкой объекта добавлено turbopack: {}
$ rm -rf .next && npx next build | tee ../build-turbopack-fn.log

Сборка зелёная, а функция не вызвана ни разу; с флагом --turbopack без ключа — так же. Вместе с плагинами молча пропадают и вписанные в webpack() лоадеры и алиасы, поэтому этот выход годится, только если из функции действительно ничего не нужно. Если ключ webpack добавила чужая обёртка конфига — об этом строка NOTE в ошибке, — это ещё не довод, что он лишний: сначала посмотрите, что обёртка туда кладёт.

И последнее имя из этого мира — Rspack: сборщик с API webpack, написанный на Rust. Когда он уместен и что переедет в него из webpack.config, разбирает та же последняя статья главы.

Лоадер переезжает в turbopack.rules. Конфиг ниже собран из двух примеров документации Next: @svgr/webpack делает из файла .svg компонент React, а алиас в resolveAlias подменяет пакет — импорт underscore загрузит lodash. Страница админки пользуется обоими:

$ cat next.config.ts

Правило в rules выбирает файлы не регуляркой, как test у webpack, а шаблоном имени — "*.svg". loaders — та же цепочка, что в use. А as: "*.js" велит обрабатывать результат лоадера как файл .js: лоадер вернул модуль, а не картинку. Без этой строки Turbopack попробует разобрать вывод лоадера как SVG и остановит сборку ошибкой Processing image failed. В собранной странице картинка стала разметкой svg, а версия пришла из lodash, хотя в импорте написано underscore.

Babel в rules вписывать не нужно: если в проекте найдётся babel-конфиг, Turbopack включит Babel сам — что при этом печатает лог и когда такой файл лучше удалить, разобрано в статье про компилятор файла.

Главное место, где Babel в Next всё ещё нужен, — React Compiler. Флаг reactCompiler включает его как плагин Babel из пакета babel-plugin-react-compiler. У Turbopack есть экспериментальный порт компилятора на Rust, которому этот пакет не нужен. Включается он второй настройкой рядом с первой — так в документации:

// next.config.ts — как в документации turbopackRustReactCompiler
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  reactCompiler: true,
  experimental: {
    turbopackRustReactCompiler: true,
  },
};

export default nextConfig;

$ npx next build   # babel-plugin-react-compiler не установлен

С обеими настройками сборка прошла без пакета Babel, и лог честно предупреждает об эксперименте. Кусок с Price читается так же, как в статье про React Compiler: o=(0,r.c)(8) заводит восемь ячеек кеша, а проверки o[0]!==_ пересчитывают значение, только когда поменялся вход. Новое здесь — не сам кеш, а то, что его поставил Turbopack, а не Babel. Без второй настройки тот же конфиг ищет Babel-плагин и падает. Порт работает только под Turbopack: с --webpack, по документации, эта настройка — ошибка.

Ещё две вещи в Next пришли из Vite: import.meta.env с полями вроде DEV, PROD и MODE и import.meta.glob работают только под Turbopack, а переменные VITE_ Next не читает.