Project references: tsc --build, composite и инкрементальный граф сборки

Форма: проект, указывающий на свои зависимости

У каждого пакета свой tsconfig.json. Пакет, зависящий от другого, перечисляет его в references, и проект, на который ссылаются, должен быть composite:

// packages/web/tsconfig.json
{
  "compilerOptions": { "composite": true, "outDir": "dist" },
  "references": [
    { "path": "../core" },   // web зависит от core
    { "path": "../ui" }      // и от ui
  ]
}

// packages/core/tsconfig.json
{
  "compilerOptions": {
    "composite": true,        // ОБЯЗАТЕЛЬНО, чтобы на него ссылались
    "declaration": true,      // composite это подразумевает; типы — это межпроектный контракт
    "outDir": "dist"
  }
}

composite: true включает три вещи: форсирует declaration: true (чтобы проект генерировал .d.ts — интерфейс, который другие проекты потребляют вместо исходника), форсирует инкрементальное поведение с .tsbuildinfo и требует, чтобы каждый входной файл был покрыт include/files (чтобы сборка надёжно хешировала входы).

tsc --build обходит граф ссылок

Обычная сборка tsc проекта со ссылками либо упадёт, либо проигнорирует их. Нужно использовать режим сборки: tsc --build (или tsc -b). Режим сборки читает граф ссылок, топологически сортирует его и собирает зависимости перед зависящими — и пропускает любой проект, чьи входы не изменились с момента его .tsbuildinfo:

tsc --build packages/web   # собирает core, потом ui, потом web — в порядке зависимостей
tsc --build --verbose      # печатает, какие проекты актуальны, а какие пересобраны
tsc --build --clean        # удаляет все выводы + .tsbuildinfo (лекарство от устаревшего кэша)
tsc --build --force        # игнорирует .tsbuildinfo, пересобирает всё

Инкрементальность и .tsbuildinfo

Прежде чем смириться с 90-секундной проверкой типов на каждом сохранении, спроси себя: знает ли твой tsconfig, какие файлы принадлежат каждому пакету? Если нет, tsc каждый раз хеширует всё заново.

.tsbuildinfo — это кэш хешей файлов и сигнатур. При пересборке tsc -b сравнивает текущие входы с кэшированным состоянием; если входы проекта (и .d.ts его зависимостей) не изменились, он актуален и пропускается целиком. Важно: проекту нужно пересобирать зависящего, только когда его публичный .d.ts реально изменился — внутренняя правка, не меняющая генерируемые типы, оставляет зависящих в кэше (оптимизация по «сигнатуре»).

Именно поэтому редакторы шустрее: каждый проект-со-ссылкой проверяется изолированно, так что языковой сервер не переанализирует всё монорепо на каждом нажатии клавиши.

Ловушки

error TS6306: Referenced project must have setting "composite": true — ты сослался на проект, который не composite. Добавь composite: true в тот, на который ссылаются (частая путаница: его добавляют ссылающемуся).

Устаревший .tsbuildinfo — если изменить что-то, что кэш не отслеживает (апгрейд компилятора с особенностью, ручная правка dist), сборка может ошибочно счесть проект актуальным. Лекарство: tsc -b --clean, затем пересборка, или --force.

Циклические ссылки — A ссылается на B, а B на A — отвергается (TS6202); DAG сборки должен быть ацикличным. Разорви цикл, вынеся общие типы в третий лист-проект, от которого зависят оба.

Path mapping между проектами — алиасы paths по-прежнему не переписываются при emit (урок 02), поэтому межпроектные импорты должны идти через настоящий entry/exports пакета, а не через алиас paths, который понимает только проверщик типов.

Все четыре ловушки объединяет паттерн: ошибка указывает на проект, на который ссылаются, а не на ссылающийся; кэш — это файл, который всегда можно удалить; циклы требуют нового листа для разрыва; алиасы — фикция проверщика типов, которая не должна просачиваться в emit.