Що дає isolatedDeclarations і чому він прискорює збирання великих проєктів?

Щоб згенерувати .d.ts для файлу, TypeScript зазвичай виводить типи експортованих функцій і змінних - а для цього потрібен повний аналіз програми з усіма залежностями. Генерувати декларації файл за файлом незалежно неможливо.

isolatedDeclarations (TypeScript 5.5+) вимагає, щоб тип кожного експорту можна було отримати з самого файлу, без виведення через інші модулі. На практиці - явні типи результатів і анотації там, де тип неочевидний:

// помилка з isolatedDeclarations: тип результату треба вивести
export function getTotal(items: Item[]) {
  return items.reduce((sum, item) => sum + item.price, 0);
}

// ок
export function getTotal(items: Item[]): number {
  return items.reduce((sum, item) => sum + item.price, 0);
}

export const DEFAULT_PAGE = 1;              // ок: літерал очевидний
export const config = createConfig();       // помилка: потрібна анотація
export const config: AppConfig = createConfig();

Обмеження стосуються лише експортованого API - внутрішній код модуля пишеться як завжди.

Що це дає:

1. Генерація декларацій без перевірки типів. Будь-який інструмент (esbuild, SWC, oxc, Rolldown) може видати .d.ts чисто синтаксично - перетворенням одного файлу, в рази швидше за tsc. Збирання бібліотеки більше не чекає на повну перевірку типів.

2. Паралельне збирання монорепозиторіїв. Залежний пакет потребує лише .d.ts своїх залежностей. Якщо декларації генеруються синтаксично, пакети можна перевіряти паралельно, не чекаючи, доки повністю перевіриться ланцюжок залежностей. TypeScript 7 прямо згадує це: паралельне збирання проєктних посилань (--builders) обмежене графом залежностей - за винятком проєктів з isolatedDeclarations і синтаксичною генерацією декларацій.

3. Стабільніший публічний API. Явні типи на експортах означають, що зміна реалізації не змінить мовчки контракт - добра практика для бібліотек незалежно від швидкості.

Ціна: більше анотацій на межах модулів. Редактор пропонує швидке виправлення «додати явний тип», тож міграція переважно механічна.

Кому вмикати:

• бібліотекам і пакетам монорепозиторію, що публікують .d.ts;
• великим кодовим базам із проєктними посиланнями.

Для кінцевого застосунку, який нічого не публікує, користь менша - там основний виграш дає TypeScript 7 сам по собі.

Докладніше в документації: tsconfig: isolatedDeclarations