Поле jsc.transform
### jsc.transform: назначение и место в архитектуре SWC
Поле **jsc.transform** в конфигурации SWC определяет набор трансформаций AST (Abstract Syntax Tree), которые применяются к JavaScript/TypeScript коду после этапа парсинга и до генерации выходного кода. Это центральный механизм модификации синтаксиса, полифиллинга и переписывания конструкций языка без изменения исходного текста.
Трансформации в SWC выполняются на уровне дерева синтаксиса, что позволяет изменять код структурно, а не текстово. Такой подход обеспечивает высокую производительность и предсказуемость результатов, особенно при обработке больших кодовых баз.
---
### Общая структура jsc.transform
Типичная конфигурация выглядит следующим образом:
```json
{
"jsc": {
"transform": {
"constModules": false,
"legacyDecorator": false,
"decoratorMetadata": false,
"react": {
"runtime": "automatic",
"refresh": false,
"throwIfNamespace": true,
"useBuiltins": false
},
"optimizer": {
"globals": {
"vars": {}
}
},
"regenerator": {
"importPath": "@swc/helpers"
}
}
}
}
```
Каждый вложенный блок отвечает за отдельный класс трансформаций: React JSX, декораторы, оптимизации глобальных переменных, преобразование генераторов и async функций.
---
### Роль трансформаций в конвейере SWC
Внутри пайплайна SWC трансформации занимают промежуточный этап:
1. **Парсинг (jsc.parser)** — исходный код превращается в AST.
2. **Трансформация (jsc.transform)** — AST модифицируется согласно правилам.
3. **Генерация кода (jsc.codegen)** — преобразованное дерево сериализуется обратно в код.
jsc.transform является единственным этапом, где код может быть семантически изменён: добавлены импорты, переписаны конструкции, заменены вызовы функций.
---
### React-трансформация
#### JSX runtime
Блок `react` внутри jsc.transform управляет преобразованием JSX:
```json
{
"jsc": {
"transform": {
"react": {
"runtime": "automatic"
}
}
}
}
```
Доступны два режима:
* **classic runtime** — требует `React.createElement`
* **automatic runtime** — использует автоматический импорт JSX функций
При automatic режиме SWC самостоятельно вставляет необходимые импорты из `react/jsx-runtime`.
---
#### Основные параметры React трансформации
* **runtime**
* `automatic` — современный режим без явного React в каждом файле
* `classic` — совместимость со старыми проектами
* **refresh**
Включает поддержку Fast Refresh для разработки. AST дополняется хелперами для отслеживания состояния компонентов.
* **throwIfNamespace**
Контролирует поведение при использовании XML-namespace JSX.
* **useBuiltins**
Определяет использование встроенных helper-функций вместо внешних импортов.
---
### Обработка декораторов
Поле transform управляет двумя основными режимами декораторов:
```json
{
"jsc": {
"transform": {
"legacyDecorator": true,
"decoratorMetadata": true
}
}
}
```
#### legacyDecorator
Включает поддержку старого стандарта декораторов TypeScript. AST переписывается с применением функций-обёрток к классам и их свойствам.
#### decoratorMetadata
Добавляет метаданные через `Reflect.metadata`, что используется в DI-фреймворках и системах инверсии управления.
---
### Transform constModules
```json
{
"jsc": {
"transform": {
"constModules": true
}
}
}
```
Оптимизация `constModules` позволяет:
* инлайнить импортируемые модули
* удалять неизменяемые зависимости
* упрощать дерево импортов
На уровне AST происходит подстановка значений вместо ссылок на модули, если они статически вычислимы.
---
### Regenerator и async/await
Блок `regenerator` отвечает за преобразование генераторов и асинхронных функций в ES5-совместимый код:
```json
{
"jsc": {
"transform": {
"regenerator": {
"importPath": "@swc/helpers"
}
}
}
}
```
Механизм включает:
* преобразование `async/await` в state machine
* замену генераторов на функции с контекстным управлением
* импорт runtime-хелперов
Импортный путь позволяет контролировать источник вспомогательных функций, что важно для бандлеров.
---
### Optimizer: глобальные переменные
Блок `optimizer` работает с глобальными значениями:
```json
{
"jsc": {
"transform": {
"optimizer": {
"globals": {
"vars": {
"DEBUG": true
}
}
}
}
}
}
```
На уровне AST происходит:
* замена идентификаторов на литералы
* удаление условных блоков при константных выражениях
* упрощение логических ветвлений
Пример:
```js
if (DEBUG) {
console.log("dev mode");
}
```
после трансформации:
```js
console.log("dev mode");
```
если `DEBUG` задан как `true`.
---
### AST-переписывание: внутренняя модель
jsc.transform оперирует AST-структурами, включающими:
* FunctionDeclaration
* ClassDeclaration
* JSXElement
* ImportDeclaration
* ExpressionStatement
Каждый трансформер — это набор правил обхода дерева:
1. вход в узел
2. проверка типа
3. модификация или замена
4. рекурсивный обход детей
Такой подход позволяет строить композицию трансформаций без конфликтов между ними.
---
### Порядок применения трансформаций
Порядок внутри jsc.transform фиксирован и влияет на результат:
1. JSX transform
2. Decorators transform
3. Module transforms
4. Async/generator transforms
5. Optimizer transforms
Изменение порядка привело бы к некорректному AST, например, декораторы могут зависеть от структуры классов, изменённой JSX-преобразованием.
---
### Влияние на размер и производительность
Каждый включённый блок jsc.transform увеличивает:
* время компиляции (минимально, благодаря Rust-реализации)
* размер итогового AST
* количество генерируемого кода
Однако оптимизации SWC минимизируют накладные расходы за счёт:
* zero-copy операций над AST
* статической типизации узлов
* отсутствия интерпретируемых фаз
---
### Связь с плагинами и кастомными трансформациями
Хотя jsc.transform содержит фиксированный набор трансформаций, он может быть расширен через:
* внешние плагины SWC
* интеграцию с bundler-level transforms (например, Next.js или Webpack loader)
Кастомные трансформации обычно вставляются между стандартными стадиями или заменяют отдельные блоки (например, JSX runtime).
---
### Типичные ошибки конфигурации
Неправильная настройка jsc.transform приводит к:
* дублированию JSX runtime
* конфликтам декораторов legacy и stage-3
* некорректной генерации async функций
* потере импортов при constModules
Особенно критичны комбинации:
* `react.runtime = automatic` + ручной импорт React
* `legacyDecorator = true` + TypeScript experimental decorators
---
### Поведение при частично заданной конфигурации
Если jsc.transform задан частично, SWC использует дефолтные значения:
* react transform включается при наличии JSX
* regenerator активируется при наличии async функций
* optimizer применяется только при явных vars
Это делает конфигурацию устойчивой к минимальным описаниям.
---
### Значение в экосистеме SWC
jsc.transform является ключевым уровнем кастомизации поведения компилятора. В отличие от парсера и кодогенератора, он определяет семантику конечного JavaScript-кода, обеспечивая совместимость между различными стандартами языка и средами исполнения.