esbuild.analyzeMetafile()

Функция esbuild.analyzeMetafile() предназначена для преобразования метафайла сборки в человекочитаемый отчёт о структуре бандла. Метафайл, формируемый при сборке с опцией metafile: true, содержит детализированное описание входных модулей, зависимостей, выходных файлов и распределения кода по чанкам. Однако в исходном виде этот JSON сложно интерпретировать без специализированной обработки. analyzeMetafile() решает эту задачу, превращая структурированные данные в аналитический текстовый отчёт.

Метафайл как основа анализа

Метафайл генерируется при выполнении сборки:

import * as esbuild from 'esbuild';

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

console.log(result.metafile);

Структура метафайла включает:

  • входные файлы (inputs)
  • выходные файлы (outputs)
  • связи импорта между модулями
  • размеры модулей и вклад в итоговый бандл
  • информацию о разделении кода (code splitting)
  • условия включения/исключения модулей

В сыром виде это дерево зависимостей, ориентированное на машинную обработку, а не на чтение человеком.

Сигнатура esbuild.analyzeMetafile()

esbuild.analyzeMetafile(metafile, options?)

Возвращает Promise<string> с текстовым отчётом.

Параметры:

  • metafile — объект метаданных, полученный из esbuild.build() или esbuild.context().rebuild()
  • options — необязательный объект конфигурации анализа

Поддерживаемые опции:

  • verbose: boolean — расширенный режим детализации
  • color: boolean — включение цветового оформления (в CLI-окружениях)

Базовый пример использования

import * as esbuild from 'esbuild';

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

const analysis = await esbuild.analyzeMetafile(result.metafile);

console.log(analysis);

Результат представляет собой структурированный текстовый отчёт, где отображается распределение модулей по выходным файлам и вклад каждого файла в общий размер сборки.

Интерпретация результата анализа

Выход analyzeMetafile() обычно включает несколько логических блоков.

Распределение выходных файлов

В начале отчёта перечисляются выходные артефакты:

dist/app.js           245.3kb
dist/vendor.js        812.7kb

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

Граф зависимостей

Далее следует дерево импортов:

src/index.js
└── react-dom/client
    └── scheduler
        └── ...

Эта часть позволяет определить:

  • какие зависимости тянутся транзитивно
  • какие модули становятся «центрами тяжести»
  • где возникают глубокие цепочки импортов

Вклад модулей в размер бандла

Одна из ключевых секций — распределение веса:

react-dom/client        120.4kb
react                  89.1kb
scheduler              32.7kb

Здесь отображается реальный вклад каждого пакета в итоговый бандл, включая транзитивные зависимости.

Разделение кода (code splitting)

При наличии динамических импортов (import()), отчёт показывает чанки:

chunk-A.js
└── src/lazy-module.js
└── lodash-es

Это позволяет анализировать:

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

Режим verbose

При включении verbose: true отчёт становится значительно более детализированным.

const analysis = await esbuild.analyzeMetafile(result.metafile, {
  verbose: true
});

Дополнительно отображается:

  • полный путь каждого модуля
  • причина включения модуля в бандл
  • цепочка импортов до корневого entry point
  • точные размеры каждого включения (включая повторные встраивания)

Практическое применение анализа

Поиск тяжёлых зависимостей

analyzeMetafile() позволяет быстро выявить библиотеки, увеличивающие размер сборки непропорционально функциональности. Часто это:

  • UI-фреймворки с полной подтяжкой компонентов
  • библиотеки утилит с не-tree-shakable экспортами
  • дублирующиеся зависимости

Диагностика tree-shaking

Отчёт показывает, какие части библиотек действительно попали в сборку. Это позволяет оценить эффективность:

  • ESM-модулей
  • sideEffects-флагов в package.json
  • структуры импортов

Если модуль целиком включается, несмотря на частичный импорт, это сигнал к пересмотру структуры импортов.

Анализ дублирования

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

Оптимизация архитектуры сборки

На основе анализа корректируются:

  • точки входа (entry points)
  • стратегия code splitting
  • порядок динамических импортов
  • использование shared chunks

Работа с большими метафайлами

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

  • анализ выполняется асинхронно
  • результат часто перенаправляется в файл
  • используется фильтрация по интересующим пакетам на уровне предварительной обработки метафайла
import fs from 'fs';
import * as esbuild from 'esbuild';

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

const report = await esbuild.analyzeMetafile(result.metafile);

fs.writeFileSync('analysis.txt', report);

Связь с metafile и build context

analyzeMetafile() не выполняет сборку и не изменяет граф зависимостей. Она работает исключительно с уже готовым метафайлом.

В сценариях с watch-режимом или контекстной сборкой:

  • context.rebuild() генерирует новый метафайл
  • каждый новый метафайл может анализироваться отдельно
  • результаты можно сравнивать между итерациями сборки

Ограничения анализа

Функция ориентирована на структурный анализ, поэтому:

  • не показывает runtime-поведение
  • не учитывает фактическое выполнение кода
  • не измеряет производительность в браузере или Node.js
  • не анализирует асинхронные загрузки после бандлинга

Интерпретация размеров

Размеры в отчёте отражают итоговый вклад модулей после:

  • минификации (если включена)
  • объединения модулей
  • удаления неиспользуемого кода
  • инлайнинга зависимостей

Таким образом, цифры соответствуют именно финальному артефакту, а не исходным исходникам.

Типовые сценарии анализа

Сравнение двух сборок

Используется для проверки влияния изменений:

  • добавление новой библиотеки
  • изменение структуры импортов
  • переключение режима сборки (ESM/CJS)

Проверка эффективности оптимизаций

После включения:

  • tree shaking
  • splitting
  • minify

анализ показывает реальный эффект, а не декларативные настройки.

Контроль архитектуры монорепозитория

В монорепозиториях метафайл помогает определить:

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

Форматирование результата

Выход analyzeMetafile() представляет собой текстовый отчёт, пригодный для:

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

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

Оглавление