React-монорепозитории: Turborepo, pnpm workspaces и публикация UI-кита

Зачем это нужно#

В крупномасштабных проектах разработка UI-компонентов, утилит и конфигураций в изолированных полирепозиториях (отдельный Git-репозиторий на каждую библиотеку) приводит к организационному параличу:

• Редактирование компонента кнопки требует выпуска новой версии npm-пакета, ожидания сборки в CI, обновления версии в целевом приложении и локального npm link, чреватого рассинхронизацией зависимостей.
• Атомарные сквозные изменения (например, обновление контракта дизайн-системы с адаптацией всех продуктовых приложений) распадаются на цепочку из десятка PR, блокирующих релиз на дни.

Архитектура монорепозитория (Monorepo) на базе пакетного менеджера pnpm workspaces и оркестратора задач Turborepo устраняет эти барьеры.

Сочетание pnpm и Turborepo формирует современный промышленный стандарт:

1. Жесткая линковка зависимостей: Механизм симлинков и изолированного глобального хранилища (content-addressable store) в pnpm предотвращает эффект фантомных зависимостей (Phantom Dependencies), присущий npm и yarn.
2. Конвейер задач и кэширование Turborepo: Оркестратор строит направленный ациклический граф задач (DAG) и сохраняет артефакты сборки в локальный или удаленный кэш (Remote Cache), сводя повторные сборки к долям секунды.
3. Автоматизация релизов с Changesets: Управление семантическим версионированием (SemVer), генерация списков изменений (Changelog) и публикация пакетов в npm/GitHub Packages.

Ментальная модель#

