esbuild выполняет транспиляцию TypeScript как часть общего процесса преобразования исходного кода в JavaScript, пригодный для выполнения в браузере или Node.js. Важно различать два уровня обработки TypeScript: удаление синтаксиса типов и полноценная проверка типов. esbuild относится только к первому уровню.
TypeScript добавляет в JavaScript систему статических типов, интерфейсы, перечисления и другие конструкции, которые не существуют в рантайме. Любой инструмент, который «транспилирует TypeScript», обязан удалить эти конструкции, чтобы получить валидный JavaScript. Именно эту задачу и решает esbuild.
При этом esbuild не является TypeScript-компилятором в полном смысле. Он не реализует семантический анализ типов и не выполняет проверку совместимости типов. Его роль ограничена синтаксическим преобразованием.
При включённой поддержке TypeScript esbuild выполняет строго ограниченный набор операций:
Удаление типов
interface): string,
: number)<T>)type A = ...)Трансформация современного синтаксиса
Интеграция с модульной системой esbuild анализирует импорт/экспорт и может:
Главное ограничение esbuild в контексте TypeScript — полное отсутствие проверки типов.
Это означает:
tsconfig.json используется только частично (в основном
для синтаксических опций)Фактически esbuild «не знает», что такое типовая система TypeScript. Он рассматривает типы как комментарии, которые нужно удалить.
Отсутствие проверки типов приводит к смещению ответственности:
Обычно это означает параллельное использование tsc в
режиме проверки:
tsc --noEmit — только проверка типов без генерации
файловТакое разделение позволяет достичь высокой скорости сборки без потери типовой безопасности.
esbuild уверенно обрабатывает большинство распространённых возможностей TypeScript:
Базовые типы
Структуры кода
public,
private, protected)Функции
Модули
Несмотря на высокую скорость и широкую поддержку синтаксиса, существуют принципиальные ограничения.
esbuild не умеет:
Многие опции TypeScript игнорируются:
noImplicitAny не применяетсяstrict не имеет эффектаbaseUrl и paths работают только через
дополнительные механизмы резолвингаПоддержка декораторов зависит от версии и режима:
tscОсновное различие заключается в архитектуре:
tsc) — это семантический
анализатор + транспиляторЭто приводит к фундаментальному разделению ответственности:
| Возможность | esbuild | tsc |
|---|---|---|
| Удаление типов | Да | Да |
| Проверка типов | Нет | Да |
| Бандлинг | Да | Нет |
| Оптимизация сборки | Да | Ограниченно |
| Инкрементальная компиляция | Да | Да |
Отказ от анализа типов делает esbuild крайне быстрым. В типичных сценариях он:
Однако архитектура проекта должна учитывать:
esbuild продолжает работу даже при наличии:
Ошибки проявляются только в двух случаях:
Таким образом, код может успешно собраться, но быть логически некорректным с точки зрения TypeScript.
В реальных сборках TypeScript с esbuild обычно выстраивается двухэтапная схема:
Это позволяет:
При использовании TSX:
Это делает возможным использование React + TypeScript без замедления сборки, но переносит ответственность за корректность типов на внешний инструмент.
Модель работы можно описать так: