Передача конфигурации через флаги

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

Флаги CLI в SWC представляют собой атомарные параметры, которые:

• напрямую влияют на этапы трансформации;
• имеют приоритет над конфигурационными файлами;
• позволяют быстро переключать режимы работы;
• подходят для CI/CD и одноразовых запусков.

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

Базовая структура CLI-команды

SWC CLI использует следующую общую форму вызова:

swc <input> [options]

или при использовании пакетных сценариев:

swc src -d dist --options

Флаги могут изменять поведение компиляции как на уровне синтаксиса, так и на уровне генерации кода.

Основные категории флагов

Флаги входа и выхода

Эти параметры определяют, откуда берётся код и куда он записывается.

• -d, –out-dir — директория вывода
• -o, –out-file — единый файл результата
• –copy-files — копирование не-JS файлов
• –source-maps — генерация source maps

Пример:

swc src -d dist --source-maps

В данном случае компиляция сопровождается созданием карт соответствий исходного кода и итогового результата.

Флаги режима компиляции

Эти флаги определяют, как именно SWC интерпретирует код.

• –env — выбор целевой среды (browser, node и т.д.)
• –target — целевая версия ECMAScript
• –module — формат модулей (commonjs, esm, umd)
• –minify — включение минификации

Пример:

swc src -d dist --target es2020 --module commonjs

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

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

SWC использует иерархию источников конфигурации:

1. CLI-флаги
2. Файл конфигурации .swcrc
3. Значения по умолчанию

Это означает, что флаги всегда перекрывают настройки из .swcrc.

Пример .swcrc:

{
  "jsc": {
    "target": "es2019"
  }
}

При запуске:

swc src -d dist --target es2022

финальная цель компиляции будет es2022, несмотря на настройки файла.

Флаги JavaScript Compiler (jsc)

Большая часть конфигурации SWC относится к секции jsc, которая может частично переопределяться через CLI.

Target и трансформация синтаксиса

swc src -d dist --target es2018

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

Например:

• async/await может быть преобразован в генераторы;
• optional chaining может быть транспилирован в условные выражения;
• class fields могут быть преобразованы в assignment внутри конструктора.

Parser-флаги

Некоторые параметры влияют на парсер:

• –syntax — выбор диалекта (ecmascript, typescript, jsx)
• –tsx — включение поддержки TSX
• –decorators — поддержка декораторов

Пример:

swc src -d dist --syntax typescript --tsx

Это включает разбор TypeScript и JSX одновременно.

Флаги модуля

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

swc src -d dist --module esm

Доступные режимы:

• commonjs
• esm
• umd
• amd

Преобразование модулей влияет на:

• способ импорта зависимостей;
• структуру экспортов;
• совместимость с рантаймом.

Флаги минификации

Минификация в SWC может быть активирована через CLI:

swc src -d dist --minify

Минификация включает:

• удаление пробелов и комментариев;
• переименование идентификаторов;
• упрощение выражений;
• устранение мёртвого кода (в зависимости от конфигурации).

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

Source maps и отладка

swc src -d dist --source-maps

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

Варианты генерации:

• inline source maps;
• external .map файлы;
• отключение генерации.

Флаг влияет на доступность отладки в браузере и Node.js.

Взаимодействие флагов между собой

Некоторые флаги могут конфликтовать или перекрывать друг друга.

Пример конфликтов

• –minify и –source-maps одновременно увеличивают размер выходного процесса сборки
• –module esm и –module commonjs являются взаимоисключающими

SWC разрешает конфликты по принципу:

• последний применённый флаг имеет приоритет;
• либо CLI-валидатор выбрасывает ошибку при несовместимости.

Передача сложных конфигураций через CLI

Несмотря на наличие флагов, часть конфигурации может передаваться в виде JSON-строк.

Пример:

swc src -d dist –config &

В этом случае CLI-флаги и JSON-конфигурация объединяются, но CLI всё
равно имеет приоритет.


Переменные окружения и их взаимодействие с флагами


Хотя флаги являются основным способом управления поведением SWC,
переменные окружения могут влиять на вспомогательные аспекты:



режим выполнения (development/production);


включение debug-логов;


пути к конфигурационным файлам.



Однако приоритет остаётся за CLI-параметрами.


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


Типичный сценарий интеграции:

{
  "scripts": {
    "build": "swc src -d dist --target es2020 --module commonjs",
    "build:prod": "swc src -d dist --minify --source-maps"
  }
}

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


Поведение флагов в watch-режиме

swc src -d dist --watch

Watch-режим отслеживает изменения файлов и пересобирает проект.


При использовании дополнительных флагов:

swc src -d dist --watch --source-maps

каждая пересборка будет сопровождаться актуализацией source maps и
применением текущей конфигурации.


Стабильность и воспроизводимость сборки


Передача конфигурации через флаги особенно важна для:



CI/CD пайплайнов;


контейнеризированных сборок;


изолированных окружений.



Флаги обеспечивают:



отсутствие зависимости от локальных файлов конфигурации;


явное описание поведения компиляции;


упрощение диагностики ошибок сборки.