Проверка типов против транспиляции: почему твой бандлер не ловит ошибки типов

Две совершенно разные задачи: проверка против транспиляции

tsc делает две вещи: проверяет типы (анализирует всю программу на ошибки типов) и генерирует JavaScript. Бандлеры разделяют их и оставляют только вторую:

Причина, по которой бандлеры в 10–100× быстрее tsc, именно в том, что они не проверяют типы. Анализ типов требует построения графа всей программы; транспиляция просто удаляет синтаксис типов токен за токеном в одном файле. Ошибка типа им невидима — это просто синтаксис, который они стирают.

isolatedModules: делаем однофайловую транспиляцию безопасной

Если твоя команда использует esbuild или swc для emit, есть целый класс валидного TypeScript, который молча сгенерирует неправильный JavaScript — не ошибку, а просто сломанный бандл. isolatedModules — флаг, который ловит такие конструкции в редакторе, а не в рантайме.

Поскольку esbuild/swc/babel компилируют по одному файлу за раз, не зная о других файлах, некоторые конструкции TypeScript небезопасно так транспилировать — им нужна информация о всей программе. isolatedModules: true заставляет tsc помечать именно такие конструкции, чтобы твой код был портируем на однофайловый транспилятор:

// с isolatedModules эти конструкции дают ошибку в tsc:

// 1. type-only реэкспорт, ВЫГЛЯДЯЩИЙ как реэкспорт значения:
export { SomeType } from "./types";
//       ^^ ~TS1205: однофайловый компилятор не может понять, SomeType — это
//          тип (стереть экспорт) или значение (оставить). Фикс:
export type { SomeType } from "./types"; // теперь однозначно — стереть

// 2. const enum между файлами — нужны значения enum, вшитые из другого файла:
import { Color } from "./enums";
const c = Color.Red; // const enum нельзя вшить без межфайловой информации

isolatedModules не меняет emit; он ограничивает то, что можно писать, чтобы пофайловая транспиляция давала корректный вывод. Две главные вещи, которые он фактически запрещает: const enum, потребляемый между файлами (однофайловый компилятор не может вшить значения, которых не видит) и неоднозначные type-only реэкспорты (вынуждая export type / import type).

Паттерн: бандлер собирает, tsc --noEmit гейтит

Production-настройка развязывает две задачи. Бандлер быстро производит артефакт; tsc --noEmit (часто tsc -b --noEmit для монорепо) запускается параллельно или в CI чисто чтобы проверить типы — он ничего не генерирует, лишь валит сборку, если тип неверен:

// скрипты package.json
{
  "scripts": {
    "build": "vite build",            // esbuild транспилирует — БЕЗ проверки типов
    "typecheck": "tsc --noEmit",      // настоящий гейт типов — ничего не генерирует
    "ci": "npm run typecheck && npm run build"
  }
}

verbatimModuleSyntax (TS 5.0) усиливает это: он делает emit import/export буквальным, так что обычный import всегда сохраняется, а стираются только import type/export type. Эта предсказуемость и нужна транспилятору — никакого угадывания, был ли импорт «использован как значение». Он заменяет старый importsNotUsedAsValues и закрывает те же однофайловые заботы, которые помечает isolatedModules. (Заметь: сам tsc всё ещё делает declaration emit — генерацию .d.ts — чего транспилятор не делает никогда, поэтому сборки библиотек оставляют tsc для типов, даже когда JS производит esbuild.)