Turborepo + pnpm Workspaces

Как организована монорепозитория Lowcode Platform: сборка, кеширование, пайплайны и структура пакетов.

🎯 Зачем эта страница

Задача этого раздела — объяснить:

• почему используется Turborepo;
• как он взаимодействует с pnpm workspaces;
• как устроены пайплайны (dev, build, lint, test);
• как кеширование ускоряет работу с большим количеством пакетов;
• как правильно добавлять новые модули и приложения.

Разобрав это, можно уверенно расширять монорепу, не ломая существующую структуру и не теряя производительности.

---

1. Что такое Turborepo

Turborepo — это инструмент для управления монорепозиториями, который предоставляет:

• параллельный запуск задач;
• интеллектуальное кеширование результатов;
• инкрементальную сборку (запускает только то, что реально изменилось);
• кэш, совместимый с CI;
• декларативные пайплайны, описанные в turbo.json.

Основная идея: не нужно пересобирать весь проект — только изменившиеся части.

---

2. Что такое pnpm workspaces

pnpm используется как менеджер пакетов.

Workspaces позволяют:

• иметь единый node_modules в корне;
• устанавливать зависимости один раз;
• делать локальные пакеты доступными друг другу без публикации.

Корневой файл pnpm-workspace.yaml определяет, какие директории входят в монорепу:

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

Это означает:

• все «рабочие приложения» — в apps/;
• все библиотеки и общие модули — в packages/.

---

3. Как Turborepo и pnpm работают вместе

Turborepo не заменяет NPM/Pnpm — он просто дирижёр.

Он:

• читает package.json всех пакетов;
• смотрит зависимости между ними;
• запускает скрипты (dev, build, lint, test);
• кеширует результаты;
• в CI может скачивать кеш, чтобы ускорить build.

Команда

pnpm dev

в корне вызывает

turbo run dev

и дальше Turborepo решает, какие пакеты запускать.

---

4. Структура монорепозитория Lowcode Platform

В проекте действует чёткое разделение:

apps/
  api/            ← NestJS + Fastify backend
  builder-web/    ← React + Vite редактор
  docs/           ← сайт документации Docusaurus

packages/
  dsl-compiler/   ← DSL → AST → bundle (ядерная логика платформы)
  shared-types/   ← общие типы TS
  ui-kit/         ← библиотека визуальных компонентов (если есть)

Особенности:

• apps/ содержит запускаемые приложения.
• packages/ содержит общий код, который используется приложениями.

---

5. Пайплайны Turborepo

В корне проекта есть файл turbo.json, например:

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

Как это работает

• dev: запускает команды разработки в каждом приложении (обычно vite dev, nest start, docusaurus start).
• build: вызывает build сначала у зависимостей, затем у зависимых пакетов.
• lint: запускает линтеры (eslint, tsc --noEmit, и т.п.).
• test: запускает Jest или Vitest.

Ключевая идея: если packages/dsl-compiler не изменился — Turborepo не будет пересобирать apps/builder-web.

Это ускоряет сборку в разы.

---

6. Пример: разработка в монорепозитории

6.1. Запуск всего проекта в режиме разработки

В корне:

pnpm dev

Turborepo запускает:

• apps/api → pnpm dev → NestJS
• apps/builder-web → pnpm dev → Vite dev server
• apps/docs → при необходимости — pnpm start

Они работают параллельно.

6.2. Запуск только одного приложения

pnpm --filter @lowcode/api dev

или

pnpm --filter @lowcode/builder-web dev

---

7. Добавление нового пакета в монорепу

7.1. Новый модуль в packages/

Создаём файл:

packages/new-module/package.json

Минимум:

{
  "name": "@lowcode/new-module",
  "version": "0.1.0",
  "main": "src/index.ts"
}

Теперь его можно импортировать из других пакетов:

import { something } from '@lowcode/new-module';

7.2. Новое приложение в apps/

Создаём директорию:

apps/new-app/

Добавляем свой package.json и нужные команды (dev, build, start).

Turborepo автоматически учтёт его в пайплайне.

---

8. Кеширование Turborepo

Turborepo хранит кеш сборок в:

./.turbo/

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

• скорость разработки: повторные сборки мгновенные;
• скорость CI/CD: можно хранить кеш в облаке.

В CI можно включить remote caching, чтобы build занимал секунды.

---

9. Где находятся ключевые файлы

Компонент	Путь	Описание
Конфигурация Turborepo	turbo.json	Определяет пайплайны
Workspaces pnpm	pnpm-workspace.yaml	Описывает пакеты монорепы
Корневой package.json	package.json	Общие скрипты и зависимости
Приложения	apps/**	Запускаемые сервисы
Библиотеки	packages/**	Общий код

---

10. Что нужно знать разработчику

• как работает структура apps/ и packages/;
• как запускать отдельные приложения через pnpm --filter;
• как Turborepo кеширует результаты и управляет зависимостями между пакетами;
• какие задачи определены в turbo.json и как они связаны.

Этого достаточно, чтобы уверенно работать в монорепозитории и добавлять новые модули.