Turborepo, монорепы и shared packages: как жить, когда фронтов уже пять
Текст написан с позиции июня 2023 года: так, как тема выглядела тогда, без технологий и событий, появившихся позже.
Есть довольно характерный момент в жизни любой фронтенд-команды, после которого старые привычки вдруг перестают работать. Пока у вас один продукт, один репозиторий и относительно линейная траектория развития, почти все кажется управляемым. Даже если внутри уже есть технический долг, он пока еще выглядит как локальная неприятность, а не как системная угроза. Потом появляется второй фронтенд. Затем третий. Затем отдельная админка, публичная витрина, внутренний кабинет, BFF-клиент, какой-нибудь docs-сайт, виджет для партнеров, white-label-версия, возможно, еще мобильный web-shell. И в какой-то момент команда с неприятной ясностью понимает: проблема уже не в том, как писать очередной React-код, а в том, как жить в мире, где фронтов стало несколько, а продуктовая скорость не собирается ждать, пока вы вручную синхронизируете button, eslint config и auth-utils между пятью репозиториями.
Именно здесь разговор про монорепы, shared packages и инструменты вроде Turborepo перестает быть модной инженерной темой «для платформенной команды» и становится очень земным вопросом выживания. Потому что как только фронтендов несколько, цена несогласованности начинает расти быстрее, чем сама кодовая база. Один продукт обновил дизайн-токены, второй отстал. В одном репозитории починили баг в общей библиотеке форм, в другом об этом никто не узнал. Третий живет на старом tsconfig, потому что «руки не дошли». Четвертый случайно тащит другую версию React Query или UI kit. Пятый уже переписал часть инфраструктуры и теперь плохо совместим со всеми остальными. Внешне все это еще можно назвать «экосистемой приложений». По сути это уже медленно расползающийся ландшафт локальных договоренностей.
На этом фоне монорепа начинает выглядеть не как прихоть любителей большого репозитория, а как попытка вернуть системе управляемость. А Turborepo — не как еще один инструмент ускорения сборки, а как довольно прагматичный ответ на вопрос: как сделать так, чтобы несколько приложений и пакетов жили в одной организационной реальности, не превращая ежедневную разработку в наказание? Но важно не свалиться в другую крайность. Как и почти любая хорошая инженерная идея, монорепа не является магическим решением. Она не убирает хаос, а меняет его форму. И самая вредная реакция на нее — услышать про единый репозиторий и решить, что это автоматический способ победить беспорядок. Команда, которая так думает, почти наверняка позже обнаружит, что хаос не исчез, а просто стал централизованным.
Именно поэтому говорить о Turborepo, монорепах и shared packages полезно без романтики. Не как о «правильной современной архитектуре», а как о наборе практических ответов на очень конкретную ситуацию: у вас уже не один фронт, а несколько; shared-код действительно нужен; скорость изменений важна; и теперь надо решить, хотите ли вы продолжать координировать все это через множество независимых репозиториев и ручные публикации, или все-таки пора признать, что экосистема приложений уже стала одной системой и заслуживает соответствующей формы.
Дорасти до монорепы — это не про размер кода, а про цену рассинхронизации
Одна из самых частых ошибок — начинать разговор о монорепе слишком рано или, наоборот, слишком поздно. Слишком рано — это когда команда видит два небольших проекта и заранее строит тяжелую платформенную архитектуру «на будущее», которое, возможно, никогда не наступит. Слишком поздно — это когда фронтов уже действительно пять, shared-код расползся по npm-пакетам, git submodule’ам, ручному copy-paste и внутренним вики, а люди продолжают делать вид, что это все еще просто «несколько независимых приложений».
Признаки зрелой потребности довольно понятны. Во-первых, у вас действительно есть повторяемый shared-код: UI kit, утилиты, типы, config-пакеты, API-clients, auth-слой, shared hooks, дизайн-токены, доменные модули, куски business logic. Во-вторых, этот код меняется не раз в полгода, а регулярно, и изменения должны доходить до нескольких приложений без недельной бюрократии. В-третьих, приложения развиваются разными командами или хотя бы разными потоками задач, но при этом не являются по-настоящему независимыми системами. В-четвертых, стоимость синхронизации между репозиториями уже заметна: обновление общих пакетов, согласование версий, поддержка одинаковых tooling-конфигов, одинаковых линтеров, тестовых окружений и сборочных правил начинает есть непропорционально много времени.
Когда эти признаки уже есть, монорепа перестает быть «архитектурной амбицией» и становится нормальной формой признания реальности. У вас уже одна распределенная frontend-система. Вопрос лишь в том, хотите ли вы продолжать симулировать независимость там, где ее давно нет.
Почему «просто публиковать shared packages» быстро перестает быть простым
Когда фронтов становится больше одного, первое естественное решение выглядит очень разумно. Общий код выносят в отдельные пакеты, публикуют во внутренний registry и подключают по версиям, как обычные зависимости. На небольшом масштабе это действительно работает. И именно потому так много команд задерживается в этой модели слишком долго.
Проблема в том, что публикация shared packages хорошо живет только там, где shared-слой действительно стабилен и редко меняется. Как только общая библиотека становится живой частью ежедневной разработки, цикл «изменил пакет — выпустил новую версию — обновил зависимость в приложении — убедился, что ничего не сломалось — повторил это еще для четырех клиентов» начинает ощущаться как лишний налог на любую кросс-продуктовую задачу. Особенно больно это становится, когда изменение проходит через несколько пакетов сразу или требует синхронного обновления приложения и общего модуля.
Появляется неприятный организационный эффект: разработчики начинают избегать улучшений shared-слоя, потому что цена доставки изменений слишком высока. Или, наоборот, начинают делать локальные обходы прямо в приложениях, потому что «потом некогда будет выпускать пакет». И вот в этот момент shared packages из источника порядка превращаются в источник трения. Не потому, что сама идея плохая, а потому что у нее есть предел масштабирования по частоте изменений.
Монорепа в этом смысле интересна тем, что она позволяет воспринимать изменение shared-кода и приложения как одно изменение системы, а не как цепочку внешних поставок между псевдонезависимыми сущностями.
Монорепа — это не про один git-репозиторий, а про единый цикл изменений
Очень полезно мысленно отделить два уровня. Есть внешний уровень: да, все живет в одном репозитории. Но это не самое важное. По-настоящему важна другая вещь: в монорепе несколько приложений и пакетов могут меняться в одном согласованном commit flow. То есть shared button, app-shell, docs-site и eslint-config не являются «чужими внешними зависимостями» друг для друга. Они становятся частями одной кодовой базы с одним жизненным циклом изменений.
Именно это дает монорепе настоящую силу. Вы можете менять shared package и сразу видеть, как это влияет на конкретное приложение. Вы можете рефакторить общий API пакета вместе с потребителями, а не выпускать ломающую версию в надежде, что остальные потом догонят. Вы можете централизованно держать tooling, typescript configs, eslint presets, prettier, CI-правила, test utilities и прочие вещи, которые в multi-repo мире слишком легко расползаются.
Поэтому хороший разговор о монорепе начинается не с обсуждения «удобно ли держать все в одном git», а с обсуждения того, нужен ли вам единый цикл координированных изменений. Если нужен, тогда монорепа — естественный кандидат. Если нет, то один большой репозиторий сам по себе ничего не починит: он лишь соберет в одном месте проблемы, которые раньше были разнесены по разным.
Где Turborepo попадает в реальную боль
Turborepo стал заметным именно потому, что очень точно попал в практический слой проблемы. Команды, которые уже признали необходимость монорепы, почти сразу сталкиваются с другой реальностью: как не сделать разработку в таком репозитории мучительной. Если в одном месте живут несколько приложений, несколько библиотек, тесты, линтинг, билд-пайплайны, Storybook, возможно, docs и набор служебных пакетов, простая команда «запусти все и проверь все» очень быстро становится слишком дорогой. Особенно в CI. Особенно в средних и крупных командах.
И вот здесь Turborepo выглядит очень прагматично. Он дает модель task orchestration, dependency graph между пакетами, кэширование и возможность запускать только то, что действительно затронуто. То есть он помогает монорепе не просто существовать как файловая структура, а быть рабочей системой, где изменения в одном пакете не заставляют бессмысленно пересобирать весь мир каждый раз.
Это важный момент. Потому что без такого слоя монорепа очень легко теряет часть своей привлекательности. Да, у вас теперь все вместе. Но если каждая локальная правка запускает полрепозитория, а CI стал в два раза медленнее, команда быстро перестанет романтизировать единое пространство. Turborepo ценен именно тем, что делает монорепу операционно выносимой.
Turborepo ускоряет сборку, но не проектирует архитектуру пакетов за вас
Это стоит проговорить особенно жестко. Очень легко поставить Turborepo, разложить код по папкам apps и packages, увидеть красивые кэши и решить, что экосистема теперь «правильно организована». На практике это всего лишь начало. Turborepo отлично помогает организовать сборку и выполнение задач. Но он никак автоматически не решает, какие именно shared packages вам нужны, где проходят границы между ними, что должно быть общим, а что должно оставаться локальным для конкретного приложения. Это не вопрос tooling, это вопрос архитектуры, и его за вас не закроет ни один кэш.
Если команда ошибается в самой модели shared-кода, монорепа лишь ускорит распространение этой ошибки. Можно очень быстро кэшировать плохо проведенные границы. Можно очень эффективно собирать пакеты, которые не должны были существовать в таком виде. Можно централизованно поддерживать общий модуль, который на самом деле является полупродуктовой свалкой из случайных утилит. И все это будет выглядеть «современно», пока не начнет болезненно ограничивать развитие приложений.
Поэтому Turborepo — это инструмент для операционной дисциплины, а не замена архитектурного мышления. Он помогает жить в монорепе. Но сначала еще нужно понять, что именно у вас должно в ней жить и как.
Самая частая ошибка: тащить в shared packages все, что повторилось дважды
Как только появляется монорепа, у команды почти неизбежно включается рефлекс «раз это повторяется, надо вынести в общий пакет». На словах это звучит как забота о порядке. На практике очень часто становится источником нового хаоса. Потому что повторяемость сама по себе еще не означает, что сущность созрела до статуса shared. Совпадение двух экранов — это не общность, а пока лишь совпадение.
Например, два приложения используют похожий виджет выбора периода. Это еще не значит, что пора создавать @company/date-range-widget. Возможно, сходство временное. Возможно, один из них скоро эволюционирует в другую сторону. Возможно, у виджета пока нет устойчивого API. То же самое касается бизнес-логики, API-клиентов, кусков domain code, даже hooks и util-функций. Преждевременное вынесение в shared package часто делает код менее гибким, а не более. Вы фиксируете не зрелый общий примитив, а случайное текущее пересечение потребностей.
Это особенно опасно в монорепе, потому что барьер вынесения сильно ниже. Не нужно создавать отдельный репозиторий, настраивать публикацию и думать о versioning. Достаточно создать папку в packages. И именно поэтому дисциплина должна быть строже, а не слабее. Чем дешевле вынести код в общий слой, тем дороже потом обходится каждая поспешно проведенная граница. Shared packages должны появляться там, где повторяемость уже устойчива по смыслу, а не просто видна глазами на двух экранах.
Какие shared packages действительно почти неизбежны
При этом не стоит впадать и в обратную крайность, будто shared packages — зло. Есть классы пакетов, которые в мире нескольких фронтов почти всегда оказываются оправданными. Во-первых, это infrastructural configs: eslint config, tsconfig presets, prettier, возможно, shared jest/vitest setup, build presets. Во-вторых, дизайн-системный слой: tokens, базовые UI primitives, иконки, theme contracts, общие styling utilities. В-третьих, cross-cutting utilities, действительно не привязанные к продукту: date formatting helpers, env abstractions, logger adapters, feature flag contracts, analytics adapters. В-четвертых, иногда — thin domain clients для взаимодействия с backend API, если несколько приложений действительно потребляют один и тот же контракт.
Заметим, что все эти пакеты имеют одну общую черту: они либо инфраструктурны, либо достаточно стабильны, либо действительно отражают общую реальность нескольких приложений. Они не являются случайным куском продукта, вытащенным «потому что жалко копировать». И именно это отличает здоровый shared package от токсичного.
Вообще полезный вопрос перед созданием пакета звучит так: это общее по природе или просто общее по текущему совпадению? Ответ очень часто отрезвляет.
Не путайте shared UI kit и shared product components
Это, пожалуй, одна из самых важных границ в frontend-монорепе. UI kit и product components — не одно и то же. Первый должен быть максимально независим от конкретного приложения. Это язык примитивов: кнопки, поля, layout-компоненты, базовые паттерны, токены, иконки, темы. Вторые уже почти всегда тянут за собой продуктовый смысл: UserSummaryCard, BillingBanner, PaymentMethodSelector, DashboardActivityFeed и так далее.
Ошибки начинаются, когда product components начинают преждевременно жить в shared packages на тех же правах, что и button или modal. Кажется, будто это тоже переиспользование. Но по факту библиотека начинает накапливать продуктовую историю разных команд в одном общем слое. Со временем такие пакеты становятся тяжеловесными, плохо обобщенными и очень чувствительными к локальным изменениям в одном из приложений.
Это не значит, что product-level shared code невозможен. Возможен. Но он требует куда большей осторожности. Продуктовый пакет должен появляться только там, где действительно есть общая бизнес-область и стабильный договор между приложениями. Иначе вы просто построите shared-свалку с красивым названием.
Главная недооцененная ценность монорепы — не общий код, а platform consistency
Есть один очень недооцененный плюс, который особенно заметен, когда фронтов уже не два, а пять. Монорепа помогает не только делить код, но и удерживать платформенную консистентность. То есть не просто общий UI или общие утилиты, а единый уровень инженерной среды: версии TypeScript, линтеров, тестовых библиотек, patterns для CI, conventions по naming, сборочные практики, policies по env variables, даже скрипты запуска и локальной разработки.
В multi-repo мире именно эта часть обычно разъезжается первой. И разъезжается тихо. Каждая команда обновляет зависимость «когда сможет». У каждого приложения своя версия ESLint rules. Кто-то уже перешел на новый ts target, кто-то нет. В одном репозитории строгое правило по import boundaries, в другом его отключили «на время». В результате экосистема фронтов перестает быть экосистемой. Она становится группой родственных, но все менее совместимых островов.
Монорепа возвращает ощущение, что у вас есть frontend-platform, а не просто набор случайных приложений. И для организации, где фронтов уже несколько, это очень часто ценнее, чем сам факт shared code.
Когда код лежит рядом, плохую границу нарушить — дело одного импорта
У единого пространства есть и неприятная сторона: если у вас плохие границы между пакетами, они будут нарушаться гораздо активнее, чем в multi-repo мире. Почему? Потому что доступность выше. Когда весь код живет рядом, всегда есть соблазн «быстро импортнуть нужную штуку оттуда», даже если с архитектурной точки зрения так делать не стоит. Внешний friction исчезает, а значит, дисциплина должна стать внутренней.
Поэтому хорошая монорепа почти всегда нуждается в явных import boundaries и договоре о зависимостях между пакетами. Какие пакеты инфраструктурные? Какие могут зависеть от каких? Какие части UI kit никогда не должны знать о продуктах? Может ли app-A импортировать продуктовый пакет app-B? Что считается запрещенной связностью? Если таких правил нет, единый репозиторий очень быстро превращается в огромное поле случайных прямых импортов, которые сначала кажутся удобными, а потом делают любую попытку разделить ответственность болезненной.
Тут и проявляется зрелость команды. Монорепа награждает дисциплину очень щедро, но хаос тоже масштабирует прекрасно.
Локальная разработка должна стать проще, а не «более централизованной»
Это важный критерий, который часто недооценивают. Если после перехода на монорепу и Turborepo локальная разработка для обычного разработчика стала тяжелее, значит что-то, скорее всего, пошло не так. В хорошем сценарии человек должен по-прежнему уметь быстро запускать только нужное приложение, быстро трогать shared package и сразу видеть эффект, не поднимая всю экосистему, и не страдать от того, что каждое изменение инициирует огромный pipeline «ради порядка».
Turborepo как раз силен там, где помогает это удержать: filter’ы задач, понимание зависимостей, инкрементальный запуск, кэширование — все это нужно не для красоты, а чтобы повседневная работа не ощущалась как работа в гигантской машине. Если же платформа начинает требовать от каждого фронтенд-разработчика держать в голове граф сборки, как DevOps-инженер, монорепа быстро потеряет часть поддержки внутри команды.
Вообще, один из лучших тестов на успешность монорепы звучит так: стало ли проще делать изменения поперек нескольких приложений, не усложнив обычную локальную задачу в одном приложении? Если ответ «да», направление выбрано правильно.
Версионирование в монорепе — это тоже вопрос философии
В multi-repo мире versioning shared packages — почти неизбежная реальность. В монорепе ситуация тоньше. Если пакеты публикуются наружу или потребляются вне репозитория, версии по-прежнему важны. Но если большая часть shared packages используется только внутри монорепы, команда получает возможность не превращать каждое внутреннее изменение в ceremony вокруг semver. Это большой плюс, но он требует ясности.
Нужно понимать, какие пакеты являются truly publishable artifacts, а какие — просто организационные модули внутри одной кодовой базы. Если не различать эти два типа, возникают две крайности. Либо все начинает жить как будто это внешняя библиотека с тяжелым versioning, что тормозит развитие. Либо все становится «просто внутренним», и команда теряет дисциплину там, где на самом деле уже есть внешние контракты.
То есть монорепа не отменяет вопрос версий, но делает его более контекстным. И это хорошо: меньше ритуала там, где он не нужен, и больше ясности там, где контракт действительно важен.
Когда монорепа может быть плохой идеей
Несмотря на всю пользу, монорепа не является универсальным благом. Есть ситуации, где она действительно может быть лишней. Например, если приложения по-настоящему независимы: разные команды, разные циклы релизов, разная предметная область, минимум shared code и мало смысла в совместных изменениях. Или если shared-слой очень мал и достаточно стабилен, чтобы жить как несколько опубликованных пакетов без заметного трения. Или если организация пока не готова к платформенной дисциплине, но уже хочет «как у больших» — тогда единый репозиторий легко превращается в централизованный беспорядок.
То же самое касается команд, которые романтизируют Turborepo как замену архитектуре. Если нет ясного понимания границ пакетов, правил зависимостей и модели shared code, перенос всего в монорепу даст лишь новые инструменты для ускорения плохих решений. Это не причина не делать монорепу. Это причина делать ее не из моды, а из реальной потребности.
Главный диагностический вопрос тут простой: у вас уже есть одна система, которую вы искусственно держите в нескольких репозиториях, или у вас действительно несколько систем, которым просто иногда удобно делиться кодом? Это разные ситуации. И они заслуживают разных решений.
Самая здоровая цель — не красивый граф задач, а меньше координации руками
Если свести весь разговор к одному практическому критерию, то монорепа, shared packages и Turborepo оправданы там, где они реально уменьшают ручную координацию между фронтендами. Меньше ручных публикаций. Меньше ручных синхронизаций конфигов. Меньше ручного догоняния багфиксов в пяти репозиториях. Меньше ручного объяснения, какая версия общего пакета где стоит и почему она до сих пор не обновлена. Меньше ручной боли при изменениях, которые логически являются одним изменением системы.
Это очень хороший ориентир, потому что он не дает спору уйти в идеологию. Вас не должно волновать, насколько красиво выглядит граф задач или насколько современно звучит слово «монорепа». Вас должно волновать, уменьшилось ли количество человеческой координации там, где раньше ее было слишком много. Если да, значит система работает на вас. Если нет, возможно, вы просто сменили вывеску у старых сложностей.
Итог
Когда фронтов уже пять, проблема почти никогда не в том, что вам «не хватает еще одного пакета». Проблема в том, что экосистема приложений уже стала одной системой, а вы либо признали это архитектурно, либо еще нет. Монорепа в таком контексте — не модный выбор по умолчанию, а способ дать этой системе единый цикл изменений, единые platform rules и более управляемую жизнь shared-коду. Turborepo полезен не потому, что делает сборку модной, а потому что позволяет всей этой конструкции жить без чрезмерного операционного страдания. Shared packages ценны не потому, что все нужно выносить, а потому что действительно общие примитивы должны жить как общие примитивы, а не копироваться между приложениями из лени или страха перемен.
Но, как и в любой хорошей архитектурной теме, здесь нет автоматической победы. Монорепа не спасает от плохих границ. Turborepo не проектирует shared packages за команду. А единый репозиторий не превращает разрозненные продуктовые компромиссы в платформу только потому, что они теперь лежат в папке packages. Чтобы все это работало, нужна дисциплина: различать truly shared и случайно повторяющееся, отделять UI kit от продуктовых компонентов, держать import boundaries, не тащить в общий слой все подряд и строить локальную разработку так, чтобы она оставалась легкой.
Если же сформулировать главный практический вывод совсем прямо, он будет таким: когда фронтов уже пять, легче становится не от монорепы как таковой, а от того, что вы перестаете координировать руками то, что давно уже стало одной системой, — и если ручной координации не убавилось, значит вы просто переименовали старые сложности в новые технологические слова. Turborepo и shared packages хороши именно в этом качестве. Не как инженерная мода, а как способ признать реальность и сделать ее менее болезненной.