CLI: флаги, синтаксис, передача аргументов

CLI-интерфейс esbuild построен вокруг компактного синтаксиса, где поведение сборки определяется набором флагов после вызова бинарного файла. Базовая форма команды включает входной файл и набор параметров конфигурации:

esbuild input.js --bundle --outfile=dist/output.js

Входной файл может быть указан первым аргументом или через явный флаг --entry:, однако в большинстве случаев используется позиционный синтаксис. CLI поддерживает несколько входных точек:

esbuild src/app.js src/admin.js --bundle --outdir=dist

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

Флаги вывода и управление артефактами сборки

Ключевым аспектом CLI является управление выходными файлами. Основные параметры:

–outfile задаёт единый выходной файл:

esbuild src/index.js --bundle --outfile=dist/bundle.js

–outdir используется для генерации нескольких файлов:

esbuild src/app.js src/admin.js --bundle --outdir=dist

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

–splitting включается совместно с ESM-форматом:

esbuild src/app.js --bundle --splitting --format=esm --outdir=dist

Управление форматом модулей

Флаг --format определяет тип выходного модуля:

  • iife — самовызывающаяся функция
  • cjs — CommonJS
  • esm — ES Modules

Примеры:

esbuild src/index.js --bundle --format=cjs --outfile=dist/index.cjs
esbuild src/index.js --bundle --format=esm --outfile=dist/index.js

Формат влияет на доступность code splitting, динамического импорта и способ обработки зависимостей.

Платформы выполнения

Флаг --platform изменяет поведение резолвинга модулей и встроенных API:

  • browser — ориентирован на браузер
  • node — для Node.js окружения
  • neutral — универсальная конфигурация
esbuild src/index.js --bundle --platform=node --outfile=dist/server.js

При выборе платформы автоматически корректируются встроенные импорты (fs, path, url) и стратегии полифиллов.

Оптимизация и трансформация кода

esbuild предоставляет набор флагов для ускорения и уменьшения размера бандла:

–minify включает минификацию:

esbuild src/index.js --bundle --minify --outfile=dist/app.js

–sourcemap управляет генерацией source maps:

esbuild src/index.js --bundle --sourcemap --outfile=dist/app.js

Возможные режимы source map:

  • external
  • inline
  • both

Пример:

esbuild src/index.js --bundle --sourcemap=external --outfile=dist/app.js

Определение переменных и подмена значений

Флаг --define позволяет заменять выражения на этапе сборки:

esbuild src/index.js --bundle --define:process.env.NODE_ENV=\"production\"

Механизм работает как статическая подстановка значений до этапа минификации, что позволяет удалять условные блоки:

if (process.env.NODE_ENV === "production") {
  console.log("prod mode");
}

Работа с внешними зависимостями

Флаг --external исключает модули из бандла:

esbuild src/index.js --bundle --external:react --external:react-dom

Такая конфигурация используется при сборке библиотек, где зависимости предполагаются внешними.

Настройка загрузчиков (loaders)

CLI поддерживает назначение loader’ов для расширений:

esbuild src/index.js --bundle --loader:.png=file --loader:.css=text

Типы загрузчиков:

  • js, jsx
  • ts, tsx
  • json
  • text
  • binary
  • file

Пример обработки TypeScript и JSX:

esbuild src/app.tsx --bundle --loader:.tsx=tsx

Разделение кода и динамические импорты

Code splitting включается совместно с ESM:

esbuild src/index.js --bundle --format=esm --splitting --outdir=dist

Динамический импорт (import()) автоматически становится точкой разделения, создавая дополнительные чанки.

Метаданные сборки

Флаг --metafile сохраняет информацию о графе зависимостей:

esbuild src/index.js --bundle --metafile=meta.json --outfile=dist/app.js

Файл содержит:

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

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

Режим наблюдения за изменениями

Флаг --watch включает автоматическую пересборку:

esbuild src/index.js --bundle --watch --outfile=dist/app.js

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

Встроенный сервер разработки

CLI поддерживает режим сервера через --serve:

esbuild src/index.js --bundle --serve=localhost:3000 --outdir=dist

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

Инкрементальная сборка

Флаг --incremental активирует кеширование:

esbuild src/index.js --bundle --incremental

Результат сохраняется в памяти процесса и повторно используется при следующих сборках через API (в CLI применяется ограниченно).

Вставка кода в начало и конец бандла

Флаги --banner и --footer добавляют код до и после результата сборки:

esbuild src/index.js --bundle --banner:js="/* build start */" --footer:js="/* build end */"

Используется для лицензий, глобальных переменных или инициализации среды.

Обработка stdin как входного потока

esbuild поддерживает чтение кода из стандартного ввода:

cat src/index.js | esbuild --bundle --outfile=dist/app.js

или

esbuild --bundle --stdin --outfile=dist/app.js

При использовании stdin требуется явное указание формата через --loader:.js=js при необходимости.

Передача аргументов через npm scripts

При запуске через npm CLI-аргументы передаются после двойного дефиса:

{
  "scripts": {
    "build": "esbuild src/index.js --bundle --outfile=dist/app.js"
  }
}

Запуск с дополнительными флагами:

npm run build -- --watch

Дополнительные параметры добавляются к базовой команде без изменения package.json.

Экранирование и особенности shell

CLI esbuild чувствителен к правилам оболочки:

  • в Unix-системах требуется экранирование кавычек для --define
  • в Windows используются другие правила интерпретации строк
  • JSON-подобные значения должны передаваться как строки

Пример корректной передачи:

esbuild src/index.js --define:API_URL=\"https://example.com\"

Группировка и комбинирование флагов

Большинство параметров может использоваться одновременно без ограничения порядка:

esbuild src/index.ts --bundle --platform=browser --format=esm --minify --sourcemap --outdir=dist

Комбинации флагов определяют конечную стратегию сборки: от разработки с наблюдением до production-бандлов с полной оптимизацией и разбиением на чанки.

Оглавление