Поле plugin в конфигурации

В конфигурации SWC поле plugin используется для подключения пользовательских трансформаций, расширяющих стандартный набор преобразований компилятора. Оно позволяет внедрять дополнительную логику обработки AST, реализованную как плагин, который выполняется в процессе трансформации исходного кода.

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

Расположение поля в конфигурации

Поле plugin может встречаться в зависимости от версии конфигурации SWC и используемой схемы:

  • на верхнем уровне конфигурации (редко и зависит от сборки);
  • внутри блока jsc;
  • внутри экспериментального блока experimental.

Наиболее распространённая форма: 

{
  "jsc": {
    "experimental": {
      "plugins": []
    }
  }
}

Однако концептуально поле plugin часто рассматривается как обобщённое обозначение механизма подключения расширений, тогда как фактическая реализация в SWC чаще использует массив plugins.

Структура плагина

Каждый подключаемый плагин задаётся как элемент массива, содержащий:

  • идентификатор плагина (строка или путь к модулю);
  • параметры конфигурации (объект).

Общий формат: 

{
  "jsc": {
    "experimental": {
      "plugins": [
        ["plugin-name", { "optionA": true, "optionB": "value" }]
      ]
    }
  }
}

Первый элемент массива — это точка подключения плагина, второй — объект настроек, передаваемый в его инициализацию.

Типы подключаемых плагинов

SWC поддерживает несколько категорий плагинов, которые могут быть использованы через конфигурационное поле:

  1. WASM-плагины

Наиболее распространённый формат. Плагин компилируется в WebAssembly и загружается во время выполнения трансформации.

Особенности:

  • кроссплатформенность;
  • ограниченная работа с внешними ресурсами;
  • высокая изоляция выполнения.

Пример подключения: 

{
  "jsc": {
 "experimental": {
   "plugins": [
     ["@swc/plugin-console", {}]
   ]
 }
  }
}

  1. Native/Rust-плагины

Используются внутри экосистемы SWC и могут быть встроены в бинарную сборку трансформера.

Особенности:

  • максимальная производительность;
  • прямой доступ к внутреннему AST;
  • сложность разработки и сборки.

  1. JS-обёртки над плагинами

В некоторых сценариях используются JS-модули, которые лишь делегируют работу WASM-части.

Порядок выполнения плагинов

Если в конфигурации указано несколько плагинов, они выполняются последовательно в порядке объявления: 

{
  "jsc": {
 "experimental": {
"plugins": [
  ["plugin-a", {}],
  ["plugin-b", {}],
  ["plugin-c", {}]
]
 }
  }
}

Последовательность важна, поскольку каждый следующий плагин получает AST, уже модифицированное предыдущими.

Взаимодействие с трансформацией SWC

Плагины выполняются на стадии, когда исходный код уже:

  • распарсен в AST;
  • частично нормализован внутренними механизмами SWC;
  • готов к трансформациям уровня синтаксиса.

После выполнения плагинов AST проходит стандартные стадии:

  • трансформация ECMAScript (ESNext → ES5 при необходимости);
  • оптимизация;
  • генерация кода.

Таким образом, plugin влияет именно на промежуточное представление программы.

Передача параметров в plugin

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

Пример: 

{
  "jsc": {
 "experimental": {
"plugins": [
  [
 "remove-debug-plugin",
 {
   "removeConsole": true,
   "removeDebugger": true
 }
  ]
]
 }
  }
}

Внутри плагина эти параметры интерпретируются как конфигурация поведения трансформации AST.

Пример: модификация кода через plugin

Предположим, используется плагин, удаляющий все вызовы console.log.

Конфигурация: 

{
  "jsc": {
 "experimental": {
"plugins": [
  [
 "strip-console",
 {
   "methods": ["log", "info"]
 }
  ]
]
 }
  }
}

Исходный код: 

console.log("debug");
console.info("info");
console.error("error");

Результат трансформации: 

console.error("error");

Плагин воздействует только на указанные методы, оставляя остальные без изменений.

