Первая сборка: hello world через CLI

Инструмент сборки esbuild распространяется как Node.js-пакет и может использоваться как через API, так и через командную строку. Для первой сборки через CLI требуется наличие среды Node.js и менеджера пакетов npm или yarn.

Установка выполняется на уровне проекта:

npm install esbuild --save-dev

После установки бинарный файл становится доступен через npx, что позволяет запускать сборку без глобальной установки:

npx esbuild --version

Вывод версии подтверждает корректную установку и доступность CLI-инструмента.

Подготовка минимального проекта

Структура минимального проекта для первой сборки обычно включает исходный файл и точку входа:

project/
 ├── src/
 │    └── index.js
 ├── dist/
 ├── package.json

Файл src/index.js содержит базовый JavaScript-код:

console.log("Hello world from esbuild");

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

Базовая сборка через CLI

Основная команда esbuild для сборки файла выглядит следующим образом:

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

Разбор параметров:

  • src/index.js — входной файл
  • --bundle — включение режима сборки зависимостей в единый файл
  • --outfile — путь к результирующему файлу

После выполнения команды формируется файл dist/bundle.js, содержащий объединённый код.

Запуск результата сборки

Собранный файл выполняется через Node.js:

node dist/bundle.js

Ожидаемый вывод:

Hello world from esbuild

На этом этапе подтверждается корректная работа цепочки: исходный код → сборка → выполнение.

Добавление режима разработки

esbuild поддерживает ускоренный цикл разработки за счёт наблюдения за изменениями файлов. Используется флаг --watch:

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

После запуска процесс остаётся активным и пересобирает проект при изменении исходников.

Особенности режима наблюдения:

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

Использование форматирования вывода

esbuild позволяет управлять форматом результирующего кода через параметр --format.

Пример сборки в формате IIFE:

npx esbuild src/index.js --bundle --outfile=dist/bundle.js --format=iife

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

  • iife — самовызывающаяся функция, подходит для браузера
  • cjs — CommonJS модуль
  • esm — ES Modules

Минификация результата

Для уменьшения размера выходного файла используется флаг --minify:

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

В процессе минификации выполняются:

  • удаление пробелов и переносов строк
  • сокращение имён переменных
  • оптимизация выражений

Результат становится менее читаемым, но более компактным.

Подключение нескольких модулей

При наличии нескольких файлов esbuild автоматически анализирует зависимости.

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

src/
 ├── index.js
 └── message.js

message.js:

export const message = "Hello world from module";

index.js:

import { message } from "./message.js";

console.log(message);

Команда сборки остаётся прежней:

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

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

Использование source map

Для отладки применяется генерация source map:

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

В результате создаётся дополнительный файл карты источников, позволяющий:

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

Работа с целевой платформой

Параметр --target задаёт уровень поддержки Jav * aScript:

npx esbuild src/index.js --bundle --outfile=dist/bundle.js --target=es2017

Значение влияет на трансформации:

  • синтаксис стрелочных функций
  • async/await
  • современные операторы

Чем старше целевая версия, тем больше преобразований выполняется.

Передача нескольких входных точек

esbuild поддерживает множественные точки входа:

npx esbuild src/index.js src/admin.js --bundle --outdir=dist

Особенности режима:

  • используется --outdir вместо --outfile
  • создаётся отдельный файл для каждой точки входа
  • общие зависимости извлекаются в общий код автоматически

Управление внешними зависимостями

Для исключения пакетов из сборки применяется --external:

npx esbuild src/index.js --bundle --outfile=dist/bundle.js --external:react

Такая конфигурация оставляет импорт неизменным:

import React from "react";

Пакет не включается в итоговый бандл и ожидается во внешней среде выполнения.

Логика выполнения CLI-команды

Процесс сборки в esbuild включает несколько этапов:

  1. Анализ входного файла
  2. Построение графа зависимостей
  3. Трансформация синтаксиса
  4. Объединение модулей
  5. Генерация итогового файла

Каждый этап выполняется в памяти без промежуточных файлов, что обеспечивает высокую скорость обработки даже при больших проектах.

Оглавление