Конфигурационный файл .swcrc: формат и расположение

Файл .swcrc является центральной точкой конфигурации для SWC (Speedy Web Compiler) и определяет, каким образом исходный JavaScript или TypeScript код будет трансформироваться. Он описывает правила компиляции, плагины, пресеты, параметры JSX, модульную систему и множество других аспектов, влияющих на результат сборки.

Файл .swcrc представляет собой JSON-документ. Это принципиальный момент: несмотря на то, что SWC поддерживает разные способы конфигурации (в том числе через JavaScript API и swc.config.js в некоторых сценариях), именно JSON-формат считается стандартным и наиболее широко используемым.

Структурно файл выглядит как объект верхнего уровня, содержащий набор ключей конфигурации: 

{
  "jsc": {
    "parser": {
      "syntax": "typescript"
    },
    "transform": null
  },
  "module": {
    "type": "es6"
  },
  "minify": false
}

Особенности JSON-формата

  • Используются только двойные кавычки
  • Запрещены комментарии (в отличие от некоторых расширенных конфигов других инструментов)
  • Не допускаются trailing commas
  • Все значения строго типизированы (строки, числа, булевы значения, массивы, объекты)

Любая ошибка в синтаксисе приводит к падению компиляции, поэтому .swcrc должен быть валидным JSON.

Расположение файла .swcrc

SWC автоматически ищет файл .swcrc в файловой системе, начиная с директории запуска процесса.

Базовый сценарий поиска

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

  1. Проверяется текущая рабочая директория
  2. Если файл не найден, поиск продолжается вверх по дереву директорий
  3. При наличии нескольких конфигураций используется ближайшая к обрабатываемым файлам

Таким образом, .swcrc может быть размещён:

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

Пример структуры проекта 

project/
  .swcrc
  package.json
  src/
    index.ts
    utils.ts

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

Монорепозитории и локальные конфигурации

В монорепозиториях возможна ситуация, когда каждый пакет имеет собственный .swcrc: 

repo/
  packages/
    frontend/
      .swcrc
      src/
    backend/
      .swcrc
      src/

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

Структура конфигурационного объекта

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

  1. jsc — ядро трансформации JavaScript

Основной блок конфигурации, определяющий поведение компилятора: 

{
  "jsc": {
 "parser": {},
 "transform": {},
 "target": "es2020"
  }
}

parser

Отвечает за разбор исходного кода.

Пример: 

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

Возможные значения:

  • syntax: “ecmascript” | “typescript”
  • tsx: включает поддержку JSX в TypeScript
  • decorators: включает декораторы
  • dynamicImport: поддержка import()

transform

Определяет правила трансформации AST. 

"transform": {
  "react": {
 "runtime": "automatic"
  }
}

Используется для:

  • JSX трансформации
  • оптимизаций
  • работы с React runtime
  • макросов и кастомных преобразований

target

Указывает целевую версию ECMAScript: 

"target": "es2018"

Чем ниже target, тем более агрессивные преобразования применяются.

  1. module — система модулей

Блок определяет формат выходных модулей. 

{
  "module": {
 "type": "commonjs"
  }
}

Поддерживаемые типы

  • es6 — ES Modules
  • commonjs — CommonJS
  • umd — универсальный формат
  • amd — устаревший модульный стандарт

Дополнительные параметры 

"module": {
  "type": "es6",
  "strict": true,
  "noInterop": false
}
  • strict — строгая модульная семантика
  • noInterop — отключение interop между CJS и ESM

  1. minify — минификация

SWC может использоваться как минификатор. 

{
  "minify": true
}

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

"minify": {
  "compress": {
 "unused": true
  },
  "mangle": true
}

Компоненты минификации

  • compress — удаление мёртвого кода, упрощение выражений
  • mangle — переименование переменных
  • format — управление стилем вывода

  1. sourceMaps

Управление генерацией sourcemaps: 

{
  "sourceMaps": true
}

Возможные значения:

  • true — генерация inline или external maps
  • false — отключение
  • “inline” — встроенные карты
  • “external” — отдельные .map файлы

  1. exclude и include

Контроль области применения конфигурации: 

{
  "exclude": ["node_modules"],
  "include": ["src"]
}

Особенности работы

  • пути задаются относительно директории .swcrc
  • поддерживаются glob-шаблоны
  • exclude имеет приоритет над include

Локальные и каскадные конфигурации

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

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

Пример поведения: 

root/.swcrc
packages/app/.swcrc

Если в корневом файле задан: 

{
  "module": { "type": "commonjs" }
}

а в локальном: 

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

то для packages/app будет использоваться es6.

Альтернативные пути конфигурации

Хотя .swcrc является стандартом, SWC также поддерживает:

  • передачу конфигурации через CLI (–config-file)
  • программную конфигурацию через API
  • интеграцию в сборщики (Webpack, Vite, Next.js)

Однако в этих случаях часто используется именно .swcrc как базовый источник.

Валидация конфигурации

SWC не выполняет «мягкую» интерпретацию ошибок. При нарушении структуры:

  • неизвестные ключи игнорируются или приводят к предупреждениям
  • неправильные типы значений вызывают ошибки трансформации
  • некорректный JSON полностью останавливает процесс

Типичные ошибки:

  • использование строк вместо boolean
  • неправильные значения syntax
  • конфликтующие параметры module.type и jsc.target

Практическая структура .swcrc

Типичный файл для TypeScript-проекта: 

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

Для React-проекта: 

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

Для библиотек с CommonJS: 

{
  "jsc": {
 "parser": {
"syntax": "ecmascript"
 },
 "target": "es2017"
  },
  "module": {
 "type": "commonjs"
  }
}
Оглавление