Поле jsc: настройка компилятора JavaScript

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

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

{
  "jsc": {
    "parser": {},
    "transform": {},
    "target": "es2015",
    "loose": false,
    "externalHelpers": false,
    "keepClassNames": false,
    "minify": {},
    "experimental": {}
  }
}

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

parser: настройка разбора исходного кода

Поле parser определяет, как SWC интерпретирует входной JavaScript или TypeScript код. От правильной настройки зависит корректность построения AST.

Основные варианты:

  • syntax — выбор языка
  • jsx — поддержка JSX
  • decorators — декораторы
  • dynamicImport — динамический import()
  • privateMethod — приватные методы классов
  • functionBind — оператор привязки ::

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

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

syntax

Ключ syntax определяет базовый язык:

  • ecmascript — JavaScript
  • typescript — TypeScript

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

JSX и TSX

При работе с React-подобными системами активируется: 

{
  "jsx": true,
  "tsx": true
}

Это позволяет корректно обрабатывать JSX-элементы и типизированные TSX-файлы.

decorators

Поддержка декораторов критична для фреймворков уровня NestJS и Angular-подобных архитектур: 

{
  "decorators": true,
  "decoratorsBeforeExport": true
}

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

transform: система преобразований AST

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

{
  "jsc": {
    "transform": {
      "react": {},
      "optimizer": {},
      "legacyDecorator": false
    }
  }
}

react: трансформация JSX

Блок react управляет преобразованием JSX в вызовы функций. 

{
  "jsc": {
    "transform": {
      "react": {
        "runtime": "automatic",
        "importSource": "react",
        "throwIfNamespace": true,
        "development": false
      }
    }
  }
}

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

  • runtime

    • classic — старый JSX трансформ
    • automatic — новый JSX Transform без явного React.createElement

  • importSource Определяет источник функций JSX runtime.

  • development Добавляет дополнительные проверки и отладочные вызовы.

optimizer: оптимизация AST

Оптимизатор снижает размер и сложность итогового кода. 

{
  "optimizer": {
    "globals": {
      "vars": true,
      "typeofs": true
    }
  }
}

Оптимизация глобальных значений позволяет выполнять статическое сворачивание выражений:

  • удаление мёртвого кода
  • инлайнинг констант
  • упрощение typeof проверок

legacyDecorator

Поддержка старого поведения декораторов: 

{
  "legacyDecorator": true
}

Используется при миграции проектов с Babel или устаревших TypeScript-конфигураций.

target: целевая версия JavaScript

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

{
  "jsc": {
    "target": "es2017"
  }
}

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

  • es3
  • es5
  • es2015
  • es2016 – es2022
  • esnext

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

loose: упрощённые трансформации

Флаг loose включает упрощённые (менее спецификационно точные) преобразования. 

{
  "jsc": {
    "loose": true
  }
}

Включение режима приводит к:

  • более короткому и быстрому коду
  • снижению точности соответствия спецификации ECMAScript
  • потенциальным отличиям в edge-case поведении

Типичный пример — упрощённая эмуляция классов и наследования.

externalHelpers: вынесенные вспомогательные функции

SWC при трансформации часто генерирует вспомогательные функции (helpers). Поле externalHelpers управляет их источником. 

{
  "jsc": {
    "externalHelpers": true
  }
}

При включении:

  • helpers не вставляются в каждый файл
  • вместо этого используется единый пакет @swc/helpers

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

  • уменьшение размера бандла
  • устранение дублирования кода
  • улучшение кеширования

keepClassNames: сохранение имён классов

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

{
  "jsc": {
    "keepClassNames": true
  }
}

Это важно для:

  • dependency injection
  • логирования и диагностики
  • runtime reflection

minify внутри jsc

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

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

Основные элементы:

  • compress — логическое упрощение кода
  • mangle — переименование идентификаторов
  • unused — удаление неиспользуемого кода

experimental: экспериментальные возможности

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

{
  "jsc": {
    "experimental": {
      "plugins": []
    }
  }
}

Чаще всего используется для:

  • интеграции кастомных SWC-плагинов
  • тестирования новых трансформаций AST
  • расширения поведения компилятора

Пример полной конфигурации jsc 

{
  "jsc": {
    "target": "es2020",
    "parser": {
      "syntax": "typescript",
      "tsx": true,
      "decorators": true,
      "dynamicImport": true
    },
    "transform": {
      "react": {
        "runtime": "automatic",
        "development": false
      },
      "optimizer": {
        "globals": {
          "vars": true
        }
      }
    },
    "loose": false,
    "externalHelpers": true,
    "keepClassNames": false,
    "minify": {
      "compress": {
        "unused": true
      },
      "mangle": true
    }
  }
}

Влияние jsc на пайплайн компиляции

jsc фактически определяет поведение всего трансформационного слоя SWC. Изменение одного параметра может повлиять сразу на несколько этапов:

  • парсер → структура AST
  • трансформер → семантика кода
  • target → уровень совместимости
  • helpers → размер и модульность сборки

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

  • производительностью компиляции
  • размером итогового кода
  • соответствием стандартам ECMAScript
  • совместимостью с окружениями выполнения
Оглавление