esbuild.transform(): полная сигнатура

Функция esbuild.transform() представляет собой низкоуровневый API библиотеки Esbuild, предназначенный для преобразования отдельного фрагмента исходного кода без участия файловой системы и без запуска полноценного процесса сборки. Она работает исключительно с переданной строкой кода и возвращает результат трансформации в виде структуры, содержащей преобразованный код, sourcemap, предупреждения и дополнительные метаданные.

Базовая форма функции:

esbuild.transform(input: string, options?: TransformOptions): Promise<TransformResult>

Синхронный аналог:

esbuild.transformSync(input: string, options?: TransformOptions): TransformResult

Ключевая особенность transform() — асинхронная природа, даже если внутри не выполняется I/O. Это связано с унификацией API Esbuild: все операции, потенциально входящие в пайплайн сборки, представлены в виде Promise-интерфейсов.

Параметры функции

input: string

Строка исходного кода, подлежащая преобразованию. Может содержать:

  • JavaScript (ESNext, ES5 и т.д.)
  • TypeScript
  • JSX / TSX
  • фрагменты кода без обёртки модулем

Esbuild не требует полной структуры проекта — достаточно валидного синтаксического фрагмента.

options: TransformOptions

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

Ключевые поля TransformOptions

loader: string

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

Основные значения:

  • "js" — JavaScript
  • "ts" — TypeScript
  • "jsx" — JavaScript с JSX
  • "tsx" — TypeScript с JSX
  • "json" — JSON как модуль
  • "text" — текстовый контент

Пример:

esbuild.transform(code, {
  loader: "ts"
})

sourcemap: boolean | “inline” | “external” | “both”

Управляет генерацией source map:

  • false — отключено
  • true — inline sourcemap
  • "inline" — встроенная карта
  • "external" — отдельный файл карты (в build-режиме)
  • "both" — оба варианта

В контексте transform() чаще всего используются true или "inline".

minify: boolean

Включает минификацию кода:

  • удаление пробелов
  • сокращение идентификаторов
  • упрощение выражений

Пример:

esbuild.transform(code, {
  minify: true
})

target: string | string[]

Определяет целевую версию Jav * aScript:

  • "es2015"
  • "es2017"
  • "es2020"
  • "esnext"

Можно задавать массив целей:

target: ["es2015", "chrome58", "firefox57"]

Esbuild подбирает наиболее строгий совместимый диалект.

jsxFactory: string

Определяет функцию создания JSX-элементов.

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

React.createElement

Пример изменения:

esbuild.transform(code, {
  jsxFactory: "h"
})

jsxFragment: string

Указывает фабрику для JSX-фрагментов:

esbuild.transform(code, {
  jsxFragment: "Fragment"
})

jsxImportSource: string

Используется при automatic JSX runtime (React 17+):

jsxImportSource: "react"

Позволяет управлять импортом функций JSX без явного указания jsxFactory.

define: Record<string, string>

Позволяет выполнять текстовую подстановку на этапе трансформации.

Пример:

esbuild.transform(code, {
  define: {
    "process.env.NODE_ENV": "\"production\""
  }
})

Это прямой препроцессор, работающий до анализа AST.

platform: “browser” | “node” | “neutral”

Определяет целевую среду выполнения:

  • "browser" — браузерные ограничения
  • "node" — Node.js окружение
  • "neutral" — отсутствие специфики

format: “iife” | “esm” | “cjs”

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

  • iife — немедленно вызываемая функция
  • esm — ES Modules
  • cjs — CommonJS

legalComments: “none” | “inline” | “eof” | “linked”

Управление сохранением комментариев лицензий:

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

charset: “utf8” | “ascii”

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

treeShaking: boolean

Хотя чаще используется в build(), в transform() влияет на удаление неиспользуемых выражений в рамках локального кода.

ast: boolean

Если установлено true, функция возвращает не только код, но и AST (Abstract Syntax Tree).

esbuild.transform(code, {
  ast: true
})

Это важно для инструментов анализа и метапрограммирования.

Возвращаемое значение: TransformResult

code: string

Результирующий JavaScript-код после трансформации.

Содержит:

  • транспиляцию TypeScript → JavaScript
  • преобразование JSX
  • минификацию (если включена)
  • подстановки define

map: string

Source map в формате JSON (обычно в виде строки).

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

  • отладки
  • трассировки исходного кода
  • интеграции с devtools

warnings: TransformMessage[]

Массив предупреждений компилятора.

Каждое предупреждение содержит:

  • текст сообщения
  • позицию в коде (line, column)
  • категорию (например, deprecated API)

errors: TransformMessage[]

Ошибки трансформации. В отличие от warnings, они могут прерывать процесс выполнения Promise.

ast: any (если включено)

Структура AST, зависящая от внутреннего формата Esbuild. Используется для:

  • статического анализа
  • построения собственных инструментов поверх Esbuild
  • интеграции с линтерами и анализаторами

Поведение трансформации

esbuild.transform() не выполняет:

  • чтение файлов
  • разрешение импортов
  • сборку зависимостей

Фактически он ограничен:

  • синтаксическим анализом
  • трансформацией AST
  • генерацией кода

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

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

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

Типовая структура вызова

const result = await esbuild.transform(sourceCode, {
  loader: "tsx",
  minify: true,
  sourcemap: "inline",
  target: "es2017",
  jsxFactory: "React.createElement",
  jsxFragment: "Fragment",
  define: {
    "process.env.NODE_ENV": "\"development\""
  }
})

Отличие от build API

transform():

  • работает со строкой
  • не обрабатывает зависимости
  • не использует entry points
  • возвращает единичный результат

build():

  • работает с файловой системой
  • строит граф зависимостей
  • формирует бандл

Синхронный вариант: transformSync

Полностью аналогичен по параметрам, но выполняется синхронно:

const result = esbuild.transformSync(code, {
  minify: true
})

Используется в средах, где невозможен async runtime (например, некоторые CLI-утилиты или ранние стадии загрузки приложений).

Поведение ошибок

Ошибки в transform() делятся на:

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

При наличии ошибок Promise отклоняется, а в sync-версии выбрасывается исключение.

Производительность

transform() оптимизирован для:

  • миллисекундных операций
  • массовой обработки строк
  • серверных runtime сценариев (SSR, edge functions)

Основной выигрыш достигается за счёт:

  • реализации на Go
  • отсутствия файлового I/O
  • минимизации аллокаций AST

Использование AST-режима

При включённом ast результат может использоваться как промежуточное представление:

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

Однако AST Esbuild не является стабильным публичным API в смысле долгосрочной совместимости, поэтому его использование ограничивается внутренними инструментами.

Влияние loader на пайплайн

loader определяет первичную стадию разбора:

  • TypeScript → удаление типов
  • JSX → преобразование в JS вызовы
  • JSON → превращение в экспортируемый объект

Далее применяется общий JS pipeline:

  • minify
  • define replacement
  • target transpilation

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

JSX обрабатывается независимо от основного синтаксиса JavaScript. В зависимости от конфигурации:

  • classic runtime использует jsxFactory и jsxFragment
  • automatic runtime использует jsxImportSource

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

Стабильность API

esbuild.transform() считается стабильной частью публичного API Esbuild. Изменения обычно касаются:

  • расширения TransformOptions
  • улучшения совместимости target
  • оптимизации генерации кода

Сигнатура и базовая модель результата остаются консистентными между версиями.

Оглавление