esbuild-analyzer

0.2.0 verified Mon Apr 27 auth: no javascript

A visualizer and analyzer for esbuild builds that generates an interactive HTML report from esbuild's metafile output. Version 0.2.0 is the current stable release; the package is maintained sporadically. It provides both a plugin API (for .build) and a standalone sync function (getEsbuildAnalyzerHtml) plus a CLI tool. Unlike webpack-bundle-analyzer, it is esbuild-native and does not require additional bundler integrations.

Common errors

error Error: Cannot find module 'esbuild-analyzer' ↓

cause Package not installed or not in node_modules.

fix

Run npm install -D esbuild-analyzer.

error TypeError: AnalyzerPlugin is not a function ↓

cause Incorrect import style; the default export is a function.

fix

Use const AnalyzerPlugin = require('esbuild-analyzer') (CommonJS) or import AnalyzerPlugin from 'esbuild-analyzer' (ESM not supported).

error Error: build failed with 0 errors? ↓

cause Missing `metafile: true` in esbuild options.

fix

Add metafile: true to your esbuild build configuration.

Warnings

gotcha The plugin requires `metafile: true` in esbuild options; otherwise it does nothing. ↓

fix Always set `metafile: true` in your esbuild build options.

gotcha The plugin must be listed in the `plugins` array; it does not work as a standalone function. ↓

fix Pass `plugins: [AnalyzerPlugin()]` to the esbuild build call.

breaking Before v0.2.0, the plugin was exported as a default export only; named exports were added in v0.2.0. ↓

fix Import the default export: `const AnalyzerPlugin = require('esbuild-analyzer');` or use `import AnalyzerPlugin from 'esbuild-analyzer'`.

deprecated The package does not support ESM; using `import` may fail in Node ESM mode. ↓

fix Use `require` or dynamic import. Or wrap in a CommonJS module.

gotcha The CLI expects the metafile to be generated separately; it does not run esbuild itself. ↓

fix First run `esbuild --metafile=meta.json` then `npx esbuild-analyzer --metafile=meta.json`.

Install

npm install esbuild-analyzer

yarn add esbuild-analyzer

pnpm add esbuild-analyzer

Imports

AnalyzerPlugin

wrong

const AnalyzerPlugin = require('esbuild-analyzer')

correct

import AnalyzerPlugin from 'esbuild-analyzer'

Default CommonJS export; ESM not supported. Use require or dynamic import.

getEsbuildAnalyzerHtml

wrong

const getEsbuildAnalyzerHtml = require('esbuild-analyzer').getEsbuildAnalyzerHtml

correct

import { getEsbuildAnalyzerHtml } from 'esbuild-analyzer'

Named export for synchronous usage with buildSync; available as a named export.

AnalyzerPlugin (CLI)
```
npx esbuild-analyzer --metafile=meta.json --outfile=report.html
```
CLI usage does not require imports; runs as a binary.

Quickstart

Shows how to use esbuild-analyzer as a plugin during esbuild's async build, generating an interactive HTML report.

const esbuild = require('esbuild');
const AnalyzerPlugin = require('esbuild-analyzer');

async function build() {
  const result = await esbuild.build({
    entryPoints: ['src/index.js'],
    outdir: 'dist',
    bundle: true,
    metafile: true,
    write: false,
    plugins: [AnalyzerPlugin()],
  });
  console.log('Analysis complete. Open generated HTML in browser.');
}

build().catch(console.error);