Монорепа для фронта и бэка: когда общий TypeScript-код действительно помогает
Текст написан с позиции декабря 2017 года: так, как тема выглядела тогда, без технологий и событий, появившихся позже.
Идея монорепозитория в JavaScript-мире долго звучала одновременно очень привлекательно и немного подозрительно. Привлекательно — потому что мысль держать фронтенд, бэкенд и общий код рядом кажется почти идеальной для команды, которая устала от дублирования типов, бесконечных расхождений в моделях данных и ручной синхронизации контрактов между клиентом и сервером. Подозрительно — потому что за красивой картинкой «все в одном месте» слишком часто скрывается новый слой организационной сложности, который на старте недооценивают.
Сейчас этот разговор стал особенно практическим. TypeScript уже воспринимается всерьез, Node.js давно вышел из статуса временной экзотики для серверных задач, фронтенд и бэкенд все чаще пишутся командами, которые говорят на одном техническом языке. И желание делить код между клиентом и сервером звучит уже не как теоретическая мечта, а как вполне конкретная цель. Но именно поэтому стоит сразу зафиксировать главное: вопрос о монорепе осмысленно ставить не в форме «хорошо это или плохо», а в форме «когда это действительно помогает».
Потому что сама по себе общая папка с несколькими пакетами еще не приносит пользы. Более того, она легко создает иллюзию архитектурного прогресса там, где на деле просто изменился способ хранения файлов. Самая вредная реакция на тему монорепы — услышать «fullstack на одном языке» и решить, что общий репозиторий сам по себе вылечит рассинхронизацию клиента и сервера. Не вылечит. Чтобы монорепа была не модным жестом, а реальным инженерным выигрышем, должны совпасть несколько условий, и самое важное из них касается не инструмента, а природы общего кода.
Сформулируем тезис, вокруг которого будет крутиться весь дальнейший разбор. Общий TypeScript-код помогает не тогда, когда команде просто хочется «объединить все», а тогда, когда между частями системы действительно есть устойчивые и честные точки пересечения. Все остальное — про то, как не перепутать эти две ситуации и не заплатить за чужую красивую картинку собственной поддержкой.
Близость файлов соблазняет смешивать слои, а не объединять знание
На словах разница между «общим» и «просто лежащим рядом» кажется очевидной. Но в реальной разработке очень легко перепутать удобство совместного репозитория с правом на произвольное смешивание слоев. Как только фронт и бэк оказываются рядом, появляется соблазн делить не только действительно общие типы и утилиты, но и куски логики, которые на самом деле принадлежат только одной стороне.
А дальше обнаруживается знакомая картина: серверный код неожиданно начинает диктовать форму клиенту, клиент тянет за собой зависимости, неуместные на сервере, а папка shared превращается в новый всемогущий серый слой проекта, где лежит все то, для чего никто не захотел честно определить дом. Монорепа обещает согласованность, но без дисциплины очень быстро начинает производить новую форму хаоса. Это и есть первая ловушка: близость в файловой системе создает ложное ощущение родства у кода, который на самом деле живет по разным законам.
Поэтому полезно сначала зафиксировать, в чем вообще состоит реальное обещание общего TypeScript-кода. Обычно под ним подразумевают несколько очень конкретных вещей: общие типы данных (сущности, DTO, структуры запросов и ответов, перечисления, идентификаторы, контракты между API и клиентом); небольшой слой действительно нейтральных утилит и функций преобразования, не привязанных к платформе; иногда — общую логику валидации или нормализации, если она обязана совпадать на обеих сторонах; и, наконец, общий язык модели предметной области, который перестает дублироваться в двух репозиториях разными руками.
Польза не в общей папке, а в том, что клиент и сервер перестают расходиться в описании мира
Реальная выгода появляется не в самом факте общей папки, а в том, что клиент и сервер перестают расходиться в описании мира. Это очень ощутимая боль, если команда уже пыталась жить без такого общего слоя. Сервер меняет форму ответа — фронтенд узнает об этом поздно. На клиенте появляется свой интерфейс пользователя, на сервере — свой, и через месяц они различаются не только полями, но и смыслом некоторых значений. Один enum меняется в одном проекте, а в другом остается старым.
Типизация есть и там, и там, но она защищает только внутреннюю согласованность каждого репозитория отдельно, не создавая общей правды между ними. В этом смысле монорепа с общими TypeScript-контрактами выглядит почти как естественный следующий шаг: раз мы уже умеем типизировать мир, почему бы не перестать описывать его дважды?
И вот здесь начинается одна из самых убедительных выгод. Когда фронт и бэк используют один и тот же источник типов для общих сущностей и API-контрактов, значительная часть расхождений исчезает не потому, что команда стала внимательнее, а потому, что почва для расхождения уменьшилась. Если изменился контракт ответа, это видно сразу. Если изменилась форма объекта, компилятор начинает шуметь по обе стороны. Если новый endpoint требует другую структуру запроса, клиент уже не может так легко притвориться, будто ничего не произошло. Для команды, которая работает быстро и часто меняет модель продукта, это серьезная экономия нервов и времени.
Общий код должен выражать общее знание, а не служить каналом утечки ответственности
Здесь же кроется и важная граница здравого смысла. Общий код помогает только тогда, когда он действительно выражает общее знание, а не служит каналом утечки ответственности. Общая структура пользователя или заказа — вполне разумная вещь. Общая типизация payload для API — тоже. А вот попытка вынести в shared клиентские селекторы, серверные сервисы, UI-ориентированные трансформации, специфичную для базы данных логику или любую платформенно-зависимую механику почти всегда означает, что команда путает «общий язык» с «общей логикой».
Монорепа опасна именно тем, что делает эту путаницу слишком удобной. Поэтому первый критерий успеха очень прост: общий TypeScript-код должен быть действительно платформенно-нейтральным. Если код не обязан знать, где он будет исполнен — на клиенте или на сервере, — у него есть шанс на честную общность. Если же код уже знает о DOM, браузерном окружении, Node API, HTTP-фреймворке, ORM, состоянии React-компонента или конкретном устройстве серверного приложения, его место, скорее всего, не в shared-слое.
Противопоставление здесь принципиальное: монорепа становится полезной не тогда, когда она стирает границы между слоями системы, а тогда, когда усиливает согласованность модели. Это два очень разных результата, которые внешне легко спутать, потому что оба начинаются со слов «давайте положим это в общий пакет».
Единая техническая поверхность не равна единой организационной реальности
Очень важна и организационная сторона. Без монорепы фронтенд и бэкенд часто живут с собственной инфраструктурой сборки, собственными зависимостями, собственными правилами проверки, тестирования и публикации. Монорепа обещает сделать это движение более согласованным: можно запускать общие проверки, синхронно обновлять общий пакет типов, легче видеть взаимосвязанные изменения. Для небольшой или средней команды это особенно приятно — меньше переключений между репозиториями, меньше технической бюрократии вокруг версионирования крошечных внутренних пакетов, меньше ритуалов для простого изменения контракта между клиентом и сервером.
Но и здесь реальная польза появляется не автоматически. Если фронтенд и бэкенд у команды живут в совершенно разном темпе, если у них разные циклы релизов, разные правила деплоя, разные люди, разные зависимости и довольно слабый общий слой, монорепа начинает мешать не меньше, чем помогать. Появляется единая техническая поверхность, но не обязательно единая организационная реальность.
Тогда любое изменение в общей инфраструктуре затрагивает слишком многих, а сам репозиторий становится большим не потому, что код действительно связан, а потому что исторически так сложилось. Общий репозиторий сам по себе не заменяет понимания того, насколько тесно живут части системы. И это понимание — а не выбор инструмента — обычно решает, окупится ли переход.
Лучший сигнал в пользу монорепы — один продуктовый поток, а не два независимых мира
Очень хороший сигнал в пользу монорепы — когда у команды действительно есть один продуктовый поток, а не два почти независимых мира. Один и тот же набор разработчиков активно меняет и клиент, и сервер. Контракты между ними часто эволюционируют. Модель данных общая и живая. Ошибки на границе фронта и бэка занимают заметную долю времени.
В таком случае выгода от общей типовой модели становится почти осязаемой. Изменение сущности или API-формы проходит через всю систему за один заход. Команда видит последствия целиком. Компилятор становится союзником не только внутри слоя, но и на стыке слоев. Это как раз тот случай, когда общий TypeScript-код помогает не абстрактно, а буквально каждый день.
Чуть менее очевидна, но тоже важна культурная выгода. Когда фронтенд и бэкенд начинают использовать общий язык типов и общую структуру монорепы, модель предметной области становится более явной. Спрятать расхождения за разными именами и локальными соглашениями уже сложнее. Если в проекте есть User, Order, Product, SearchResult, они перестают быть разными полуофициальными сущностями в головах двух команд и становятся частью общей словарной реальности проекта. Это кажется почти эстетической пользой, но эффект вполне прикладной: меньше недоговоренностей, меньше внутренних переводов с одного технического языка на другой, меньше неявной когнитивной работы на границе между слоями.
Общий тип не равен общей сущности во всех контекстах
При этом очень важно помнить: общий тип — не всегда то же самое, что общая сущность во всех контекстах. Это одна из самых коварных ловушек монорепы. Допустим, на сервере есть полная модель пользователя со всеми полями, внутренними флагами, служебными атрибутами и данными, которые клиент вообще не должен знать. На фронтенде же нужен только безопасный и публичный срез этой модели.
Если команда механически начинает использовать один «общий» тип пользователя везде, она рискует либо потащить на клиент лишнюю серверную реальность, либо искусственно урезать серверную модель ради удобства общего кода. Оба варианта плохи. Общий TypeScript-код должен помогать на границе, а не стирать смысловые различия между внутренними и внешними представлениями данных.
Именно поэтому самый зрелый shared-слой обычно довольно скромен. В нем живут контракты взаимодействия, общие схемы данных на стыке систем, небольшие нейтральные утилиты и иногда бизнес-правила, которые действительно обязаны быть едины в нескольких средах. Но он не должен становиться местом, где живет «почти все важное в проекте».
Хороший shared-слой должен быть не большим, а строгим
Разрастание shared — распространенная ошибка. Кажется, что раз монорепа позволяет делиться кодом без боли, значит, лучше вынести как можно больше наверх. На практике происходит обратное: чем агрессивнее команда растит shared-слой, тем выше риск, что он превратится в новый монолит внутри монорепы — очень удобный для импорта и очень неудобный для архитектуры.
Здесь почти буквально повторяется знакомая история с общим util.js, только на более крупном уровне. Если папка shared начинает означать «туда складываем все, что кажется полезным и может понадобиться где-то еще», монорепа перестает быть инструментом согласованности и становится просто новым складом с неясными границами. Хороший shared-слой должен быть не большим, а строгим. Попасть в него должно быть немного трудно: у кода должно быть ясное объяснение, почему он действительно общий, а не просто удобно вынесен.
Технически монорепа сегодня уже не выглядит чем-то невероятным. Экосистема JavaScript давно привыкла к пакетным менеджерам, workspace-подходам, внутренним пакетам и сборке из нескольких частей. То есть инструментальная почва для такой организации кода заметно зрелее, чем несколько лет назад. Но сама зрелость инструментария не гарантирует зрелости решений. Очень легко построить монорепу, в которой фронт и бэк вроде бы живут вместе, но реально лишь мешают друг другу: общие зависимости обновлять больно, тесты бегают неочевидно, сборка становится тяжеловесной, а shared-пакет обрастает всем подряд.
Монорепа — это не один репозиторий на все, а набор пакетов с направленными зависимостями
Второй критерий успеха — умение видеть в монорепе не «один репозиторий на все», а набор четко очерченных пакетов с ясными ролями. Полезно держать в голове примерно такую разбивку:
- фронтенд — отдельный пакет или приложение;
- бэкенд — отдельный пакет или приложение;
- общие контракты — отдельный пакет;
- при необходимости — отдельный пакет для чистых доменных утилит и валидаций, если они действительно платформенно-нейтральны.
И очень желательно, чтобы зависимости между этими частями были направленными и понятными. Клиент и сервер могут зависеть от общих типов, но shared не должен внезапно зависеть от клиента. Сервер не должен начинать неявно тянуть за собой UI-слой. Если эта дисциплина не удерживается, монорепа быстро становится запутаннее двух отдельных репозиториев.
Отдельная тема — сборка и скорость обратной связи. Один из главных аргументов против монорепы в практической жизни появляется тогда, когда она начинает тормозить не архитектурно, а буквально физически. Если любая маленькая правка в типах заставляет пересобирать слишком много, если локальная разработка становится тяжелой, если проверки запускаются неочевидно, если границы между пакетами формальны, а реальная работа с ними неудобна — энтузиазм быстро исчезает. Общий TypeScript-код помогает только тогда, когда не превращает каждое согласованное изменение в бюрократический марш по всей системе. Иначе команда начинает искать обходные пути, а они обычно и есть признак того, что архитектурная идея не совпала с повседневной реальностью.
Монорепа делает связанность честной — но только если она реально есть
Есть и более тонкий аргумент в пользу монорепы: она помогает бороться с ложной независимостью фронта и бэка там, где этой независимости в продукте на самом деле нет. Очень часто команды формально разводят клиент и сервер по разным репозиториям, будто это два независимых продукта, хотя в реальности они меняются почти синхронно и почти всегда обсуждаются вместе. В таком случае раздельность оказывается не свободой, а лишним административным слоем. Монорепа делает эту связанность честной: если части системы и так живут как одна эволюция, их совместное существование в одном техническом пространстве естественнее, чем постоянные танцы вокруг синхронизации.
Но честность работает и в обратную сторону. Если фронт и бэк действительно живут разной жизнью, обслуживаются разными циклами и имеют очень тонкую точку соприкосновения, монорепа может быть просто красивой избыточностью. Тогда общий TypeScript-код помогает лишь в ограниченном объеме, а цена общей инфраструктуры и совместного репозитория начинает перевешивать. Монорепа хороша не потому, что «fullstack на одном языке» звучит красиво, а потому, что она отражает реальную связанность системы. Если этой связанности мало, пользы тоже будет меньше, чем обещают статьи на эту тему.
Очень практичный вопрос, который стоит задать перед переходом, звучит так: что именно мы хотим перестать дублировать? Если ответ расплывчатый и сводится к чему-то вроде «ну, вообще код» — это плохой знак. Если же ответ конкретный (API-контракты, модели общих сущностей, схемы валидации, несколько чистых доменных функций) — тогда уже есть предмет для честного shared-слоя. Монорепа окупается именно там, где общность можно перечислить по именам, а не чувствовать романтически.
TypeScript здесь не фон, а катализатор
Почему этот разговор стал серьезнее именно сейчас? Потому что TypeScript играет в нем роль катализатора. Без него монорепа тоже возможна, но ее обещание звучит слабее. Просто положить фронт и бэк в один репозиторий можно и на обычном JavaScript, но там согласованность держится на внимательности людей, а не на механической проверке.
TypeScript же делает общие контракты материальными. Он позволяет shared-слою быть не только местом для импортов, но и системой проверяемых договоренностей. У команд появляется не просто общий язык, а общий типовой каркас для важнейших точек взаимодействия. Это сдвиг, а не революция: монорепа не становится правильным выбором сама по себе, но цена честного общего слоя заметно падает, когда за контрактами стоит компилятор.
Общим должно быть только то, что действительно общее
Самый честный вывод звучит так. Монорепа для фронта и бэка полезна не тогда, когда хочется держать все рядом из соображений порядка, и не тогда, когда есть иллюзия, что общий репозиторий автоматически решит проблему рассинхронизации. Она полезна тогда, когда у системы действительно есть значимый общий слой знаний, который должен эволюционировать согласованно, и когда команда готова строго охранять границы между shared-кодом и платформенно-специфичной логикой. В таком случае общий TypeScript-код реально работает: снижает дублирование, делает контракты явнее, ускоряет изменения на стыке фронта и бэка и дает команде более единый язык модели.
Во всех остальных случаях монорепа легко превращается просто в более крупный репозиторий с более крупными иллюзиями. А иллюзии архитектурного единства почти всегда стоят дороже, чем честная локальная раздельность. Поэтому вопрос не в том, стоит ли объединять фронт и бэк по моде времени. Вопрос в том, есть ли у вас общий код, который действительно заслуживает быть общим, и достаточно ли у команды дисциплины, чтобы этот слой не стал новой свалкой. Если общего по-настоящему мало, лучше признать это заранее, чем потом героически поддерживать монорепу, которая объединяет больше на бумаге, чем в реальной работе.
Объединяйте фронт и бэк в монорепу не ради красивого «fullstack на одном языке», а только тогда, когда у вас есть перечислимый по именам общий слой контрактов и достаточно дисциплины держать shared строгим — иначе вы меняете честную раздельность на дорогую иллюзию единства.