Полный перечень опций transform

Функция transform в esbuild предназначена для преобразования отдельных фрагментов кода без сборки проекта. Она используется для компиляции TypeScript, JSX, удаления типов, минификации и транспиляции синтаксиса под заданные версии JavaScript.

Ниже приведён полный перечень поддерживаемых опций transform, сгруппированный по назначению.

Основные опции трансформации

loader

Определяет, как интерпретировать входной код.

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

  • js — JavaScript
  • jsx — JavaScript с JSX
  • ts — TypeScript
  • tsx — TypeScript с JSX
  • json — JSON
  • css — CSS
  • text — текст
  • base64 — base64-кодирование
  • dataurl — data URL
  • binary — бинарные данные

Ключевой момент: loader влияет на парсинг исходного кода и определяет, какие синтаксические конструкции допустимы.

target

Определяет целевую версию JavaScript, под которую производится транспиляция.

Примеры значений:

  • es2015
  • es2016
  • es2017
  • es2018
  • es2019
  • es2020
  • es2021
  • es2022
  • esnext

Используется для преобразования современного синтаксиса (optional chaining, nullish coalescing и др.) в совместимый код.

format

Формат выходного кода.

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

  • esm — ES Modules
  • cjs — CommonJS
  • iife — Immediately Invoked Function Expression

Используется при подготовке кода для различных окружений: браузер, Node.js, CDN.

JSX и TypeScript

jsx

Определяет стратегию обработки JSX.

Варианты:

  • transform — классическая трансформация JSX в JS
  • preserve — JSX остаётся без изменений
  • automatic — новый JSX runtime (React 17+)

jsxFactory

Функция, используемая для создания JSX-элементов в классическом режиме.

По умолчанию:

React.createElement

Можно заменить на:

h

или любую пользовательскую функцию.

jsxFragment

Функция для обработки фрагментов JSX (<>...</>).

По умолчанию:

React.Fragment

jsxImportSource

Определяет источник для автоматического JSX runtime.

Пример:

"react"

или

"preact"

jsxDev

Включает dev-режим JSX (дополнительные проверки и более подробные сообщения об ошибках).

Тип: boolean

Минификация

minify

Включает полную минификацию кода.

Эквивалентно включению:

  • minifyWhitespace
  • minifyIdentifiers
  • minifySyntax

Тип: boolean

minifyWhitespace

Удаляет лишние пробелы, переносы строк и форматирование.

minifyIdentifiers

Сокращает имена переменных, функций и параметров.

minifySyntax

Оптимизирует синтаксис:

  • упрощает конструкции
  • удаляет избыточные элементы
  • заменяет выражения на более компактные формы

Source maps

sourcemap

Генерация source maps.

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

  • true — встроенная карта
  • false — отключено
  • "inline" — встроенная карта в код
  • "external" — отдельный файл source map

Используется для отладки транспилированного кода.

sourcefile

Имя исходного файла.

Используется в source maps для корректного отображения пути.

Управление синтаксисом и совместимостью

define

Позволяет заменять глобальные идентификаторы на константы во время трансформации.

Пример:

define: {
  "process.env.NODE_ENV": "\"production\""
}

Применяется для:

  • удаления условных веток
  • внедрения compile-time констант

drop

Удаляет определённые конструкции из кода.

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

  • "console" — удаляет все вызовы console.*
  • "debugger" — удаляет инструкции debugger

Можно комбинировать:

drop: ["console", "debugger"]

legalComments

Управляет обработкой лицензионных комментариев.

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

  • none — удалить все комментарии
  • inline — оставить inline
  • eof — перенести в конец файла
  • linked — вынести в отдельный файл

charset

Определяет кодировку выходного файла.

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

  • utf8
  • ascii

ascii используется для максимальной совместимости и уменьшения размера.

TypeScript-специфичные опции

tsconfigRaw

Позволяет передать конфигурацию TypeScript напрямую, без файла tsconfig.json.

Форматы:

  • строка JSON
  • объект конфигурации

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

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

Поведение кода и оптимизация

keepNames

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

Полезно для:

  • дебага
  • сериализации функций
  • reflection API

pure

Указывает функции, которые можно безопасно удалить при отсутствии побочных эффектов.

Пример:

pure: ["console.log", "debug"]

Сводная структура опций

transform(code, {
  loader,
  target,
  format,

  jsx,
  jsxFactory,
  jsxFragment,
  jsxImportSource,
  jsxDev,

  minify,
  minifyWhitespace,
  minifyIdentifiers,
  minifySyntax,

  sourcemap,
  sourcefile,

  define,
  drop,

  legalComments,
  charset,

  tsconfigRaw,
  keepNames,
  pure
})

Поведение комбинаций опций

Некоторые опции взаимодействуют между собой:

  • minify: true переопределяет все частичные minify-флаги
  • jsx: "automatic" требует корректного jsxImportSource
  • define применяется до минификации
  • drop выполняется до оптимизаций синтаксиса
  • sourcemap влияет только на структуру отладки, не изменяя AST

Особенности выполнения transform

  • transform работает без файловой системы
  • обрабатывает только переданный код
  • не выполняет бандлинг зависимостей
  • оптимизирован для быстрых однофайловых преобразований
  • используется как базовый строительный блок CLI и API esbuild
Оглавление