Настройка Monorepo (Turborepo) для веб-проекта

Настройка Monorepo (Turborepo) для веб-проекта

Turborepo — build system для monorepo от Vercel. Не менеджер пакетов и не линтер — именно инструмент для умного запуска задач с кешированием результатов. Главная идея: если входные файлы задачи не изменились, вывод берётся из кеша. На практике это означает turbo build за 3 секунды вместо 4 минут при повторном запуске.

Когда Turborepo, а не просто npm workspaces

npm/yarn/pnpm workspaces уже дают monorepo-структуру с общими зависимостями. Turborepo добавляет поверх них:

• Параллельный запуск с учётом зависимостей между пакетами
• Инкрементальный кеш (локальный + удалённый)
• Граф задач с явными зависимостями
• Фильтрацию: запустить только изменившиеся пакеты

Если проект небольшой (2–3 пакета) и команда маленькая — workspaces без Turbo достаточно. При 5+ пакетах и CI/CD — Turbo начинает экономить реальное время.

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

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

Инициализация

# Создаём новый monorepo
npx create-turbo@latest my-project
cd my-project

# Или добавляем Turbo в существующий проект
pnpm add turbo --save-dev --workspace-root

Конфигурация 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"]
    }
  }
}

^build означает «сначала собери все зависимости этого пакета». Так Turbo автоматически определяет порядок: packages/ui соберётся до apps/web, потому что web зависит от ui.

Настройка пакетов

// 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",
    "lint": "eslint src/",
    "typecheck": "tsc --noEmit"
  },
  "devDependencies": {
    "@acme/eslint-config": "*",
    "@acme/typescript-config": "*",
    "tsup": "^8.0.0"
  },
  "peerDependencies": {
    "react": "^18.0.0"
  }
}

// apps/web/package.json
{
  "name": "@acme/web",
  "private": true,
  "dependencies": {
    "@acme/ui": "*",
    "@acme/utils": "*"
  }
}

"*" — workspace-протокол: pnpm/yarn разрешит в локальный пакет. В npm надо указывать "workspace:*" явно.

Общий TypeScript конфиг

// packages/config/typescript/base.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "lib": ["ES2020"],
    "skipLibCheck": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  }
}

// packages/config/typescript/react.json
{
  "extends": "./base.json",
  "compilerOptions": {
    "jsx": "react-jsx",
    "lib": ["ES2020", "DOM", "DOM.Iterable"]
  }
}

// apps/web/tsconfig.json
{
  "extends": "@acme/typescript-config/react.json",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@/*": ["./src/*"] }
  },
  "include": ["src", "next-env.d.ts"]
}

Удалённый кеш

Локальный кеш работает только на одной машине. Для команды и CI нужен remote cache. Vercel Remote Cache — бесплатно для опенсорса, платно для приватных:

# Авторизация (один раз)
npx turbo login
npx turbo link

# Или self-hosted через ducktape/turborepo-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}"

// turbo.json — remote cache endpoint
{
  "remoteCache": {
    "signature": true
  }
}

# Запуск с remote cache
TURBO_TOKEN=your-secret-token TURBO_API=https://cache.internal.example.com \
  turbo build

CI/CD с 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  # нужно для --filter=...[HEAD^1]

      - 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]

      # Build всегда — деплой нужен с актуальным кешем
      - run: pnpm turbo build

--filter=...[HEAD^1] — «всё, что изменилось с предыдущего коммита, плюс все зависящие от этого пакеты». Если изменили packages/ui — пересобираются и apps/web, и apps/admin.

Типичные проблемы

Зависимость на runtime конфиг — если пакет читает .env при сборке, Turbo закеширует с конкретным значением переменной. Явно указывайте env в pipeline:

"build": {
  "env": ["NEXT_PUBLIC_API_URL", "DATABASE_URL"]
}

Circular dependencies — Turbo упадёт с ошибкой. Рефакторинг: выделить общую зависимость в третий пакет.

Dev-режим и кеш — dev должен иметь "cache": false и "persistent": true. Иначе Turbo не будет запускать watchers параллельно.

Сроки

Настройка Turborepo с нуля для проекта с 5–8 пакетами — два-три дня: создание структуры, конфигурация pipeline, общие tsconfig/eslint, настройка remote cache, адаптация CI/CD. Перенос существующего проекта в monorepo добавляет неделю на реструктуризацию импортов и разрешение зависимостей.