esbuild: сборка библиотеки или утилиты (build.mjs) — Сниппеты

Скрипт использует только официальный API esbuild (esbuild.github.io/api), без экспериментальных флагов.

Файл: build.mjs (в корне проекта):

import * as esbuild from 'esbuild';

await esbuild.build({
  // Точки входа: один файл для библиотеки/утилиты. Можно массив — будет несколько выходных файлов.
  entryPoints: ['src/index.ts'],

  // Собирать зависимости в один бандл (иначе только транспиляция, импорты остаются как есть).
  bundle: true,

  // Папка вывода. При одном entry получится dist/index.js (или с outExtension — .mjs).
  outdir: 'dist',

  // Минификация: убирает пробелы, короткие имена, dead code. Для библиотеки/утилиты — обычно true.
  minify: true,

  // Source map: true — отдельный .map файл рядом с .js; нужен для отладки прод-сборки и стеков ошибок.
  sourcemap: true,

  // Цель транспиляции: современный JS. es2020 — широко поддерживается в Node 14+ и браузерах 2020+.
  // Варианты: 'esnext' (минимум трансформаций), 'es2022', массив ['es2020', 'node18'] и т.д.
  target: ['es2020'],

  // Формат вывода: ESM для современной библиотеки/утилиты. Для Node-утилиты можно 'cjs'.
  format: 'esm',

  // Платформа: 'neutral' — ни браузер, ни node по умолчанию (подходит для универсальной библиотеки).
  // Для утилиты только под Node лучше platform: 'node'.
  platform: 'neutral',
});

console.log('Build done → dist/');

Запуск:

node build.mjs

Перед первым запуском: npm i -D esbuild. Точка входа src/index.ts (или src/index.js) должна существовать.

Для каких задач esbuild подходит идеально

Библиотеки и утилиты — один или несколько entry, быстрый бандл, минификация и source map из коробки. Не нужен HTML, dev-сервер, HMR.
CLI на TypeScript/ESM — собрать в один файл под Node, без лишних плагинов и конфигов.
Скрипты и воркеры — бандл тяжёлых зависимостей в один файл для быстрого старта и простого деплоя.
Часть пайплайна — вызов esbuild.build() из своей сборки (Gulp, npm-скрипты, CI): один зависимый бинарник, предсказуемый вывод.
Скорость — холодный и повторный билд заметно быстрее Webpack и часто быстрее Rollup на небольших и средних проектах.

Где esbuild уступает Vite / Webpack

Полноценный фронтенд-проект с HTML и dev-сервером — у Vite есть index.html, HMR, прелоады, оптимизация зависимостей; у esbuild только serve и watch, без «из коробки» SPA-удобств.
Сложный граф ассетов — CSS-пайплайн (препроцессоры, постобработка), SVG как компоненты, шрифты, тонкий контроль чанков. Vite/Webpack и плагины закрывают это богаче; у esbuild — базовый CSS и ограниченный набор лоадеров.
Легаси и нестандартные импорты — динамические пути (import(variable)), глобалы, старые форматы. Webpack и плагины умеют такое обходить; esbuild ожидает анализируемые статические импорты.
Module Federation / микрофронты — экосистема и примеры в основном на Webpack; у esbuild нет аналога «из коробки».
Единый конфиг для dev и prod — Vite даёт один конфиг, разное поведение в dev и build; с esbuild для «как в проде» часто нужен свой скрипт и при необходимости отдельный dev-сервер.

Итого: для библиотеки или небольшой утилиты с современным JS/TS и простым графом зависимостей esbuild часто оптимален; для большого SPA/MPA с богатым пайплайном разумнее Vite или Webpack.

Как использовать

Для каких задач esbuild подходит идеально

Где esbuild уступает Vite / Webpack