В монорепозитории кодовая база логически разделена на исполняемые приложения (apps/*) и переиспользуемые разделяемые пакеты (packages/*):

┌──────────────────────────────────────────────────────────────────────────┐
│                            ROOT MONOREPO                                 │
│  pnpm-workspace.yaml  |  turbo.json  |  package.json                     │
└─────────────────────┬──────────────────────────────┬─────────────────────┘
                      │                              │
        ┌─────────────▼────────────┐   ┌─────────────▼────────────┐
        │        apps/web          │   │        apps/docs         │
        │      (Next.js 15+)       │   │       (Storybook)        │
        └─────────────┬────────────┘   └─────────────┬────────────┘
                      │ depends on:                  │ depends on:
                      │ - @repo/ui                   │ - @repo/ui
                      │ - @repo/tailwind-config      │ - @repo/tailwind-config
                      │                              │
        ┌─────────────┴──────────────────────────────┴────────────┐
        │                    SHARED PACKAGES                      │
        │                                                         │
        │  ┌───────────────────┐  ┌────────────────────────────┐  │
        │  │   @repo/ui        │  │   @repo/tailwind-config    │  │
        │  │  (React 19 Kit)   │  │   (Tailwind v4 Presets)    │  │
        │  └─────────┬─────────┘  └────────────────────────────┘  │
        │            │ depends on:                                │
        │  ┌─────────▼─────────┐  ┌────────────────────────────┐  │
        │  │   @repo/tsconfig  │  │   @repo/eslint-config      │  │
        │  │   (Strict TS)     │  │   (Shared Linting Rules)   │  │
        │  └───────────────────┘  └────────────────────────────┘  │
        └─────────────────────────────────────────────────────────┘

Когда разработчик запускает команду pnpm build, Turborepo:

1. Вычисляет хэш всех входных файлов (inputs), переменных окружения и зависимостей целевого пакета.
2. Проверяет наличие хэша в локальном кэше или удаленном бакете Remote Cache (Vercel/S3).
3. При совпадении хэша мгновенно восстанавливает директорию dist/ из кэша (>>> FULL TURBO), пропуская компиляцию TypeScript и бандлинг за 50 мс.

• pnpm workspaces
• Remote Caching
• Changesets
• tsup

На практике применяется#

1. Единая Enterprise дизайн-система: Пакет @company/ui потребляется одновременно веб-порталом на Next.js, мобильным клиентом на React Native и панелью администратора на Vite.
2. Мгновенный локальный Hot-Reload без предварительной сборки (Just-In-Time): Приложения импортируют исходный TypeScript-код пакетов напрямую во время разработки через экспорт source в package.json, исключая необходимость запускать watch-билд для каждого пакета.
3. Оптимизация CI/CD пайплайнов: В монорепозитории с десятками пакетов PR затрагивает только одну кнопку. Turborepo с флагом --filter=...[HEAD^1] запускает сборку и тесты строго для затронутого пакета и зависящих от него приложений.
4. Централизованное управление версиями зависимостей: Обновление с React 18 до React 19 происходит единовременно в корне монорепозитория через pnpm update -r react@latest, исключая версионный зоопарк.

Архитектура конвейера и глубокое погружение#

1. Конфигурация корневого монорепозитория#

packages:
  - 'apps/*'
  - 'packages/*'

Конфигурационный файл turbo.json определяет топологию конвейера сборки:

{
  "$schema": "https://turbo.build/schema.json",
  "ui": "tui",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$", ".env*"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "lint": {
      "dependsOn": ["^lint"]
    },
    "test": {
      "dependsOn": ["^build"],
      "inputs": ["src/**/*.tsx", "src/**/*.ts", "test/**/*.ts"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

• dependsOn: ["^build"]: символ ^ указывает топологическую зависимость: перед сборкой приложения apps/web Turborepo обязан сначала собрать все пакеты из packages/*, от которых оно зависит.
• cache: false, persistent: true: режим для долгоживущих dev-серверов.

2. Организация UI-пакета и строгие peerDependencies React 19#

Пакет компонентов @repo/ui не должен бандлить собственный экземпляр React. Вместо этого он объявляет react и react-dom в блоке peerDependencies:

{
  "name": "@repo/ui",
  "version": "1.4.0",
  "private": false,
  "type": "module",
  "exports": {
    "./button": {
      "types": "./dist/button.d.ts",
      "import": "./dist/button.js"
    },
    "./card": {
      "types": "./dist/card.d.ts",
      "import": "./dist/card.js"
    },
    "./styles.css": "./dist/index.css"
  },
  "scripts": {
    "build": "tsup src/index.ts src/button.tsx src/card.tsx --dts --format esm",
    "dev": "tsup src/index.ts --watch --dts --format esm",
    "lint": "eslint src/",
    "typecheck": "tsc --noEmit"
  },
  "peerDependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  },
  "devDependencies": {
    "@repo/tsconfig": "workspace:*",
    "@types/react": "^19.0.0",
    "@types/react-dom": "^19.0.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "tsup": "^8.3.5",
    "typescript": "^5.7.2"
  }
}

3. Автоматизация релизов с Changesets#

Сравнение пакетных менеджеров#

Готовый рабочий артефакт: Конфигурация сборщика tsup для энтерпрайз UI-кита#

Ниже представлен production-конфиг бандлера tsup для пакета дизайн-системы, формирующий изолированные tree-shakeable ESM-модули с типами и директивами React 19:

import { defineConfig, type Options } from 'tsup';

export default defineConfig((options: Options) => ({
  // Множественные точки входа для независимого tree-shaking
  entry: [
    'src/index.ts',
    'src/components/Button/index.ts',
    'src/components/Card/index.ts',
    'src/components/Modal/index.ts',
  ],
  format: ['esm'],
  dts: true,
  clean: !options.watch,
  sourcemap: true,
  minify: !options.watch,
  target: 'es2022',
  external: ['react', 'react-dom'],
  // Сохранение баннеров и директивы 'use client' для поддержки Next.js App Router
  banner: {
    js: "'use client';",
  },
  esbuildOptions(esbuildOptions) {
    esbuildOptions.jsx = 'automatic';
  },
}));

Распространённые ошибки (Pitfalls)#

// ❌ Антипаттерн: отсутствие явной зависимости в apps/web/package.json
{
  "name": "web",
  "dependencies": {
    "@repo/ui": "workspace:*"
    // lodash забыт, но локально работает из-за плоского hoisting!
  }
}

// ✅ Правильное решение: явное объявление всех прямых зависимостей
{
  "name": "web",
  "dependencies": {
    "@repo/ui": "workspace:*",
    "lodash": "^4.17.21"
  }
}

// ❌ Антипаттерн: любой коммит в markdown сбрасывает весь кэш сборки
"build": {
  "outputs": ["dist/**"]
}

// ✅ Правильное решение: точный перечень исходных файлов
"build": {
  "inputs": ["src/**", "package.json", "tsconfig.json"],
  "outputs": ["dist/**"]
}

На собеседовании спросят#