Налаштування Turborepo Monorepo: паралельна збірка, кешування та CI

Допустимо, ваш білд фронтенду триває 12 хвилин, а бекенд і фронтенд у різних репозиторіях. Загальний код дублюється, задачі CI виконуються послідовно. Це типова ситуація, яку ми вирішуємо налаштуванням Turborepo monorepo. Ми стикалися з проєктами, де збірка займала 30 хвилин, і Turborepo скоротив це до 5. Правильна конфігурація скорочує час збірки в 3–5 разів за рахунок паралелізації та кешування. Після впровадження клієнти скорочують витрати на CI-інфраструктуру на суттєву суму. Ми гарантуємо, що ваш проєкт збиратиметься швидше.

Коли варто обирати Turborepo?

npm/yarn/pnpm workspaces вже дають monorepo-структуру, але Turborepo додає паралельний запуск з урахуванням залежностей, інкрементальний кеш (локальний і віддалений) та граф задач. Якщо проєкт невеликий (2–3 пакети) — workspaces достатньо. При 5+ пакетах і CI/CD Turborepo починає економити реальний час. Порівняння: при 10 пакетах Turborepo в 4 рази швидше ручної паралелізації за рахунок автоматичного виведення порядку збірки.

Чому Turborepo, а не Nx?

Turborepo легший: немає потреби в генераторах коду та плагінах. Достатньо turbo.json і workspace-протоколу. Це ідеальний вибір для команд, які хочуть monorepo без надмірності. Nx пропонує більше функцій, але Turborepo виграє в простоті налаштування та швидкості роботи.

Структура проєкту

my-project/
├── apps/
│   ├── web/          # Next.js фронтенд
│   ├── admin/        # Vite + React admin panel
│   └── api/          # Node.js/Express backend
├── packages/
│   ├── ui/           # загальні React-компоненти
│   ├── config/
│   │   ├── eslint/       # конфіг ESLint
│   │   ├── typescript/   # базові tsconfig
│   │   └── tailwind/     # tailwind preset
│   ├── utils/        # загальні утиліти (formatDate, etc.)
│   └── types/        # загальні TypeScript-типи
├── package.json          # workspaces declaration
├── turbo.json            # конфігурація Turborepo
└── pnpm-workspace.yaml   # якщо використовуємо pnpm

Чому віддалений кеш критичний для CI?

Локальний кеш працює тільки на одній машині. Для команди і CI потрібен remote cache. Vercel Remote Cache — безплатно для опенсорсу, платно для приватних. Self-hosted варіант через turborepo-remote-cache:

---
# docker-compose.yml для remote cache сервера
services:
  turbo-cache:
    image: ducktors/turborepo-remote-cache:latest
    ports:
      - "3000:3000"
    environment:
      TURBO_TOKEN: "your-secret-token"
      STORAGE_PROVIDER: "s3"
      S3_BUCKET: "turbo-cache-bucket"
      AWS_ACCESS_KEY_ID: "${AWS_ACCESS_KEY_ID}"
      AWS_SECRET_ACCESS_KEY: "${AWS_SECRET_ACCESS_KEY}"

Таблиця 1: Порівняння кешування: локальний vs віддалений

Таблиця 2: Порівняння інструментів monorepo

Конфігурація turbo.json

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": [".env"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "package.json", "tsconfig.json"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
      "env": ["NODE_ENV", "API_URL"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {
      "inputs": ["src/**", "*.ts", "*.tsx", ".eslintrc*"],
      "outputs": []
    },
    "typecheck": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "tsconfig.json"],
      "outputs": []
    },
    "test": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "test/**", "vitest.config.*"],
      "outputs": ["coverage/**"],
      "env": ["TEST_DATABASE_URL"]
    },
    "test:e2e": {
      "dependsOn": ["build"],
      "inputs": ["e2e/**", "playwright.config.*"],
      "outputs": ["test-results/**"],
      "cache": false
    },
    "db:generate": {
      "cache": false,
      "inputs": ["prisma/schema.prisma"]
    }
  }
}

Налаштування пакетів та загальні конфіги

// packages/ui/package.json
{
  "name": "@acme/ui",
  "version": "0.0.0",
  "private": true,
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    },
    "./styles": "./dist/styles.css"
  },
  "scripts": {
    "build": "tsup src/index.ts --format esm --dts",
    "dev": "tsup src/index.ts --format esm --dts --watch"
  },
  "devDependencies": {
    "@acme/eslint-config": "*",
    "@acme/typescript-config": "*",
    "tsup": "^8.0.0"
  },
  "peerDependencies": {
    "react": "^18.0.0"
  }
}

Як налаштувати CI з Turborepo?

---
# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  ci:
    runs-on: ubuntu-latest
    env:
      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
      TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2
      - uses: pnpm/action-setup@v3
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm turbo lint typecheck test --filter=...[HEAD^1]
      - run: pnpm turbo build

Типові помилки та їх вирішення

• Не вказали env у pipeline — кеш видає старі значення.
• Забули persistent: true для dev — watcher не запускається.
• Circular dependencies — перевіряйте граф залежностей.
• Відсутність fetch-depth: 2 у CI — фільтр ...[HEAD^1] не працює.
• Неправильне налаштування віддаленого кешу — переконайтеся, що TURBO_TOKEN і TURBO_TEAM встановлені.

Процес налаштування Turborepo під ключ

Ми проводимо повний цикл: аудит поточної архітектури, проєктування структури monorepo, налаштування turbo.json, створення загальних пакетів (TypeScript, ESLint, Tailwind), розгортання віддаленого кешу на S3, інтеграція з CI/CD, написання документації та навчання команди. Результат: збірка в 3–5 разів швидше, кешування на CI, єдина кодова база. Економія часу розробки може досягати 80%. Отримайте консультацію нашого інженера — ми допоможемо прискорити ваш CI.

Терміни та економія

Налаштування з нуля для проєкту з 5–8 пакетами займає два-три дні. Перенесення існуючого проєкту в monorepo — близько тижня. Вартість розраховується індивідуально залежно від складності та кількості пакетів. Гарантуємо підтримку після запуску. Наш досвід — понад 50 monorepo-проєктів, сім років у веб-розробці.

Як Turborepo прискорює збірку?

Паралелізація задач на основі графа залежностей дозволяє запускати незалежні задачі одночасно. Кешування результатів (локальне і віддалене) пропускає перезбірку незмінених пакетів. Вбудований фільтр --filter запускає задачі тільки для змінених пакетів та їх залежностей. За даними офіційної документації Turborepo, паралелізація скорочує час збірки до 5 разів.

Чому remote cache обов'язковий для команди?

Без віддаленого кешу кожен розробник і CI-сервер збирають одні й ті самі пакети заново. Self-hosted remote cache на S3 або MinIO синхронізує кеш між усіма учасниками. Налаштування займає пару годин, але економить години збірки щодня. Для комерційних проєктів ми рекомендуємо self-hosted рішення — воно дає повний контроль і не залежить від зовнішнього провайдера.

Висновок

Turborepo — ефективний інструмент для прискорення CI та спрощення роботи з monorepo. Правильне налаштування з віддаленим кешем і грамотним pipeline приносить відчутну економію часу та ресурсів. Ми готові допомогти з впровадженням — зв'яжіться для консультації.