Установка и использование @swc/cli

Пакет @swc/cli предоставляет интерфейс командной строки для компилятора SWC. Он используется для запуска трансформации исходного кода непосредственно из терминала без необходимости писать собственные скрипты на Node.js.

CLI-инструмент позволяет:

компилировать отдельные файлы;
обрабатывать целые каталоги;
преобразовывать современный JavaScript в совместимый код для старых сред выполнения;
компилировать TypeScript;
преобразовывать JSX и TSX;
автоматически отслеживать изменения файлов;
копировать дополнительные ресурсы в каталог сборки;
генерировать карты исходников (Source Maps).

В большинстве проектов пакет устанавливается совместно с основным компилятором @swc/core.

Установка

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

npm install --save-dev @swc/cli @swc/core

Для Yarn:

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

Для pnpm:

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

После установки в проекте становится доступна команда:

swc

Проверка работоспособности:

npx swc --version

Пример вывода:

@swc/cli: 0.x.x
@swc/core: 1.x.x

Базовая компиляция файла

Пусть имеется файл:

const user = {
    name: "Alex"
};

console.log(user?.name);

Компиляция выполняется командой:

npx swc app.js

Результат будет выведен в консоль.

Для сохранения результата в файл используется параметр -o:

npx swc app.js -o dist/app.js

После выполнения появится файл:

var user = {
    name: "Alex"
};

console.log(user === null || user === void 0 ? void 0 : user.name);

Компиляция каталога

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

Структура проекта:

src/
├── app.js
├── utils.js
└── api.js

Компиляция каталога:

npx swc src -d dist

Параметры:

Параметр	Назначение
`src`	исходный каталог
`-d dist`	каталог назначения

Результат:

dist/
├── app.js
├── utils.js
└── api.js

Структура каталогов сохраняется автоматически.

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

Большинство настроек хранится в файле .swcrc.

Пример:

{
  "jsc": {
    "target": "es2020"
  }
}

После создания файла достаточно выполнить:

npx swc src -d dist

SWC автоматически загрузит настройки.

Компиляция TypeScript

Одной из наиболее востребованных возможностей является трансформация TypeScript.

Исходный файл:

interface User {
    name: string;
}

const user: User = {
    name: "Alex"
};

console.log(user);

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

{
  "jsc": {
    "parser": {
      "syntax": "typescript"
    }
  }
}

Запуск:

npx swc src -d dist

Результат:

const user = {
    name: "Alex"
};

console.log(user);

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

Компиляция TSX

Для React-проектов часто используется TSX.

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

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

Пример компонента:

export function App() {
    return <h1>Hello</h1>;
}

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

Компиляция JSX

Для JavaScript-проектов без TypeScript используется режим ECMAScript.

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

{
  "jsc": {
    "parser": {
      "syntax": "ecmascript",
      "jsx": true
    }
  }
}

Пример:

function App() {
    return <div>Hello</div>;
}

Компиляция:

npx swc src -d dist

Указание целевой версии JavaScript

Параметр target определяет, в какую версию ECMAScript будет преобразован код.

Пример:

{
  "jsc": {
    "target": "es5"
  }
}

Допустимые значения:

es3
es5
es2015
es2016
es2017
es2018
es2019
es2020
es2021
es2022
es2023
esnext

Чем ниже версия, тем больше современных конструкций будет преобразовано.

Например:

const result = data?.name;

При цели es5 превращается в более длинный код совместимости.

Использование Source Maps

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

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

{
  "sourceMaps": true
}

Или через CLI:

npx swc src -d dist --source-maps

После сборки рядом с файлами появляются карты:

app.js
app.js.map

Преимущества:

удобная отладка;
корректные стек-трейсы;
отображение исходного кода в браузере.

Наблюдение за изменениями

Во время разработки полезен режим автоматической перекомпиляции.

Команда:

npx swc src -d dist --watch

После запуска процесс остаётся активным.

При изменении файла:

src/app.js

SWC автоматически пересобирает соответствующий результат в каталоге:

dist/app.js

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

Копирование дополнительных файлов

Проект может содержать файлы, не требующие компиляции:

src/
├── index.js
├── styles.css
├── config.json
└── image.png

Для копирования таких ресурсов используется флаг:

npx swc src -d dist --copy-files

Результат:

dist/
├── index.js
├── styles.css
├── config.json
└── image.png

Все неподдерживаемые файлы будут перенесены без изменений.

Игнорирование файлов

Иногда требуется исключить часть файлов из обработки.

Пример:

npx swc src -d dist --ignore "**/*.test.js"

Файлы:

user.test.js
api.test.js

