Установка и подключение плагина

SWC используется как высокопроизводительный компилятор и транспайлер, написанный на Rust и интегрируемый в JavaScript-экосистему через npm-пакеты. Основной пакет предоставляет ядро трансформаций, CLI-инструменты и возможность расширения через плагины.

Установка выполняется через менеджеры пакетов npm, yarn или pnpm и делится на несколько уровней: базовое ядро, CLI-инструменты и дополнительные интеграционные пакеты под конкретные сборщики.

Установка базового ядра

Основной пакет SWC: 

npm install @swc/core

или: 

yarn add @swc/core

или: 

pnpm add @swc/core

Пакет @swc/core содержит нативные бинарные модули, поэтому установка сопровождается загрузкой платформенно-зависимых сборок (Linux, macOS, Windows). Эти бинарники обеспечивают высокую скорость трансформации кода и заменяют Babel в типичных сценариях транспиляции.

После установки становится доступен программный API для выполнения трансформаций: 

const swc = require("@swc/core");

const result = swc.transformSync("const x: number = 1;", {
  jsc: {
    parser: {
      syntax: "typescript"
    },
    target: "es2020"
  }
});

console.log(result.code);

Установка CLI-инструмента

Для использования SWC в командной строке устанавливается отдельный пакет: 

npm install -D @swc/cli

CLI предоставляет утилиту swc, позволяющую выполнять трансформацию файлов и директорий.

Пример использования: 

npx swc src -d dist

В данном режиме происходит рекурсивная обработка исходников из директории src с выводом результата в dist.

Дополнительно CLI поддерживает наблюдение за изменениями: 

npx swc src -d dist --watch

Подключение SWC к сборщикам

SWC интегрируется в современные сборочные системы через специализированные загрузчики:

Webpack 

npm install -D swc-loader

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

module.exports = {
  module: {
    rules: [
      {
        test: /\.[jt]sx?$/,
        use: {
          loader: "swc-loader",
          options: {
            jsc: {
              parser: {
                syntax: "typescript",
                jsx: true
              },
              target: "es2020"
            }
          }
        }
      }
    ]
  }
};

Vite (через плагин) 

npm install -D @swc/plugin-vite

Использование в конфигурации Vite: 

import swc from "@swc/plugin-vite";

export default {
  plugins: [swc()]
};

Конфигурация SWC через .swcrc

Основной способ управления поведением SWC осуществляется через файл .swcrc. Он может быть размещён в корне проекта и определяет параметры трансформации.

Пример базовой конфигурации: 

{
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "tsx": true
    },
    "target": "es2020",
    "transform": {
      "react": {
        "runtime": "automatic"
      }
    }
  },
  "module": {
    "type": "es6"
  }
}

Файл .swcrc автоматически подхватывается CLI и большинством интеграций без дополнительного указания пути.

Установка и подключение плагинов SWC

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

Установка плагинов

Плагины устанавливаются как отдельные npm-пакеты: 

npm install -D @swc/plugin-styled-components

или другие плагины, поставляемые экосистемой SWC или сторонними разработчиками.

Подключение плагинов через .swcrc

Подключение осуществляется через секцию plugin или plugins (в зависимости от версии интеграции): 

{
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "tsx": true
    },
    "transform": {},
    "experimental": {
      "plugins": [
        [
          "@swc/plugin-styled-components",
          {
            "displayName": true,
            "ssr": true
          }
        ]
      ]
    }
  }
}

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

Особенности подключения плагинов

При использовании плагинов учитываются следующие ограничения архитектуры SWC:

  • плагины выполняются на этапе трансформации AST, до генерации кода
  • порядок выполнения может влиять на итоговую структуру кода
  • не все плагины совместимы с различными парсерами (TypeScript, JSX, decorators)
  • поддержка зависит от версии @swc/core

Плагины и experimental-режим

Плагин-система SWC долгое время находилась в экспериментальном статусе, поэтому часть функциональности активируется через флаг experimental.

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

{
  "jsc": {
    "experimental": {
      "plugins": [
        [
          "swc-plugin-log",
          {
            "level": "debug"
          }
        ]
      ]
    }
  }
}

В таких конфигурациях важно учитывать совместимость версий @swc/core и подключаемого плагина, поскольку API AST может изменяться между релизами.

Подключение SWC в Node.js без CLI

SWC может использоваться напрямую в серверных приложениях Node.js, что позволяет интегрировать плагины и конфигурацию без сборщика. 

const swc = require("@swc/core");

async function compile(source) {
  return await swc.transform(source, {
    filename: "input.ts",
    jsc: {
      parser: {
        syntax: "typescript"
      },
      experimental: {
        plugins: [
          ["@swc/plugin-styled-components", { displayName: true }]
        ]
      }
    }
  });
}

compile("const a: number = 1;").then(console.log);

Разрешение зависимостей плагинов

При установке плагинов важно учитывать их бинарную природу. Некоторые плагины требуют дополнительных зависимостей:

  • @swc/core определённой версии
  • совместимый runtime Node.js
  • платформенные бинарники (glibc / musl)

Проверка установленной версии SWC: 

npx swc --version

или через npm: 

npm list @swc/core

Использование нескольких плагинов одновременно

SWC поддерживает цепочку плагинов, которые выполняются последовательно: 

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

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

Типичные проблемы при установке плагинов

При подключении SWC и его плагинов часто возникают следующие ситуации:

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

  • плагины требуют более новую или старую версию @swc/core

Ошибки загрузки бинарников

  • отсутствие подходящей платформенной сборки
  • использование неподдерживаемой архитектуры

Конфликты конфигурации

  • одновременное использование Babel и SWC в одном пайплайне
  • дублирование трансформаций JSX или TypeScript

Ошибки experimental plugins

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

Итоговая структура установки SWC с плагинами

Типовая схема подключения включает:

  • установка @swc/core как ядра трансформации
  • установка @swc/cli или swc-loader при необходимости сборки
  • добавление нужных плагинов через npm
  • конфигурация .swcrc с секцией experimental.plugins
  • проверка совместимости версий всех компонентов

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

Оглавление