Конфигурация через package.json

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

Основной механизм настройки заключается в добавлении поля swc в корневой package.json. Внутри него описывается конфигурация, аналогичная .swcrc, но встроенная в структуру проекта. 

{
  "name": "example-project",
  "version": "1.0.0",
  "swc": {
    "jsc": {
      "parser": {
        "syntax": "ecmascript",
        "jsx": false
      },
      "target": "es2020"
    },
    "module": {
      "type": "es6"
    }
  }
}

При наличии одновременно .swcrc и package.json с полем swc, поведение зависит от используемого инструмента: чаще всего приоритет отдаётся .swcrc, однако многие интеграции позволяют явно переключать источник конфигурации.

Структура конфигурации SWC

Конфигурация делится на несколько ключевых секций:

  • jsc — настройки JavaScript/TypeScript компиляции
  • module — управление системой модулей
  • minify — параметры минификации
  • sourceMaps — генерация source maps
  • env — трансформации под окружения

Каждая секция отвечает за отдельный этап обработки кода.

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

jsc (JavaScript Compiler) определяет, как SWC парсит и трансформирует исходный код. 

{
  "swc": {
    "jsc": {
      "target": "es2019",
      "parser": {
        "syntax": "typescript",
        "tsx": true,
        "decorators": true,
        "dynamicImport": true
      }
    }
  }
}

parser.syntax

Определяет язык входного кода:

  • ecmascript — JavaScript
  • typescript — TypeScript
  • jsx — React JSX (через jsx: true)

Поддержка TypeScript

SWC не выполняет type-checking, а только удаляет типы: 

{
  "swc": {
    "jsc": {
      "parser": {
        "syntax": "typescript"
      },
      "target": "es2020"
    }
  }
}

Важно учитывать: ошибки типов не будут обнаружены на этапе трансформации, для этого используется tsc –noEmit.

Настройка JSX

Для React-проектов включается обработка JSX: 

{
  "swc": {
    "jsc": {
      "parser": {
        "syntax": "typescript",
        "tsx": true
      },
      "transform": {
        "react": {
          "runtime": "automatic",
          "importSource": "react"
        }
      }
    }
  }
}

Ключевые параметры:

  • runtime: “automatic” — использование нового JSX runtime
  • runtime: “classic” — классический React.createElement
  • importSource — источник JSX runtime (например, react или preact)

Управление модулями

Секция module определяет формат выходных модулей: 

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

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

  • es6 — ESM
  • commonjs — CommonJS
  • amd, umd, systemjs — реже используемые форматы

Пример для Node.js окружения: 

{
  "swc": {
    "module": {
      "type": "commonjs",
      "strict": true,
      "lazy": false
    }
  }
}

Параметр lazy позволяет откладывать загрузку модулей, что может быть полезно в больших приложениях.

Минификация через package.json

SWC включает встроенный минификатор, который также настраивается через swc: 

{
  "swc": {
    "minify": true
  }
}

Расширенная конфигурация: 

{
  "swc": {
    "minify": {
      "compress": {
        "unused": true,
        "dead_code": true
      },
      "mangle": {
        "topLevel": false
      }
    }
  }
}

compress

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

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

mangle

Сокращает имена переменных:

  • topLevel: true — включает обфускацию глобальных переменных
  • полезно для production-сборок, но может ломать внешние API

Source Maps

Для отладки важно сохранять соответствие исходного и скомпилированного кода: 

{
  "swc": {
    "sourceMaps": true
  }
}

Варианты:

  • true — генерация inline или external source maps
  • false — отключение
  • “inline” — встроенные карты

В связке с бандлерами source maps часто передаются дальше в webpack или vite pipeline.

Env-трансформации

Раздел env позволяет адаптировать код под целевые окружения: 

{
  "swc": {
    "env": {
      "targets": {
        "chrome": "100",
        "node": "18"
      },
      "mode": "entry"
    }
  }
}

targets

Определяет минимальные версии сред выполнения.

mode

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

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

Типичный пример package.json для проекта на SWC: 

{
  "name": "app",
  "version": "2.0.0",
  "swc": {
    "jsc": {
      "target": "es2020",
      "parser": {
        "syntax": "typescript",
        "tsx": true,
        "decorators": true
      },
      "transform": {
        "react": {
          "runtime": "automatic"
        }
      }
    },
    "module": {
      "type": "es6"
    },
    "sourceMaps": true,
    "minify": false,
    "env": {
      "targets": {
        "node": "18"
      }
    }
  }
}

Такая конфигурация подходит для серверных приложений, где важна совместимость с современным Node.js и поддержка TypeScript.

Поведение конфигурации в разных инструментах

SWC используется через разные интеграции:

  • @swc/core
  • @swc/cli
  • swc-loader (webpack)
  • next.js (внутренняя интеграция)

Каждая среда может по-своему интерпретировать package.json:

  • CLI обычно читает конфигурацию напрямую
  • webpack-loader может переопределять настройки через loader options
  • фреймворки (например, Next.js) частично игнорируют пользовательские поля ради стабильности сборки

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

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

  1. Параметры, переданные в runtime (CLI flags, loader options)
  2. .swcrc
  3. package.json → swc
  4. значения по умолчанию

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

Особенности наследования и монорепозитории

В монорепозиториях package.json с swc может быть определён на уровне каждого пакета. В этом случае важно учитывать:

  • отсутствие глобального объединения конфигураций
  • независимую интерпретацию каждого package.json
  • необходимость синхронизации targets и module.type

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

Ограничения конфигурации через package.json

Несмотря на удобство, подход имеет ограничения:

  • сложнее разделять dev/prod конфигурации
  • отсутствует условная логика (в отличие от JS-конфигов)
  • большие конфигурации ухудшают читаемость package.json
  • некоторые инструменты игнорируют swc в пользу .swcrc

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

Совместимость с TypeScript и Babel-подобными пайплайнами

Конфигурация SWC в package.json часто используется как замена Babel:

  • более высокая скорость компиляции
  • меньшая нагрузка на CPU
  • упрощённая архитектура конфигурации

Однако набор плагинов и трансформаций менее гибкий по сравнению с Babel, что отражается на ограниченной расширяемости через package.json.

Оглавление