Локальные и внешние плагины

Поле plugin может ссылаться как на:

  • установленный npm-пакет;
  • локальный файл;
  • внутренний модуль сборщика.

npm-пакет 

{
  "jsc": {
 "experimental": {
"plugins": [
  ["@company/swc-plugin-optimize", {}]
]
 }
  }
}

локальный путь 

{
  "jsc": {
 "experimental": {
"plugins": [
  ["./plugins/custom-plugin.wasm", {}]
]
 }
  }
}

Ограничения выполнения plugin

Модель плагинов SWC накладывает ряд ограничений:

Изоляция среды

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

Отсутствие произвольного runtime

В отличие от Node.js трансформеров, плагины работают в изолированной среде выполнения.

Ограниченный API AST

Доступ предоставляется через строго типизированные структуры, отражающие синтаксис JavaScript.

Производительность plugin-слоя

Использование plugin влияет на скорость компиляции:

  • каждый плагин добавляет дополнительный проход по AST;
  • WASM-вызовы создают overhead;
  • сложные трансформации увеличивают время сборки линейно или хуже.

Рекомендуется:

  • минимизировать количество плагинов;
  • объединять логику в один модуль;
  • избегать тяжёлых операций над деревом.

Совместимость с другими опциями SWC

Поле plugin работает совместно с другими конфигурационными блоками:

  • jsc.parser — определяет синтаксис входного кода;
  • jsc.transform — базовые трансформации;
  • minify — минификация;
  • env — полифиллы и таргетинг.

Плагины выполняются до финальной генерации кода, но после парсинга и базовой нормализации AST.

Приоритет трансформаций

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

  1. Парсер (parser)
  2. Нормализация AST
  3. plugin-слой
  4. Встроенные трансформации (transform)
  5. Минификация (minify)
  6. Генерация JavaScript

Любое изменение AST на уровне plugin влияет на все последующие стадии.

Ошибки конфигурации plugin

Типичные ошибки при использовании:

Неверная структура массива 

"plugins": [
  "plugin-name"
]

Плагин должен быть массивом из двух элементов, даже если нет опций.

Отсутствие параметров при необходимости

Некоторые плагины требуют обязательный конфигурационный объект: 

["plugin-name"] // некорректно

Несовместимость версий SWC

Плагин может требовать определённую версию SWC, иначе трансформация завершается ошибкой загрузки.

Использование plugin для архитектурных задач

Поле plugin часто применяется не только для синтаксических трансформаций, но и для архитектурных задач:

  • внедрение логирования;
  • автоматическое оборачивание функций;
  • генерация метаданных;
  • статическая инъекция кода;
  • адаптация синтаксиса под внутренние DSL.

Пример инъекции логирования: 

{
  "jsc": {
 "experimental": {
"plugins": [
  [
 "function-wrapper",
 {
   "wrapWith": "logger"
 }
  ]
]
 }
  }
}

Поведение при ошибках выполнения plugin

Если плагин вызывает ошибку:

  • компиляция прерывается;
  • выводится диагностическое сообщение SWC;
  • AST не сохраняется в промежуточном состоянии.

Некоторые сборочные системы позволяют игнорировать ошибки плагинов, но это зависит от интеграции, а не от SWC.

Кеширование результатов plugin

SWC может кешировать результаты трансформации при неизменных условиях:

  • одинаковый входной код;
  • идентичная конфигурация plugin;
  • совпадение версий плагинов.

Изменение хотя бы одного параметра конфигурации приводит к инвалидированию кеша.

Роль plugin в расширяемости SWC

Поле plugin является ключевым механизмом расширения SWC без изменения ядра трансформатора. Оно формирует промежуточный уровень абстракции между:

  • стандартным JavaScript-диалектом;
  • кастомными синтаксическими расширениями;
  • внутренними требованиями сборочных систем.

За счёт этого SWC может использоваться как универсальный компиляторный слой в различных экосистемах — от веб-приложений до серверных сборок и монорепозиториев.

Оглавление