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/**"]
}

На співбесіді запитають#