будут пропущены.

Можно указывать несколько шаблонов:

npx swc src -d dist \
  --ignore "**/*.test.js" \
  --ignore "**/*.spec.js"

Использование расширений файлов

По умолчанию SWC распознаёт стандартные расширения.

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

npx swc src -d dist \
  --extensions .js,.jsx,.ts,.tsx

Это особенно полезно в смешанных проектах.

Компиляция отдельных расширений

Допустим, проект содержит:

src/
├── app.ts
├── button.tsx
├── util.js

Компиляция только TypeScript-файлов:

npx swc src -d dist \
  --extensions .ts,.tsx

Файл:

util.js

будет проигнорирован.

Использование npm-скриптов

На практике команды SWC обычно размещаются в package.json.

Пример:

{
  "scripts": {
    "build": "swc src -d dist",
    "dev": "swc src -d dist --watch"
  }
}

Запуск сборки:

npm run build

Режим разработки:

npm run dev

Такой подход делает команды единообразными для всей команды разработки.

Очистка каталога перед сборкой

Распространённая практика — удалять старые файлы перед компиляцией.

Пример:

{
  "scripts": {
    "clean": "rimraf dist",
    "build": "npm run clean && swc src -d dist"
  }
}

Последовательность выполнения:

удаляется каталог dist;
запускается новая компиляция;
создаётся актуальная версия сборки.

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

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

Пример:

.swcrc
.swcrc.dev
.swcrc.prod

Конкретный файл конфигурации можно передать через параметры CLI.

Подобный подход позволяет создавать отдельные настройки для:

разработки;
тестирования;
production-сборок;
серверного кода;
браузерного кода.

Интеграция с Node.js

Частый сценарий — компиляция серверного кода.

Исходник:

export const getUser = async () => {
    return {
        id: 1
    };
};

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

{
  "jsc": {
    "target": "es2020",
    "parser": {
      "syntax": "typescript"
    }
  },
  "module": {
    "type": "commonjs"
  }
}

Компиляция:

npx swc src -d dist

Полученный код будет совместим с традиционной средой Node.js, использующей CommonJS.

Интеграция с ES Modules

Для современных проектов можно использовать формат ESM.

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

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

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

import { sum } from "./math.js";

export const result = sum(1, 2);

После компиляции структура модулей сохраняется в формате ECMAScript Modules.

Производительность CLI

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

Причины высокой производительности:

реализация на языке Rust;
эффективное использование памяти;
многопоточная обработка;
оптимизированный парсер;
минимальные накладные расходы во время трансформации.

На крупных проектах разница между SWC и традиционными JavaScript-компиляторами может составлять несколько раз, особенно при обработке больших объёмов TypeScript и JSX-кода.

Наиболее полезные параметры CLI

Параметр	Назначение
`-d`	каталог назначения
`-o`	выходной файл
`–watch`	отслеживание изменений
`–copy-files`	копирование ресурсов
`–source-maps`	генерация Source Maps
`–ignore`	исключение файлов
`–extensions`	список расширений
`–quiet`	уменьшение количества сообщений
`–config-file`	указание конфигурации
`–version`	вывод версии
`–help`	справка по CLI

Типичная структура проекта с `@swc/cli`

project/
├── src/
│   ├── components/
│   ├── pages/
│   ├── utils/
│   └── index.ts
├── dist/
├── package.json
├── .swcrc
└── tsconfig.json

Файл .swcrc:

{
  "sourceMaps": true,
  "jsc": {
    "target": "es2020",
    "parser": {
      "syntax": "typescript",
      "tsx": true
    }
  }
}

Скрипты:

{
  "scripts": {
    "build": "swc src -d dist",
    "dev": "swc src -d dist --watch"
  }
}

Команда сборки:

npm run build

В результате весь исходный код из каталога src преобразуется согласно настройкам SWC и помещается в каталог dist, готовый для запуска, публикации или дальнейшей упаковки другими инструментами сборки.

Установка и использование @swc/cli

Установка

Базовая компиляция файла

Компиляция каталога

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

Компиляция TypeScript

Компиляция TSX

Компиляция JSX

Указание целевой версии JavaScript

Использование Source Maps

Наблюдение за изменениями

Копирование дополнительных файлов

Игнорирование файлов

Использование расширений файлов

Компиляция отдельных расширений

Использование npm-скриптов

Очистка каталога перед сборкой

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

Интеграция с Node.js

Интеграция с ES Modules

Производительность CLI

Наиболее полезные параметры CLI

Типичная структура проекта с @swc/cli

Типичная структура проекта с `@swc/cli`