Таблица соответствия флагов CLI и ключей JS API

Esbuild предоставляет два основных способа управления процессом сборки:

  • через командную строку (CLI);
  • через программный интерфейс JavaScript API.

Обе модели используют одинаковые внутренние механизмы, однако синтаксис настройки отличается. При миграции между CLI и JavaScript API важно понимать соответствие между флагами командной строки и объектом конфигурации, передаваемым в функции build(), context() или transform().

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

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

Эквивалент на Jav * aScript:

import * as esbuild from 'esbuild';

await esbuild.build({
    entryPoints: ['src/index.js'],
    bundle: true,
    minify: true,
    outfile: 'dist/app.js'
});

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

Базовые параметры входных файлов

entryPoints

CLI:

esbuild src/index.js src/admin.js

JS API:

await esbuild.build({
    entryPoints: [
        'src/index.js',
        'src/admin.js'
    ]
});

При использовании CLI входные файлы перечисляются без специальных флагов. В JavaScript API они передаются через массив entryPoints.

--bundle → bundle

CLI:

esbuild src/index.js --bundle

JS API:

await esbuild.build({
    entryPoints: ['src/index.js'],
    bundle: true
});

Включает объединение зависимостей в итоговый пакет.

--outfile → outfile

CLI:

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

JS API:

await esbuild.build({
    entryPoints: ['src/index.js'],
    outfile: 'dist/app.js'
});

Указывает путь к единственному выходному файлу.

--outdir → outdir

CLI:

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

JS API:

await esbuild.build({
    entryPoints: [
        'src/index.js',
        'src/admin.js'
    ],
    outdir: 'dist'
});

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

Формат выходного кода

--format → format

CLI:

esbuild src/index.js --format=esm

JS API:

await esbuild.build({
    entryPoints: ['src/index.js'],
    format: 'esm'
});

Поддерживаемые значения:

  • esm
  • cjs
  • iife

Пример CommonJS:

format: 'cjs'

Пример IIFE:

format: 'iife'

--platform → platform

CLI:

esbuild src/index.js --platform=node

JS API:

await esbuild.build({
    entryPoints: ['src/index.js'],
    platform: 'node'
});

Доступные варианты:

platform: 'browser'
platform: 'node'
platform: 'neutral'

--target → target

CLI:

esbuild src/index.js --target=es2020

JS API:

await esbuild.build({
    entryPoints: ['src/index.js'],
    target: 'es2020'
});

Несколько целей:

CLI:

esbuild src/index.js --target=chrome120,firefox120

JS API:

await esbuild.build({
    entryPoints: ['src/index.js'],
    target: [
        'chrome120',
        'firefox120'
    ]
});

Минификация

--minify → minify

CLI:

esbuild src/index.js --minify

JS API:

await esbuild.build({
    entryPoints: ['src/index.js'],
    minify: true
});

Включает:

  • удаление лишних пробелов;
  • сокращение идентификаторов;
  • оптимизацию синтаксиса.

Частичная минификация

--minify-whitespace → minifyWhitespace

CLI:

esbuild src/index.js --minify-whitespace

JS API:

await esbuild.build({
    entryPoints: ['src/index.js'],
    minifyWhitespace: true
});

--minify-identifiers → minifyIdentifiers

CLI:

esbuild src/index.js --minify-identifiers

JS API:

await esbuild.build({
    entryPoints: ['src/index.js'],
    minifyIdentifiers: true
});

--minify-syntax → minifySyntax

CLI:

esbuild src/index.js --minify-syntax

JS API:

await esbuild.build({
    entryPoints: ['src/index.js'],
    minifySyntax: true
});

Генерация Source Maps

--sourcemap → sourcemap

CLI:

esbuild src/index.js --sourcemap

JS API:

await esbuild.build({
    entryPoints: ['src/index.js'],
    sourcemap: true
});

Варианты sourcemap

CLI:

esbuild src/index.js --sourcemap=inline

JS API:

await esbuild.build({
    entryPoints: ['src/index.js'],
    sourcemap: 'inline'
});

Другие варианты:

sourcemap: 'external'
sourcemap: 'linked'
sourcemap: 'both'

Работа с именами файлов

--entry-names → entryNames

CLI:

