Монорепозитории: Turborepo, Nx и Lerna для JS-проектов. Организация кодовой базы с shared-модулями

Я веб-разработчик с 10-летним опытом. В этой статье я расскажу, как монорепозитории и инструменты вроде Turborepo, Nx и Lerna помогают управлять сложными JS-проектами, а также поделюсь практическими примерами организации shared-модулей.

Что такое монорепозитории и зачем они нужны?

Монорепозиторий это подход к организации кода, при котором несколько проектов или пакетов хранятся в одном репозитории. Например, веб-приложение, мобильное приложение, общие библиотеки и CLI-утилиты могут находиться в одной кодовой базе.

Преимущества:

• Единая зависимостей: Не нужно дублировать lodash в 10 разных местах.
• Shared-модули: Компоненты, утилиты и конфиги легко переиспользовать.
• Сквозные изменения: Рефакторинг затронет все проекты сразу.
• Упрощённый CI/CD: Тесты и деплой запускаются централизованно.

Недостатки:

• Сложность onboarding для новичков.
• Медленные команды, если не использовать кэширование.
• Риск превратить репозиторий в «свалку».

Из личного опыта: монорепозиторий спас наш стартап, когда нужно было синхронизировать 3 веб-приложения и 2 npm-пакета. Но без правильных инструментов это превратилось бы в ад.

Turborepo, Nx и Lerna: Обзор

Перед погружением в примеры, кратко о каждом инструменте:

1. Lerna

Пионер среди менеджеров монорепозиториев (2016). Основные функции:

• Управление версиями пакетов через lerna publish.
• Запуск команд в параллельных процессах (lerna run build).
• Связывание локальных пакетов через symlinks.

Минус: Нет кэширования, поэтому сборка всех пакетов с нуля каждый раз.

2. Turborepo

Современный инструмент от создателей Next.js (2021). Фичи:

• Молниеносное кэширование (до 85% ускорения).
• Интеграция с любым стеком: React, Vue, Svelte.
• Простая конфигурация через turbo.json.

3. Nx

Мощная экосистема для монорепозиториев и не только. Особенности:

• Плагины для React, Node.js, Angular и даже Go.
• Визуализация зависимостей между проектами.
• Distributed Task Execution для CI/CD.

Организация кодовой базы с shared-модулями

Главная причина использовать монорепозиторий возможность делиться кодом между проектами. Рассмотрим, как структурировать shared-модули в каждом инструменте.

Базовая структура папок

Рекомендую такую иерархию:

my-monorepo/  
├── apps/           # Приложения  
│   ├── web/        # Веб-клиент  
│   └── admin/      # Админка  
├── packages/       # Shared-модули  
│   ├── utils/      # Утилиты  
│   └── ui-kit/     # React-компоненты  
├── package.json  
└── turbo.json      # Конфиг Turborepo

Пример: создание shared-модуля utils

1. Инициализация пакета:

mkdir packages/utils && cd packages/utils  
npm init -y

2. package.json:

{
  "name": "@myproject/utils",
  "version": "1.0.0",
  "main": "index.js",
  "types": "index.d.ts"
}

3. Код модуля (index.ts):

export const formatPrice = (price: number) => 
  price.toLocaleString('en-US', { style: 'currency', currency: 'USD' });

4. Использование в приложении apps/web:

import { formatPrice } from '@myproject/utils'; 
console.log(formatPrice(100)); // $100.00  

Интеграция с инструментами

Turborepo

Добавьте в turbo.json:

{
  "pipeline": {
    "build": {
      "outputs": ["dist/**"],
      "dependsOn": ["^build"]
    },
    "dev": {
      "cache": false
    }
  }
}

Запуск сборки с кэшированием:

turbo run build

Nx

Создайте nx.json:

{
  "tasksRunnerOptions": {
    "default": {
      "runner": "nx/tasks-runners/default",
      "options": { "cacheableOperations": ["build", "test"] }
    }
  }
}

Запуск:

nx run-many --target=build --all

Lerna

Добавьте в lerna.json:

{
  "packages": ["apps/*", "packages/*"],
  "version": "independent",
  "npmClient": "yarn"
}

Сборка:

lerna run build --parallel

Сравнение Turborepo, Nx и Lerna

DTE (Distributed Task Execution) в Nx позволяет распределять задачи между CI-агентами.

Рекомендации для разработчиков

1. Стартапы. Выбирайте Turborepo, быстрое начало и минимум конфигурации.
2. Корпорации. Nx подойдёт для сложных систем с Angular/React и собственными плагинами.
3. Переезд с Lerna. Постепенно внедряйте Turborepo, используя lerna только для версионирования.

Совет из практики: Держите shared-модули независимыми от фреймворков. Наш ui-kit работает с React и Vue благодаря адаптерам.

Мой стек в 2025 году: Turborepo + TypeScript + pnpm для стартапов, Nx для enterprise.

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