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

Входные точки и управление входом/выходом

entryPoints Массив входных файлов или точек приложения. Может принимать строки или объект для именованных выходов.

  • Строки: entryPoints: ["src/index.js"]
  • Объект: entryPoints: { app: "src/index.js", admin: "src/admin.js" }

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

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

Основные параметры:

  • contents — строка с кодом
  • resolveDir — базовая директория для резолва импортов
  • sourcefile — виртуальное имя файла
  • loader — тип загрузчика

outfile Путь к единственному выходному файлу. Используется только при одной точке входа и без code splitting.

outdir Каталог для вывода файлов при нескольких entry points или code splitting.

outbase Базовая директория, которая сохраняется в структуре выходных путей. Позволяет сохранять относительные пути.

write Булевый флаг:

  • true — записывать файлы на диск
  • false — возвращать результат в памяти (in-memory output)

allowOverwrite Разрешает перезапись существующих файлов в выходной директории.

publicPath Базовый публичный URL для ресурсов (особенно полезно для CSS, ассетов и динамических импортов).

Режим сборки и структура бандла

bundle Включает или отключает бандлинг.

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

splitting Включает code splitting для ESM формата.

Требования:

  • format: "esm"
  • bundle: true

format Формат вывода:

  • iife — самовызывающийся скрипт
  • cjs — CommonJS
  • esm — ES Modules

platform Целевая платформа:

  • browser
  • node
  • neutral

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

target Уровень поддержки Jav * aScript:

Примеры:

  • es2015
  • es2020
  • esnext

Определяет, какие синтаксические конструкции будут транспилироваться.

Минификация и оптимизация

minify Сокращение кода:

  • minify: true включает все виды минификации:

    • minifyWhitespace
    • minifyIdentifiers
    • minifySyntax

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

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

minifySyntax Оптимизирует синтаксические конструкции (упрощение выражений, удаление лишнего кода).

treeShaking Автоматическое удаление неиспользуемого кода. В Esbuild включено по умолчанию при bundle: true.

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

Source maps

sourcemap Управляет генерацией карт исходного кода:

  • false — отключено
  • true — inline или отдельный файл (зависит от окружения)
  • "inline" — встроенная карта
  • "external" — отдельный файл .map
  • "both" — и inline, и external

sourcesContent Встраивает исходный код в sourcemap для упрощения отладки.

Обработка модулей и расширений

loader Определяет способ обработки файлов по расширению.

Примеры:

  • ".js": "js"
  • ".ts": "ts"
  • ".json": "json"
  • ".css": "css"
  • ".png": "file"
  • ".txt": "text"

Позволяет расширять поддержку нестандартных типов ресурсов.

resolveExtensions Список расширений, используемых при резолве импортов.

Пример:

resolveExtensions: [".ts", ".tsx", ".js", ".jsx"]

mainFields Определяет приоритет полей package.json при резолве зависимостей:

Пример:

mainFields: ["module", "main"]

conditions Условия резолва в package exports:

Пример:

conditions: ["import", "browser", "default"]

Работа с зависимостями

external Массив модулей, которые не должны попадать в бандл.

Примеры:

  • "react"
  • "lodash/*"

inject Позволяет автоматически вставлять импорты в каждый модуль.

Пример:

inject: ["./shims/process.js"]

define Статическая замена переменных на этапе сборки.

Пример:

define: {
  "process.env.NODE_ENV": '"production"',
  __VERSION__: '"1.0.0"'
}

JSX и TypeScript

jsx Режим обработки JSX:

  • transform — стандартный JSX трансформ
  • preserve — оставить JSX как есть
  • automatic — новый JSX runtime

jsxFactory Функция создания элементов JSX (устаревший режим).

jsxFragment Фрагмент JSX (например React.Fragment).

jsxImportSource Источник runtime для automatic JSX (например react).

tsconfig Путь к файлу TypeScript конфигурации. Используется для синхронизации настроек компиляции.

Плагины и расширяемость

plugins Массив плагинов Esbuild.

Плагин представляет собой объект с:

  • name
  • setup(build)

Позволяет:

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

Метаданные и анализ

metafile Включает генерацию метафайла сборки.

Содержит:

  • граф зависимостей
  • размеры модулей
  • входы/выходы

Используется для анализа бандла и оптимизации.

logLevel Уровень логирования:

  • silent
  • error
  • warning
  • info
  • debug

logLimit Ограничивает количество выводимых сообщений.

Watch, serve и инкрементальная сборка

watch Включает наблюдение за файлами и автоматическую пересборку.

Пример:

watch: {
  onRebuild(error, result) {}
}

serve Запускает встроенный HTTP-сервер.

Параметры:

  • port
  • host
  • servedir

incremental Включает инкрементальную сборку, позволяющую переиспользовать кэш между билдами.

Системные и служебные настройки

absWorkingDir Абсолютная рабочая директория для резолва путей.

charset Управление кодировкой вывода:

  • utf8 (по умолчанию)
  • ascii (для минимизации размера)

color Включает цветной вывод логов:

  • true
  • false
  • auto

banner Строка или объект, добавляемый в начало каждого выходного файла.

footer Строка или объект, добавляемый в конец каждого выходного файла.

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

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

nodePaths Дополнительные пути для резолва модулей Node.js.

supported Флаги включения/отключения отдельных возможностей трансформации в зависимости от окружения.

format-specific behavior summary (взаимосвязи опций)

Некоторые опции работают только в комбинации:

  • splitting требует format: esm
  • outdir обязателен при множественных entry points
  • outfile несовместим с code splitting
  • watch и incremental усиливают друг друга, но решают разные задачи
  • define и inject влияют на AST до оптимизации и минификации

behavioral pipeline build (логика применения опций)

  1. Резолв модулей (entryPoints, resolveExtensions, mainFields, conditions)
  2. Загрузка (loader, plugins)
  3. Преобразование (jsx, tsconfig)
  4. Инлайн трансформации (define, inject)
  5. Бандлинг (bundle, external, splitting)
  6. Оптимизация (treeShaking, minify*)
  7. Генерация вывода (format, target, charset)
  8. Постобработка (banner, footer, legalComments)
  9. Sourcemap генерация (sourcemap, sourcesContent)
  10. Запись или возврат результата (write, outdir, outfile)
Оглавление