esbuild.build(): полная сигнатура и возвращаемые значения

esbuild.build() — асинхронная функция сборки, являющаяся основным программным интерфейсом пакета esbuild в режиме JavaScript API. Она принимает объект конфигурации типа BuildOptions и возвращает Promise, который разрешается в объект BuildResult. Поведение функции полностью определяется переданными опциями, включая стратегию бандлинга, вывод файлов, генерацию sourcemap, работу плагинов и режим инкрементальной сборки.

Типовая сигнатура в TypeScript-стиле:

function build(options: BuildOptions): Promise<BuildResult>

Где:

  • BuildOptions — объект конфигурации сборки
  • BuildResult — результат выполнения сборки

Функция всегда асинхронная и не блокирует поток выполнения. Внутри используется нативный Go-движок esbuild, а Node.js API выступает тонкой обёрткой.

BuildOptions: структура входных параметров

entryPoints

Точка входа или набор точек входа:

entryPoints: string[] | { [key: string]: string }

Варианты поведения:

  • массив строк — формирование одного или нескольких бандлов
  • объект — именованные выходные файлы

Пример:

entryPoints: ["src/index.js"]
entryPoints: {
  app: "src/app.js",
  admin: "src/admin.js"
}

bundle

bundle: boolean

Включает режим бандлинга.

  • true — выполняется рекурсивное объединение зависимостей
  • false — компиляция файлов без объединения импортов

При bundle: true активируется граф зависимостей, резолв модулей и tree shaking.

outfile и outdir

outfile: string
outdir: string
  • outfile — единый выходной файл (используется при одной точке входа)
  • outdir — директория для множества выходных файлов

При использовании entryPoints как объекта или массива с несколькими элементами outdir становится обязательным.

write

write: boolean

Определяет стратегию вывода:

  • true — запись файлов на диск
  • false — возврат файлов в памяти через outputFiles

При write: false esbuild работает как in-memory bundler, что часто используется в middleware и виртуальных файловых системах.

platform

platform: "browser" | "node" | "neutral"

Влияет на:

  • резолв встроенных модулей Node.js
  • поведение глобальных переменных
  • формат вывода

Особенности:

  • browser — приоритет Web API, исключение Node built-ins
  • node — сохранение Node.js-окружения
  • neutral — минимальные предположения о среде выполнения

format

format: "iife" | "esm" | "cjs"

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

  • iife — самовызывающаяся функция (для браузера без модулей)
  • esm — ES Modules
  • cjs — CommonJS

sourcemap

sourcemap: boolean | "inline" | "external" | "linked"

Режим генерации source maps:

  • false — отключены
  • true — внешние .map файлы
  • inline — встроенные в файл
  • external — отдельный файл .map
  • linked — связанный режим с ссылкой на карту

splitting

splitting: boolean

Активирует code splitting для ESM-формата.

Условия:

  • работает только при format: "esm"
  • требует bundle: true

Результат — несколько чанков с разделением общих зависимостей.

minify

minify: boolean

Эквивалент:

minifyWhitespace: true
minifyIdentifiers: true
minifySyntax: true

Снижает размер выходного кода за счёт:

  • удаления пробелов
  • сокращения идентификаторов
  • упрощения синтаксических конструкций

target

target: string | string[]

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

  • es2015, es2020, esnext
  • или список: ["es2020", "chrome58"]

Влияет на трансформации и синтаксис вывода.

loader

loader: {
  ".js": "js",
  ".ts": "ts",
  ".png": "file",
  ".css": "css"
}

Механизм определения обработки файлов по расширению.

Основные loader-типы:

  • js, ts
  • jsx, tsx
  • json
  • css
  • text
  • file
  • dataurl

external

external: string[]

Модули, исключаемые из бандла:

external: ["react", "react-dom"]

Импорты сохраняются как есть без инлайнинга.

define

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

Compile-time замены переменных.

Работает как макроподстановка до выполнения AST преобразований.

inject

inject: string[]

Файлы, содержимое которых автоматически вставляется в каждый входной модуль.

Используется для polyfill-подобных сценариев.

plugins

plugins: Plugin[]

Массив плагинов esbuild.

Плагин представляет объект с хук-функциями:

  • onResolve
  • onLoad

Позволяет расширять систему резолва и загрузки модулей.

incremental

incremental: boolean

Включает режим инкрементальной сборки.

При true функция возвращает дополнительный объект:

  • rebuild()
  • dispose()

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

metafile

metafile: boolean

При true формируется объект метаданных сборки.

Содержит:

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

BuildResult: структура результата

Основная сигнатура результата

interface BuildResult {
  errors: BuildFailure[]
  warnings: BuildFailure[]
  outputFiles?: OutputFile[]
  metafile?: Metafile
}

errors

Массив ошибок сборки:

errors: BuildFailure[]

Каждый элемент содержит:

  • текст ошибки
  • location (файл, строка, колонка)
  • подробности синтаксического или резолв-ошибочного характера

При наличии ошибок процесс сборки считается неуспешным.

warnings

warnings: BuildFailure[]

Структурно аналогичен errors, но не прерывает сборку.

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

  • неразрешённых импортов
  • deprecated API
  • потенциальных проблем tree shaking

outputFiles

outputFiles?: OutputFile[]

Появляется только при:

write: false

Каждый OutputFile содержит:

{
  path: string
  contents: Uint8Array
}

Особенности:

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

metafile

metafile?: Metafile

Возвращается при включении metafile: true.

Структура включает:

inputs

Список входных модулей и их зависимостей.

outputs

Описание каждого выходного файла:

  • входные источники
  • размеры
  • импортируемые модули

Пример структуры:

{
  "inputs": {
    "src/index.js": {
      "imports": [],
      "format": "esm"
    }
  },
  "outputs": {
    "dist/index.js": {
      "inputs": ["src/index.js"],
      "bytes": 12345
    }
  }
}

Поведение Promise результата

Promise, возвращаемый esbuild.build(), резолвится только после завершения всех стадий:

  1. Разбор входных файлов
  2. Построение графа зависимостей
  3. Трансформация AST
  4. Бандлинг (если включён)
  5. Минификация (если включена)
  6. Генерация output
  7. Запись на диск или формирование outputFiles

При ошибках Promise не отклоняется всегда — ошибки могут присутствовать в поле errors, даже при успешном resolve, если конфигурация допускает частичный вывод.

Взаимодействие опций и результирующих данных

write + outputFiles

write outputFiles
true undefined
false Array

metafile + build result

metafile result.metafile
false undefined
true Metafile object

incremental + rebuild

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

const result = await esbuild.build({
  entryPoints: ["src/index.js"],
  bundle: true,
  incremental: true
})

добавляется:

result.rebuild()
result.dispose()

Внутренние особенности исполнения build()

  • Использует параллельное выполнение на уровне Go runtime
  • Оптимизирован под минимальное потребление памяти
  • Избегает создания промежуточных AST в Node.js
  • Основная работа выполняется вне V8

Архитектура делает esbuild.build() одной из наиболее быстрых JS-сборок за счёт отказа от интерпретируемых этапов внутри Node.js слоя.

Оглавление