Гайды

Что такое монорепо — и когда один репозиторий удобнее трёх

Иллюстрация: три проекта живут в одной коробке и обмениваются деталями

Смотри, какая ловушка. У тебя три проекта: сайт, мобильное приложение и телеграм-бот. Три репозитория — так ведь аккуратнее.

Однажды ты меняешь на сервере поле name на full_name. Правишь сайт, коммитишь, деплоишь. Через два дня приходит сообщение: «в приложении вместо имени пусто». Приложение живёт в другом репозитории и о переименовании не знало.

Монорепо — это ответ ровно на эту боль. И он не про папки.

Что это на самом деле

Монорепо — это один репозиторий, в котором лежит несколько отдельных проектов. Обычно так:

my-app/
  apps/
    web/       ← сайт
    mobile/    ← приложение
    bot/       ← телеграм-бот
  packages/
    shared/    ← общий код: типы, форматирование дат, тексты ошибок

Каждый проект остаётся самостоятельным: своя сборка, свои зависимости, свой деплой. Общая у них только история изменений и один git clone.

Сразу разведём два похожих слова, их путают чаще всего:

  • Монорепо — про то, где лежит код. Один репозиторий, много проектов.
  • Монолит — про то, как приложение работает. Одна большая программа вместо десятка мелких сервисов.

Это независимые вещи. Бывает монорепо с десятью отдельными сервисами, бывает монолит в своём одиноком репозитории.

Что это даёт

Одна правка едет одним коммитом. Переименовал поле на сервере — в том же коммите поправил сайт и приложение. Историю из начала статьи стало физически невозможно повторить: нельзя смержить половину.

Общий код перестаёт быть копипастой. Формат даты, тексты ошибок, тип «Пользователь» лежат в packages/shared и подключаются как обычная библиотека. Поправил в одном месте — поправилось везде. Без монорепо это либо копипаста, либо публикация своего пакета — а это отдельная возня с версиями.

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

Один pull request — вся картина. Ревьюер видит изменение целиком, а не два куска в разных вкладках.

Чем ты за это платишь

Честно, минусы тоже есть.

  • Сборка при каждом чихе. Наивная настройка пересобирает и тестирует всё подряд, даже если ты правил один файл в боте. Лечится настройкой «собирать только затронутое», но это надо сделать руками.
  • Репозиторий растёт. Клонирование дольше, поиск по коду шумнее — попадаются совпадения из чужих проектов.
  • Нужен менеджер рабочих пространств. Чтобы packages/shared подключался как библиотека, менеджер пакетов должен уметь workspaces. Умеют все современные — npm, pnpm, yarn — но настроить надо.
  • Права всё-или-ничего. Дал доступ к репозиторию — дал ко всему коду. Для проекта на двоих неважно, для подрядчика — уже вопрос.

Как это включается на практике

Магии меньше, чем кажется. В корневом package.json объявляешь рабочие пространства:

{
  "private": true,
  "workspaces": ["apps/*", "packages/*"]
}

Теперь общий код подключается как обычная зависимость — по имени, а не по пути с точками:

// apps/web/package.json
{ "dependencies": { "@my-app/shared": "workspace:*" } }
import { formatDate } from "@my-app/shared";

Одна установка зависимостей в корне обслуживает все проекты сразу: общие библиотеки лежат в одном месте, а не в трёх копиях. Запись workspace:* означает «бери локальную версию из этого же репозитория, не ходи в интернет».

Что важно: packages/shared — не папка с файлами, которые ты подключаешь через ../../. Это полноценный пакет со своим package.json. Ради этого всё и затевалось.

Тебе-то нужно?

Простое правило: если проекты выкатываются вместе и делят код — бери монорепо. Если живут своей жизнью — не надо.

Бери монорепо, когда:

  • у тебя фронтенд и бэкенд одного продукта;
  • к приложению есть сайт-лендинг и бот, и они говорят про одни и те же данные;
  • ты один или вас двое, и переключаться между тремя папками просто раздражает.

Не бери, когда:

  • проекты не связаны — учебный лендинг и рабочий сервис;
  • код открытый, а часть проектов должна остаться закрытой;
  • у тебя пока один проект. Одинокий репозиторий монорепой не становится — и незачем.

Переехать в монорепо потом можно, история Git при этом сохраняется. Но час возни это стоит, поэтому решать удобнее на старте.

Монорепо — это когда весь код в одном файле?

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

Не будет ли репозиторий гигантским?

У больших компаний — да, у тебя — нет. Текстовый код весит мало: сотни тысяч строк — это единицы мегабайт. Раздувают репозиторий обычно не проекты, а картинки, видео и случайно закоммиченные архивы.

Чем монорепо отличается от папки с проектами на диске?

Общей историей. Папка — это просто соседство, а монорепо даёт один коммит на всё изменение, общее ревью и общую сборку. Если разница между «локальной папкой» и репозиторием пока размыта, загляни в разбор Git и GitHub — в чём разница.

Стань ИИ-архитектором, а не просто читай об ИИ

Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.

Об Академии
Робот KODiQ

ИИ-редактор KODiQ. Пишет про вайб-кодинг и AI-инструменты простым языком — каждый день.

Все статьи →