Установка через npm, yarn, pnpm

Пакет SWC в экосистеме JavaScript распространяется как набор модулей, основным из которых является @swc/core. Он содержит нативный компилятор, написанный на Rust, и используется для трансформации современного JavaScript и TypeScript в совместимый код для различных сред выполнения.

Базовая установка через npm выполняется добавлением пакета в зависимости проекта: 

npm install -D @swc/core

В большинстве случаев SWC используется как инструмент сборки или транспиляции, поэтому его добавляют именно в devDependencies. Это позволяет не включать его в production-бандл и уменьшить размер итогового приложения.

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

npm install -D @swc/cli

@swc/cli предоставляет интерфейс для запуска трансформаций напрямую из терминала, без необходимости интеграции с bundler’ами.

Типовая структура после установки включает:

  • @swc/core — ядро компилятора
  • @swc/cli — CLI-обёртка
  • дополнительные плагины (по необходимости)

Установка через yarn

При использовании Yarn процесс установки полностью эквивалентен npm, однако отличается синтаксис команд и структура lock-файла.

Установка ядра SWC: 

yarn add -D @swc/core

Добавление CLI-инструмента: 

yarn add -D @swc/cli

Yarn автоматически фиксирует версии зависимостей в yarn.lock, обеспечивая детерминированную сборку проекта на разных машинах.

При использовании Yarn 2+ (Berry) пакетная модель может работать без node_modules, что особенно важно для крупных монорепозиториев, где SWC применяется как часть общей системы сборки.

Установка через pnpm

pnpm использует жёсткую структуру хранения зависимостей с контент-адресуемым хранилищем, что уменьшает дублирование пакетов и ускоряет установку в больших проектах.

Установка SWC через pnpm: 

pnpm add -D @swc/core

CLI-инструмент: 

pnpm add -D @swc/cli

Особенность pnpm заключается в строгой изоляции зависимостей: пакет не может использовать модули, не объявленные в его package.json. Это важно для SWC-интеграций, так как некоторые плагины или обёртки требуют явного указания всех зависимостей.

Проверка установки и базовый запуск

После установки можно проверить доступность SWC через CLI: 

npx swc --version

или при глобальной доступности: 

swc --version

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

npx swc src/index.js -o dist/index.js

Если используется TypeScript: 

npx swc src/index.ts -o dist/index.js

SWC автоматически обрабатывает синтаксис TypeScript без необходимости предварительной компиляции через tsc, если не требуется проверка типов.

Локальная и глобальная установка

Глобальная установка встречается реже, так как SWC обычно привязан к конкретному проекту и версии Node.js.

Глобальная установка: 

npm install -g @swc/cli

или 

pnpm add -g @swc/cli

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

Локальная установка предпочтительнее, поскольку:

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

Установка в монорепозиториях

В монорепозиториях SWC часто подключается на уровне root-пакета: 

pnpm add -Dw @swc/core @swc/cli

или в Yarn Workspaces: 

yarn add -D -W @swc/core @swc/cli

Флаг -W или -w означает установку в корневую область workspace. Это позволяет использовать единый компилятор для всех пакетов репозитория.

Версионирование и совместимость

SWC активно развивается, и разные версии могут содержать изменения в AST, плагинах и поддержке стандартов ECMAScript.

Рекомендуется фиксировать версию явно: 

npm install -D @swc/core@1.3.100

Это особенно важно в CI/CD, где даже небольшие изменения в трансформации могут влиять на итоговый бандл.

При обновлении версии следует учитывать:

  • совместимость с используемыми пресетами (@swc/preset-env)
  • поведение TypeScript-трансформаций
  • изменения в плагинной системе

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

В реальных проектах SWC редко используется в одиночку. Часто добавляются дополнительные пакеты: 

npm install -D @swc/preset-env
npm install -D @swc/preset-typescript

Они расширяют поведение трансформера и позволяют настраивать целевые среды выполнения.

Также при интеграции с bundler’ами могут использоваться:

  • swc-loader для Webpack
  • интеграции с Vite через плагины
  • плагины для Jest

Проверка окружения Node.js

SWC требует актуальной версии Node.js, так как использует нативные бинарники.

Проверка версии: 

node -v

При несовместимости возможны ошибки загрузки бинарных модулей @swc/core. В этом случае требуется либо обновление Node.js, либо установка соответствующей версии SWC, собранной под конкретную платформу.

Кроссплатформенные особенности установки

@swc/core содержит prebuilt-бинарники для популярных платформ:

  • Windows x64
  • Linux x64 / ARM
  • macOS Intel / Apple Silicon

При установке пакет автоматически выбирает подходящий бинарник. Однако в редких случаях (например, нестандартные архитектуры) может потребоваться сборка из исходников.

Для этого используется Rust toolchain, и установка становится зависимой от наличия cargo и rustc.

Ошибки установки и их причины

Наиболее частые проблемы:

  • несовместимая версия Node.js
  • отсутствие подходящего бинарника для платформы
  • повреждённый cache npm/pnpm/yarn
  • конфликт lock-файлов в монорепозитории

Очистка npm cache: 

npm cache clean --force

Повторная установка зависимостей: 

rm -rf node_modules
npm install

В pnpm: 

pnpm store prune
pnpm install

Использование в связке с TypeScript

SWC не выполняет строгую проверку типов, поэтому в TypeScript-проектах он часто комбинируется с tsc –noEmit: 

npx tsc --noEmit
npx swc src -d dist

Такой подход разделяет ответственность:

  • TypeScript — проверка типов
  • SWC — трансформация и генерация кода

Это ускоряет сборку по сравнению с полной компиляцией через tsc.

Базовая структура проекта после установки

После добавления SWC типичный проект содержит: 

project/
 ├─ src/
 ├─ dist/
 ├─ package.json
 ├─ .swcrc

Файл .swcrc определяет конфигурацию трансформации и становится ключевым элементом работы SWC в проекте.

Оглавление