Учебник Esbuild

Введение в esbuild
- Что такое esbuild и зачем он нужен
- Сравнение с Webpack, Rollup, Vite и Parcel
- Почему esbuild такой быстрый: архитектурные решения
- Ограничения и компромиссы
- Версии и история развития
- Как пользоваться этим учебником
Установка и первые шаги
- Установка через npm, yarn и pnpm
- Глобальная и локальная установка
- Бинарный файл и прямой запуск без Node.js
- Первая сборка: hello world через CLI
- Проверка версии и базовые флаги помощи
- Структура типичного проекта с esbuild
Интерфейсы взаимодействия с esbuild
- CLI: флаги, синтаксис, передача аргументов
- JavaScript API: синхронный и асинхронный режимы
- Go API: краткий обзор для разработчиков Go
- Когда использовать CLI, а когда JS API
- Передача конфигурации через файл
- Переменные окружения и их влияние на сборку
Основные режимы сборки
- Bundle: объединение модулей в один файл
- Transform: транспиляция без сборки
- Разница между bundle и transform на практике
- Режим watch: пересборка при изменениях
- Режим serve: встроенный HTTP-сервер
- Одновременное использование watch и serve
Точки входа и выхода
- Одна точка входа
- Несколько точек входа
- Опция entryNames: шаблоны имён выходных файлов
- Опция outfile и outdir
- Опция outbase: управление структурой директорий
- Опция chunkNames и assetNames
- Запись в stdout вместо файла
Форматы модулей
- IIFE: скрипты для браузера
- CommonJS: формат для Node.js
- ESM: нативные ES-модули
- Выбор формата в зависимости от окружения
- Опция globalName для IIFE
- Совместимость форматов с различными средами выполнения
Работа с JavaScript и TypeScript
- Поддерживаемый синтаксис JavaScript
- Транспиляция TypeScript: что умеет и чего не умеет esbuild
- Отличие от tsc: проверка типов не выполняется
- Файлы .ts, .tsx и опция jsx
- Декораторы TypeScript: поддержка и ограничения
- Опция target: понижение синтаксиса под конкретные среды
- Поддерживаемые значения target: es5, es2015–es2022, node и браузеры
Работа с JSX
- Автоматическое определение JSX-файлов
- Опция jsxFactory и jsxFragment
- Опция jsxImportSource: автоматический импорт runtime
- JSX в режиме automatic (React 17+)
- Использование JSX с Preact, Solid и другими библиотеками
- Директива @jsxRuntime в комментариях
Управление зависимостями
- Опция bundle и разрешение модулей
- Опция external: исключение пакетов из бандла
- Паттерны в external: node:*, @scope/*
- Опция packages: external для всех node_modules
- Опция alias: переопределение путей к модулям
- Разрешение путей: алгоритм и приоритеты
- Поддержка exports в package.json
- Поддержка conditions: browser, import, require, default
Разделение кода
- Опция splitting: включение code splitting
- Динамический import() как точка разделения
- Общие чанки: как esbuild решает, что выносить
- Ограничения splitting: только ESM
- Ручное разделение через несколько точек входа
- Cross-chunk dependencies и их влияние на размер
Tree Shaking
- Как работает tree shaking в esbuild
- Аннотация /*#__PURE__*/
- Поле sideEffects в package.json
- Опция ignoreAnnotations
- Почему часть кода не удаляется: типичные причины
- Tree shaking и CommonJS: известные ограничения
Минификация
- Опция minify: включение всех видов минификации
- minifyWhitespace, minifyIdentifiers, minifySyntax по отдельности
- Минификация и tree shaking: взаимодействие
- Сжатие литералов и выражений
- Влияние минификации на карты источников
- Ограничения минификации в esbuild по сравнению с Terser
Source Maps
- Опция sourcemap: inline, external, linked, both
- Опция sourceRoot
- Опция sourcesContent: включение исходников в карту
- Работа с source maps при многоэтапной сборке
- Отладка в DevTools с source maps от esbuild
- Source maps и минификация
Переменные окружения и define
- Опция define: замена идентификаторов на значения
- Замена process.env.NODE_ENV
- Замена произвольных глобальных переменных
- Опция pure: пометка функций как чистых
- Опция drop: удаление debugger и console
- Опция dropLabels
- Опция banner и footer: вставка произвольного кода
Работа с CSS
- Встроенная поддержка CSS
- Импорт CSS из JavaScript
- CSS Modules: базовая поддержка
- Опция cssChunkNames
- @import и разрешение путей в CSS
- Обработка url() в CSS
- Вендорные префиксы: что делает и чего не делает esbuild
- Поддержка современного синтаксиса CSS: nesting, layers
Работа с ресурсами
- Загрузчики (loaders): назначение и перечень
- Loader dataurl: встраивание в base64
- Loader base64
- Loader binary
- Loader text
- Loader file: копирование файлов с хешем
- Loader copy
- Loader empty
- Назначение loader по расширению файла
- Импорт изображений, шрифтов и других бинарных файлов
Загрузчики для кода
- Loader js и jsx
- Loader ts и tsx
- Loader json: импорт JSON как модуля
- Loader css
- Loader local-css
- Loader global-css
- Loader default и auto-определение
Конфигурация платформы и совместимость
- Опция platform: browser, node, neutral
- Встроенные полифилы для browser-платформы
- Опция engines: точное указание целевых сред
- Совместимость с ES5: что поддерживается, а что нет
- Опция supported: ручное управление трансформациями синтаксиса
- Опция mainFields: порядок полей в package.json
Опции разрешения модулей
- Опция nodePaths: дополнительные пути поиска
- Опция resolveExtensions
- Опция absWorkingDir
- Опция tsconfig и tsconfigRaw
- Поддержка paths и baseUrl из tsconfig
- Символические ссылки и опция preserveSymlinks
Метаданные сборки
- Опция metafile: сбор информации о сборке
- Структура metafile: inputs, outputs
- Анализ metafile вручную
- Утилита esbuild.analyzeMetafile
- Онлайн-инструмент Bundle Size Analyzer
- Использование metafile для оптимизации бандла
Инкрементальные сборки и кэширование
- Режим watch: детальное описание работы
- Callbacks при пересборке
- Опция incremental (устаревшее API, контекст)
- Context API: esbuild.context()
- Методы context: rebuild, watch, serve, dispose
- Кэширование на уровне файловой системы
- Сравнение скорости холодной и горячей сборки
Встроенный сервер разработки
- Опция serve: host, port, servedir
- Опция onRequest: логирование запросов
- Live reload: реализация через Server-Sent Events
- HTTPS в dev-сервере
- Проксирование запросов через middleware
- Ограничения встроенного сервера
Система плагинов
- Архитектура плагинов: name и setup
- Хук onResolve: перехват разрешения путей
- Хук onLoad: перехват загрузки файлов
- Хук onStart и onEnd
- Фильтры: filter и namespace
- Namespace: виртуальные модули
- Передача данных между хуками через pluginData
- Возвращаемые значения хуков и их приоритеты
- Асинхронные плагины
- Обработка ошибок и предупреждений в плагинах
Разработка плагинов
- Плагин для нестандартных форматов файлов
- Плагин для виртуальных модулей
- Плагин для замены импортов во время сборки
- Плагин для загрузки данных из внешних источников
- Плагин с кэшированием результатов
Интеграция с инструментами экосистемы
- esbuild и TypeScript: рекомендуемый рабочий процесс
- esbuild и ESLint
- esbuild и Babel: совместное использование
- esbuild как bundler внутри Vite
- esbuild и Jest / Vitest
- esbuild в Nx и Turborepo
- esbuild и PostCSS через плагины
Сборка для Node.js
- Бандлинг серверного кода
- Опция platform: node и её последствия
- Исключение встроенных модулей Node.js
- Бандлинг CLI-утилит: shebang и banner
- Сборка Lambda-функций и serverless
- Сборка нативных аддонов: ограничения
Сборка библиотек
- Отличия сборки библиотеки от приложения
- Генерация ESM и CJS одновременно
- Опция external для peer dependencies
- Сохранение экспортов и предотвращение tree shaking экспортов
- Генерация d.ts файлов: вне зоны ответственности esbuild
- Поле exports в package.json итоговой библиотеки
Продвинутые техники сборки
- Многоэтапная сборка
- Сборка с разными конфигурациями для dev и prod
- Параллельная сборка нескольких таргетов
- Генерация манифеста файлов
- Хэширование имён файлов для долгосрочного кэширования
- Управление порядком выполнения скриптов
- Inline-скрипты и inline-стили
Производительность и оптимизация
- Профилирование сборки
- Влияние числа точек входа на скорость
- Влияние плагинов на производительность
- Оптимизация работы с большими монорепозиториями
- Ограничение параллелизма
- Сравнение режимов: bundle vs prebundle
Диагностика и отладка
- Формат сообщений об ошибках и предупреждениях
- Опция logLevel: verbose, debug, info, warning, error, silent
- Опция logLimit
- Опция color
- Опция logOverride: управление уровнем конкретных сообщений
- Отладка конфигурации через metafile
- Типичные ошибки и способы их устранения
- Циклические зависимости: обнаружение и последствия
JavaScript API: углублённое изучение
- esbuild.build(): полная сигнатура и возвращаемые значения
- esbuild.transform(): полная сигнатура
- esbuild.context(): управление жизненным циклом
- esbuild.stop(): завершение дочернего процесса
- esbuild.formatMessages(): форматирование ошибок вручную
- esbuild.analyzeMetafile()
- Типы TypeScript для JS API
- Обработка Promise и отмена операций
Использование esbuild в скриптах сборки
- Скрипт сборки вместо конфигурационного файла
- Обработка аргументов командной строки в скрипте
- Условная логика: dev, staging, prod
- Копирование статических файлов
- Генерация HTML с подстановкой хешей
- Интеграция со скриптами package.json
Работа в браузере и Deno
- esbuild-wasm: сборка прямо в браузере
- Установка и инициализация wasm-версии
- Ограничения wasm-версии по сравнению с нативной
- Использование esbuild в Deno
- npm:esbuild и deno.land/x
Справочник опций
- Полный перечень опций build
- Полный перечень опций transform
- Перечень loader-значений
- Перечень допустимых значений target
- Перечень встроенных namespaces
- Перечень логических операторов drop
- Таблица соответствия флагов CLI и ключей JS API