Архитектура монорепозитория: один репозиторий, много проектов

При создании платформы M-Smart School мы решили держать несколько приложений (админ-панель, интерфейс учителя, мобильный API, общую UI-библиотеку) в одном репозитории. Это монорепозиторий — много проектов в одном репо. Ниже — почему мы выбрали этот подход и как его построить, исходя из практики.

Что такое монорепозиторий?

Монорепозиторий — это архитектура, где несколько независимых проектов (приложения и библиотеки) живут в одном репозитории системы контроля версий. Обратный подход — каждый проект в отдельном репо — называется polyrepo.

Когда нужен монорепозиторий?

Монорепозиторий не всегда правильный выбор. Он силён в следующих случаях:

• Несколько приложений делят общий код (UI-компоненты, типы, утилиты)
• Типы фронтенда и бэкенда должны быть синхронны (end-to-end type safety)
• Одна команда параллельно развивает несколько связанных проектов

Структура

Типичная структура монорепозитория на Bun workspaces выглядит так:

my-monorepo/
├── apps/
│   ├── admin/          # Next.js admin panel
│   ├── api/            # Bun + Hono backend
│   └── mobile-api/
├── packages/
│   ├── ui/             # umumiy React komponentlar
│   ├── types/
│   └── config/
├── package.json
└── turbo.json

Определение workspaces

В корневом package.json объявляем workspace'ы:

{
  "name": "my-monorepo",
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "devDependencies": { "turbo": "^2.0.0" }
}

Ускорение с Turborepo

По мере роста монорепозитория сборка замедляется. Turborepo решает это кешированием и параллельным выполнением. turbo.json задаёт pipeline:

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": { "dependsOn": ["^build"], "outputs": [".next/**", "dist/**"] },
    "dev": { "cache": false, "persistent": true }
  }
}

Практический рабочий процесс

Команды запускаются из корня, а Turborepo сам определяет, какие пакеты пересобрать:

turbo dev
turbo build
turbo build --filter=admin

Плюсы и минусы

1. Плюс: с общими типами фронтенд и бэкенд никогда не «рассинхронизируются»
2. Плюс: изменение нескольких приложений в одном PR — атомарно и согласованно
3. Минус: настройка CI/CD сложнее — нужно деплоить только изменённое приложение
4. Минус: репо растёт, порог входа для новичка выше

Заключение

Если ваши проекты делят код и развиваются вместе, связка монорепозиторий + Turborepo сильна: type safety, атомарные изменения и быстрая сборка. Но будьте готовы платить сложностью CI/CD. Для нас в M-Smart School это был правильный выбор — но, как всегда, проверьте в своём контексте.