Явное управление поддерживаемыми предложениями
При работе со SWC ключевой особенностью архитектуры становится принцип явного выбора поддерживаемых синтаксических преобразований. В отличие от инструментов, которые автоматически включают набор трансформаций в зависимости от целевой версии ECMAScript, SWC предоставляет детальную систему конфигурации, где каждая языковая возможность может быть включена или выключена независимо. Такой подход позволяет точно контролировать итоговый набор преобразований, снижать объём генерируемого кода и исключать лишние полифиллы на этапе транспиляции.
### Принцип явного включения трансформаций
SWC рассматривает современные возможности JavaScript как набор независимых трансформаций, каждая из которых активируется вручную через конфигурацию `jsc.transform`. Это касается как стабильных синтаксических возможностей, так и предложений ECMAScript, находящихся на стадии стандартизации.
Конфигурация строится вокруг идеи минимального необходимого набора преобразований:
* включается только то, что используется в кодовой базе;
* поведение трансформаций не предполагает «скрытых» зависимостей;
* итоговый код предсказуем независимо от окружения сборки.
Основной механизм управления — файл `.swcrc`, где описываются правила компиляции.
```json
{
"jsc": {
"parser": {
"syntax": "ecmascript",
"jsx": false
},
"target": "es2019",
"transform": {
"optionalChaining": false,
"nullishCoalescing": false,
"decoratorMetadata": false,
"legacyDecorator": false,
"react": {
"runtime": "automatic"
}
}
}
}
```
В такой конфигурации отсутствует автоматическое включение трансформаций для новых языковых возможностей. Каждое поведение задаётся явно, что делает систему предсказуемой и облегчает аудит сборки.
### Управление стадийными предложениями ECMAScript
Поддержка предложений ECMAScript в SWC реализуется через набор независимых флагов внутри блока `transform`. Каждое предложение рассматривается как отдельная единица синтаксиса, требующая явного разрешения.
#### Optional Chaining и Nullish Coalescing
Два наиболее распространённых синтаксических предложения часто рассматриваются вместе, однако в SWC они разделены:
* `optionalChaining` — преобразование `?.`
* `nullishCoalescing` — преобразование `??`
Их активация контролируется отдельно, что позволяет исключать трансформацию при таргете современных сред.
```json
{
"jsc": {
"target": "es2020",
"transform": {
"optionalChaining": true,
"nullishCoalescing": true
}
}
}
```
При таргете `es2020` или выше часто нет необходимости включать эти преобразования, поскольку целевые окружения уже поддерживают синтаксис нативно. Явное отключение снижает объём выходного кода.
#### Class Fields и приватные поля
Поддержка полей классов и приватных свойств реализуется через отдельные трансформации, которые особенно чувствительны к режиму совместимости.
```json
{
"jsc": {
"transform": {
"classPrivateProperty": true,
"classPrivateMethod": true,
"classProperty": true
}
}
}
```
Каждое из этих преобразований влияет на структуру генерируемого класса. Например, приватные поля могут трансформироваться в WeakMap-подобные конструкции или закрытые области видимости через замыкания, в зависимости от выбранной стратегии.
Явное управление позволяет избегать конфликтов между современным синтаксисом и legacy-режимами, особенно при сборке библиотек, рассчитанных на широкий спектр окружений.
### Управление декораторами
Декораторы являются одной из наиболее сложных зон совместимости, поскольку существуют несколько несовместимых спецификаций. SWC разделяет их на разные режимы обработки.
Основной флаг:
* `legacyDecorator` — старый семантический вариант (TypeScript legacy)
* `decoratorMetadata` — поддержка метаданных в стиле TypeScript
```json
{
"jsc": {
"transform": {
"legacyDecorator": true,
"decoratorMetadata": true
}
}
}
```
Выбор режима напрямую влияет на порядок исполнения декораторов и структуру результирующего AST. В явной конфигурации запрещено смешивание разных моделей без прямого указания, что исключает неоднозначное поведение при компиляции.
### Управление React-трансформацией как частью поддерживаемых предложений
Хотя React не является ECMAScript-предложением, JSX-трансформация включается в тот же блок управления трансформациями и рассматривается как часть синтаксических расширений.
```json
{
"jsc": {
"transform": {
"react": {
"runtime": "automatic",
"development": false,
"refresh": false
}
}
}
}
```
Режим `automatic` устраняет необходимость явного импорта React в каждом файле, но требует строгого контроля над версией трансформации. Явная настройка предотвращает случайное переключение между legacy и automatic runtime.
### Сегментация поддерживаемых предложений по целевым окружениям
SWC связывает включение трансформаций с целевой версией ECMAScript через параметр `target`, однако этот параметр не заменяет явную настройку флагов. Он лишь задаёт базовый уровень совместимости.
```json
{
"jsc": {
"target": "es2017",
"transform": {
"asyncFunction": true,
"arrowFunction": false
}
}
}
```
Такой подход создаёт двухуровневую модель:
* `target` определяет минимальный уровень языка
* `transform` переопределяет конкретные синтаксические возможности
Это позволяет строить конфигурации, в которых часть предложений транслируется вручную даже при высоком target, если требуется поддержка специфических окружений.
### Управление async/await и генераторами
Асинхронные функции и генераторы в SWC также рассматриваются как трансформации, зависящие от целевой платформы.
```json
{
"jsc": {
"transform": {
"asyncFunction": true,
"generator": true
}
}
}
```
При включении этих флагов SWC преобразует async/await в генераторные состояния или регенераторные паттерны в зависимости от настроек окружения. Явное управление здесь критично для библиотек, работающих в средах без нативной поддержки Promises.
### Изоляция и предотвращение неявных трансформаций
Одной из особенностей SWC является отсутствие автоматического включения цепочек зависимых трансформаций. Например, включение optional chaining не активирует дополнительные полифиллы или сопутствующие преобразования без явного запроса.
Это создаёт модель, в которой конфигурация становится декларацией допустимых языковых возможностей:
* нет скрытых зависимостей между флагами;
* отсутствует каскадное включение «связанных» трансформаций;
* каждая возможность должна быть явно разрешена.
Подобная изоляция упрощает сопровождение больших кодовых баз, где разные части проекта могут требовать разные уровни поддержки синтаксиса.
### Контроль за экспериментальными возможностями
Некоторые предложения ECMAScript находятся в нестабильном состоянии и могут изменять семантику между версиями SWC. Для них используется тот же механизм флагов, но с акцентом на явную фиксацию версии трансформации через конфигурацию сборки.
```json
{
"jsc": {
"transform": {
"topLevelAwait": true
}
}
}
```
При включении подобных возможностей важно учитывать, что итоговый AST может существенно отличаться от нативного исполнения в современных движках, поэтому такие трансформации обычно включаются только в изолированных модулях или при сборке библиотек.
### Конфигурационная модель как описание языкового профиля
Набор включённых трансформаций фактически формирует языковой профиль проекта. Этот профиль определяет:
* допустимые синтаксические конструкции;
* уровень совместимости с рантаймами;
* степень транспиляции;
* структуру итогового бандла.
В SWC такой профиль выражается исключительно через конфигурацию, без скрытых механизмов автоопределения. Это позволяет рассматривать `.swcrc` как формальное описание подмножества JavaScript, разрешённого в конкретной системе сборки.