Структура объекта конфигурации

Конфигурация SWC строится вокруг единого объекта, который определяет поведение трансформации кода на уровне синтаксиса, модулей, полифиллов, минификации и генерации исходных карт. Несмотря на внешнюю компактность, структура этого объекта охватывает несколько независимых подсистем компилятора, каждая из которых влияет на отдельный этап обработки исходного кода.

Верхнеуровневая структура конфигурации

Конфигурационный объект SWC условно делится на несколько ключевых блоков:

  • jsc — настройки JavaScript/TypeScript трансформаций
  • module — управление системой модулей
  • minify — параметры минификации
  • sourceMaps — генерация source map
  • env — транспиляция под целевые окружения
  • дополнительные служебные поля (include, exclude, test, cwd и др.)

Каждый блок выполняет строго определённую роль и обрабатывается отдельными частями компилятора.

Блок jsc: ядро трансформации кода

Блок jsc является центральной частью конфигурации и определяет, как именно SWC интерпретирует и преобразует исходный код.

Основная структура: 

{
  "jsc": {
    "parser": {},
    "transform": {},
    "target": "",
    "loose": false,
    "externalHelpers": false,
    "keepClassNames": false,
    "preserveAllComments": false
  }
}

parser: разбор исходного кода

Раздел parser отвечает за синтаксический разбор. Он определяет язык и расширения, которые поддерживаются на этапе парсинга.

Ключевые параметры:

  • syntax — базовый синтаксис:

    • “ecmascript”
    • “typescript”
    • “jsx”

  • jsx — включение поддержки JSX-выражений

  • tsx — расширение JSX для TypeScript

  • dynamicImport — поддержка import()

  • decorators — поддержка декораторов (в различных спецификациях)

  • decoratorsBeforeExport — старое поведение декораторов

Пример конфигурации: 

{
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "tsx": true,
      "decorators": true,
      "dynamicImport": true
    }
  }
}

Парсер определяет AST-структуру, которая далее используется всеми трансформациями.

transform: преобразование AST

Блок transform управляет преобразованиями синтаксиса и добавлением вспомогательных конструкций.

Основные подпараметры:

react 

{
  "transform": {
    "react": {
      "runtime": "automatic",
      "importSource": "react",
      "refresh": false
    }
  }
}

  • runtime:

    • “automatic” — JSX без явного React.createElement
    • “classic” — старый режим React

  • refresh — включение Fast Refresh (используется в dev-средах)

legacyDecorator / decoratorMetadata

  • legacyDecorator — поддержка старого синтаксиса декораторов
  • decoratorMetadata — генерация метаданных для декораторов

optimizer

Оптимизатор выполняет локальные преобразования AST:

  • удаление мёртвого кода (частично)
  • упрощение выражений
  • инлайнинг констант

target: целевая версия JavaScript

Поле target определяет уровень ECMAScript, в который будет транспилирован код:

  • “es3”
  • “es5”
  • “es2015”
  • “es2017”
  • “es2020”
  • “es2022”

Это влияет на генерацию синтаксиса и доступность современных конструкций.

loose: упрощённые преобразования

Режим loose включает менее строгие, но более быстрые и компактные трансформации. В этом режиме SWC может отступать от точной спецификации ECMAScript в пользу производительности.

externalHelpers

Позволяет выносить вспомогательные функции (helpers) в отдельный модуль вместо инлайна в каждый файл. Это уменьшает размер бандла при большом количестве файлов.

keepClassNames

Сохраняет оригинальные имена классов после трансформации, что важно для логирования и некоторых фреймворков отражения типов.

Блок module: система модулей

Раздел module определяет формат модулей, в который будет преобразован код. 

{
  "module": {
    "type": "es6"
  }
}

Поддерживаемые типы:

  • “es6” — ES Modules
  • “commonjs” — Node.js require/module.exports
  • “amd” — Asynchronous Module Definition
  • “umd” — универсальный формат
  • “systemjs” — SystemJS loader

Дополнительные параметры:

  • strictMode — добавление “use strict”
  • lazy — ленивый импорт модулей (в некоторых сборках)

Выбор типа модулей критически влияет на совместимость с окружением исполнения.

Блок minify: минификация кода

Минификация в SWC реализована как отдельный слой обработки AST. 

{
  "minify": {
    "compress": true,
    "mangle": true
  }
}

compress

Включает оптимизации:

  • удаление недостижимого кода
  • свёртка выражений
  • упрощение логики условий
  • inline констант

mangle

Переименование идентификаторов для уменьшения размера:

  • переменные
  • функции
  • локальные символы

При этом глобальные имена могут быть защищены через настройки исключений.

Блок sourceMaps: карты исходного кода

Source maps связывают трансформированный код с оригинальным.

Возможные значения:

  • false — отключено
  • true — генерация .map
  • “inline” — встроенные карты в файл 
{
  "sourceMaps": true
}

Этот механизм критически важен для отладки после транспиляции.

Блок env: транспиляция под окружения

Блок env отвечает за полифиллы и адаптацию под конкретные runtime-окружения. 

{
  "env": {
    "targets": {
      "chrome": "80",
      "node": "18"
    },
    "mode": "usage",
    "coreJs": "3"
  }
}

targets

Определяет целевые платформы:

  • браузеры (Chrome, Firefox, Safari)
  • Node.js версии
  • Electron и другие runtime

mode

  • “usage” — добавляет полифиллы только при использовании конкретных API
  • “entry” — добавляет полифиллы на уровне входной точки

coreJs

Версия библиотеки полифиллов core-js, используемая для совместимости.

Дополнительные поля конфигурации

isModule

Указывает, является ли входной файл модулем. Это влияет на обработку import/export.

include и exclude

Фильтрация файлов:

  • include — список путей для обработки
  • exclude — исключения (node_modules, dist и т.д.)

test

Позволяет применять конфигурацию только к определённым файлам по шаблону (regex или glob).

cwd

Определяет рабочую директорию, от которой строятся относительные пути.

Конфигурация через программный API

При использовании @swc/core конфигурация передаётся напрямую в функцию компиляции: 

import { transform } from "@swc/core";

const result = await transform(code, {
  jsc: {
    parser: {
      syntax: "typescript"
    },
    target: "es2020"
  },
  module: {
    type: "commonjs"
  },
  sourceMaps: true
});

Здесь структура объекта полностью соответствует .swcrc, но может дополняться полями:

  • filename — имя входного файла
  • inputSourceMap — внешняя source map
  • minify — включение минификации на лету

Взаимодействие блоков конфигурации

Каждый блок конфигурации SWC работает на своём этапе пайплайна:

  1. parser формирует AST
  2. jsc.transform модифицирует AST
  3. env добавляет совместимость
  4. module перестраивает систему модулей
  5. minify оптимизирует результат
  6. sourceMaps связывает итог с исходным кодом

Такая последовательность делает конфигурационный объект не просто набором опций, а описанием полного компиляционного конвейера.

Оглавление