Механика монорепо: pnpm workspaces, граф задач Turborepo и пакеты, заслужившие свою границу

pnpm workspaces: ссылки, а не копии

Прежде чем ставить Turborepo, стоит понять, что вообще даёт настоящие границы — а не просто организацию папок. Ответ — субстрат пакетного менеджера.

Субстрат — pnpm-workspace.yaml, объявляющий apps/* и packages/*. Каждый пакет держит настоящий package.json, а внутренние зависимости используют workspace-протокол — "@acme/ui": "workspace:*", — который pnpm разрешает в симлинк на локальный пакет и никогда — в реестр. Два свойства делают это субстратом границ, а не удобством. Первое: каждый пакет объявляет зависимости явно — package.json есть контракт границы, машинно проверяемый при установке. Второе: строгий, неплоский node_modules pnpm означает, что пакет может разрешить только то, что объявил, — классическая фантомная зависимость (импорт пакета, который случайно поставил поднятый сосед) падает сразу, вместо того чтобы работать в dev и взрываться позже при другом порядке установки. Монорепо на пакетном менеджере с хостингом — это папки; монорепо на pnpm — это проверяемые рёбра.

# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"

// apps/web/package.json — ребро объявлено, а не подразумевается
{
  "name": "web",
  "dependencies": {
    "@acme/ui": "workspace:*",
    "@acme/billing": "workspace:*",
    "next": "15.1.0"
  }
}

Граф задач — это граф кеша

Turborepo читает turbo.json и строит направленный граф задач: "build": { "dependsOn": ["^build"] } значит «моей сборке сначала нужны сборки моих зависимостей» — топологический порядок получается сам. Рычаг — в том, что происходит до запуска задачи: Turborepo считает контент-хеш по её входам — исходники пакета, хеши выходов задач-зависимостей, объявленные переменные окружения, релевантный срез lockfile и конфигурацию самой задачи. Хеш уже встречался: работа пропускается, кешированные выходы и захваченные логи проигрываются байт в байт. Хеш новый: задача выполняется и кешируется. Поскольку хеш выхода зависимости — вход хеша каждого зависимого, инвалидация распространяется ровно по стрелкам зависимостей — и больше никуда.

Честные цифры из репозитория в прологе: холодная полная сборка (девять пакетов, два Next.js-приложения) идёт 20–35 минут в CI. С удалённым кешем артефакты, ключованные хешами, живут в общем хранилище: CI собирает один раз, каждый другой раннер — и каждый ноутбук — проигрывает. Тёплый медианный PR: 4–7 минут, потому что выполняется только изменённый подграф; PR, не трогающий ничего собираемого, проигрывает всё меньше чем за минуту. Добавьте --filter=...[origin/main] — и CI вообще не рассматривает задачи вне затронутого подграфа. Ничто из этого не требует умного кеша. Это требует разрезаемого графа — а это свойство ваших границ пакетов, не Turborepo.

Извлечение пакетов: ui, config, домен

Что заслуживает извлечения из приложения: код, потребляемый двумя и более приложениями, тестируемый изолированно, владеющий своими зависимостями. Три архетипа покрывают большинство репозиториев. У packages/ui — дизайн-системы — есть настоящее решение: отдавать исходниками (пакет экспортирует сырые .tsx, и каждое Next.js-приложение указывает его в transpilePackages, чтобы компилятор приложения обработал его как собственный код) или пребилдом (пакет получает задачу сборки tsup/rollup, эмитящую dist/). Исходники выигрывают в скорости итерации: ноль конфигурации бандлера в пакете, и правка кнопки мгновенно хот-релоадится в каждом запущенном приложении. Цена симметрична: каждое потребляющее приложение перекомпилирует пакет при каждой сборке, и эта компиляция кешируется как часть сборки приложения, а не как собственная задача. Пребилд переворачивает обмен — сборка пакета кешируется и шарится, сборки приложений быстрее, внешняя публикация становится возможной — ценой конфигурации бандлера, оркестрации watch-режима и класса багов «в приложении A работает, в B — протухший dist». По умолчанию — исходники плюс transpilePackages; переключайтесь, когда заставит время сборки приложений или внешняя публикация.

// apps/web/next.config.js
module.exports = {
  transpilePackages: ['@acme/ui'], // компилировать внутренние пакеты-исходники
};

packages/config держит базы eslint-config и tsconfig, которые расширяет каждый пакет, — один PR обновления двигает весь репозиторий, дрейф становится структурно невозможным. Доменные пакеты в духе packages/billing — извлечение с наибольшей отдачей: чистый TypeScript без React, так что проверка типов и тесты бизнес-правил больше вообще не требуют сборки приложения.

Честно о версионировании

Внутренним пакетам версии не нужны. workspace:* означает, что версия — каждый коммит: потребители всегда компилируются против HEAD, нечего публиковать, нечего поднимать, не о чем спорить про semver на ревью. Changesets отрабатывают свою церемонию ровно в одном случае — когда пакет публикуется наружу (npm или приватный реестр) для потребителей вне workspace. Принятие changesets для чисто внутренних пакетов порождает PR с поднятием версий, которые не потребляет ни человек, ни машина: чистый процессный театр. Честное правило: workspace:* до дня, когда появится внешний потребитель, и changesets с этого дня — только для публикуемых пакетов.

Отдача — и god-пакет, который её стирает

Отдача границ накапливается в CI: turbo run typecheck test --filter=...[origin/main] означает, что PR в packages/billing гоняет проверки биллинга плюс двух приложений, которые его импортируют, — приложение docs и пять остальных пакетов проигрываются из кеша. Время проверки типов перестаёт расти с размером репозитория и начинает расти с радиусом поражения.

Провал — тот самый, из пролога, и его механизм стоит проговорить: packages/shared — utils, helpers, «common» — импортируется каждым пакетом. Его позиция в графе означает, что его хеш питает все остальные хеши; его природа свалки означает, что он меняется постоянно (70 процентов PR в репозитории из инцидента). Перемножьте: почти нулевые попадания в кеш, пересборки всего графа на каждое изменение и команда с выводом «монорепо замедлило CI», хотя замедлила топология графа. Обнаружение механическое — отрендерите граф пакетов (turbo умеет; dependency-cruiser — тоньше) и отслеживайте hit rate кеша на PR как первоклассную метрику CI. Лечение — распил по домену и частоте изменений: стабильные листья (@acme/result, @acme/dates) отдельно от горячей доменной логики, чтобы изменение биллинга перехешировало зависимых биллинга и никого больше. Культурное лечение важнее: больше никогда не позволяйте пакету называться shared или utils — таким именам нечем отказать новому экспорту. Теперь, когда CI монорепо начнёт ползти вверх, сначала отрисуйте граф зависимостей — скорее всего, один пакет лежит под всем деревом и меняется в каждом втором PR.