esbuild src/*.js --outdir=dist --entry-names=[name]-bundle

JS API:

await esbuild.build({
    entryPoints: ['src/index.js'],
    outdir: 'dist',
    entryNames: '[name]-bundle'
});

--chunk-names → chunkNames

CLI:

esbuild src/index.js --splitting --chunk-names=chunks/[name]-[hash]

JS API:

await esbuild.build({
    entryPoints: ['src/index.js'],
    splitting: true,
    chunkNames: 'chunks/[name]-[hash]'
});

--asset-names → assetNames

CLI:

esbuild src/index.js --asset-names=assets/[name]-[hash]

JS API:

await esbuild.build({
    entryPoints: ['src/index.js'],
    assetNames: 'assets/[name]-[hash]'
});

Code Splitting

--splitting → splitting

CLI:

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

JS API:

await esbuild.build({
    entryPoints: ['src/index.js'],
    bundle: true,
    splitting: true,
    format: 'esm'
});

Разделение кода работает только для ESM-сборок.

Управление загрузчиками

--loader:.ext=value → loader

CLI:

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

JS API:

await esbuild.build({
    entryPoints: ['src/index.js'],
    loader: {
        '.png': 'file'
    }
});

Несколько загрузчиков:

CLI:

esbuild src/index.js \
--loader:.png=file \
--loader:.svg=text \
--loader:.txt=text

JS API:

await esbuild.build({
    loader: {
        '.png': 'file',
        '.svg': 'text',
        '.txt': 'text'
    }
});

Внешние зависимости

--external → external

CLI:

esbuild src/index.js --external:react

JS API:

await esbuild.build({
    entryPoints: ['src/index.js'],
    external: ['react']
});

Несколько зависимостей:

CLI:

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

JS API:

await esbuild.build({
    external: [
        'react',
        'react-dom'
    ]
});

Определение глобальных констант

--define → define

CLI:

esbuild src/index.js --define:DEBUG=true

JS API:

await esbuild.build({
    define: {
        DEBUG: 'true'
    }
});

Пример для переменных окружения:

CLI:

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

JS API:

await esbuild.build({
    define: {
        'process.env.NODE_ENV': '"production"'
    }
});

Удаление отладочных вызовов

--drop → drop

CLI:

esbuild src/index.js --drop:console

JS API:

await esbuild.build({
    drop: ['console']
});

Удаление нескольких типов:

CLI:

esbuild src/index.js \
--drop:console \
--drop:debugger

JS API:

await esbuild.build({
    drop: [
        'console',
        'debugger'
    ]
});

Поддержка JSX

--jsx → jsx

CLI:

esbuild src/app.jsx --jsx=automatic

JS API:

await esbuild.build({
    entryPoints: ['src/app.jsx'],
    jsx: 'automatic'
});

Другие варианты:

jsx: 'transform'
jsx: 'preserve'

--jsx-factory → jsxFactory

CLI:

esbuild src/app.jsx --jsx-factory=h

JS API:

await esbuild.build({
    jsxFactory: 'h'
});

--jsx-fragment → jsxFragment

CLI:

esbuild src/app.jsx --jsx-fragment=Fragment

JS API:

await esbuild.build({
    jsxFragment: 'Fragment'
});

--jsx-import-source → jsxImportSource

CLI:

esbuild src/app.jsx --jsx-import-source=preact

JS API:

await esbuild.build({
    jsxImportSource: 'preact'
});

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

В CLI используется специальный режим:

esbuild src/index.js --watch

В JavaScript API применяется объект контекста:

const context = await esbuild.context({
    entryPoints: ['src/index.js'],
    bundle: true
});

await context.watch();

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

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

CLI не имеет полного аналога в виде флага.

JS API:

const context = await esbuild.context({
    entryPoints: ['src/index.js'],
    bundle: true
});

await context.rebuild();

Механизм используется для повторной сборки без полной инициализации проекта.

Генерация метафайла

--metafile → metafile

CLI:

esbuild src/index.js --metafile=meta.json

JS API:

const result = await esbuild.build({
    entryPoints: ['src/index.js'],
    metafile: true
});

Сохранение результата:

import fs from 'fs';

fs.writeFileSync(
    'meta.json',
    JSON.stringify(result.metafile)
);

Работа с каталогами

--outbase → outbase

CLI:

esbuild src/pages/home.js \
src/pages/admin.js \
--outdir=dist \
--outbase=src

JS API:

await esbuild.build({
    entryPoints: [
        'src/pages/home.js',
        'src/pages/admin.js'
    ],
    outdir: 'dist',
    outbase: 'src'
});

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

Управление логированием

--log-level → logLevel

CLI:

esbuild src/index.js --log-level=warning

JS API:

await esbuild.build({
    logLevel: 'warning'
});

Поддерживаемые уровни:

logLevel: 'silent'
logLevel: 'error'
logLevel: 'warning'
logLevel: 'info'
logLevel: 'debug'

Работа с правами доступа

CLI:

esbuild src/index.js --legal-comments=eof

JS API:

await esbuild.build({
    legalComments: 'eof'
});

Допустимые значения:

legalComments: 'none'
legalComments: 'inline'
legalComments: 'linked'
legalComments: 'external'
legalComments: 'eof'

Генерация выходных данных в память

--write=false → write

CLI:

esbuild src/index.js --write=false

JS API:

await esbuild.build({
    write: false
});

Получение результата:

const result = await esbuild.build({
    entryPoints: ['src/index.js'],
    bundle: true,
    write: false
});

console.log(result.outputFiles);

Сводная таблица соответствия

CLI JS API
--bundle bundle
--outfile outfile
--outdir outdir
--format format
--platform platform
--target target
--minify minify
--minify-whitespace minifyWhitespace
--minify-identifiers minifyIdentifiers
--minify-syntax minifySyntax
--sourcemap sourcemap
--entry-names entryNames
--chunk-names chunkNames
--asset-names assetNames
--splitting splitting
--loader:.ext=value loader
--external external
--define define
--drop drop
--jsx jsx
--jsx-factory jsxFactory
--jsx-fragment jsxFragment
--jsx-import-source jsxImportSource
--metafile metafile
--outbase outbase
--log-level logLevel
--legal-comments legalComments
--write=false write: false

Понимание этой таблицы существенно упрощает переход между автоматизированными сценариями сборки и ручным запуском Esbuild из командной строки. Практически любой CLI-флаг имеет прямой аналог в JavaScript API, что обеспечивает единообразие конфигурации независимо от способа запуска сборщика.

Оглавление