esbuild Bundle Analyzer

0.0.1 verified Fri May 01 auth: no javascript

A tool to analyze the size and composition of esbuild output bundles, helping identify optimization opportunities. Version 0.0.1 is extremely early and unstable — expect breaking changes with every release. Unlike bundle analyzers for Webpack (webpack-bundle-analyzer) or Rollup (rollup-plugin-visualizer), this is native to esbuild's plugin system, but currently lacks interactive visualizations and detailed module trees. Release cadence is not established.

Common errors

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

cause Package not installed or import path incorrect.

fix

Run 'npm install esbuild-bundle-analyzer@0.0.1' and verify import statement.

error TypeError: bundleAnalyzer is not a function ↓

cause Importing as CJS require instead of ESM import.

fix

Use 'import { bundleAnalyzer } from "esbuild-bundle-analyzer"' in an ESM context.

error Error: The plugin must be a function or object with 'name' property. ↓

cause Incorrect plugin instantiation: passing function directly without calling it.

fix

Use 'plugins: [bundleAnalyzer()]' (call the function) instead of 'plugins: [bundleAnalyzer]'.

Warnings

breaking API is unstable: plugin may not work with esbuild versions outside 0.0.1 range. ↓

fix Pin esbuild version to exact match; await stable releases.

deprecated Default export may be removed in future releases. ↓

fix Use named export { bundleAnalyzer } instead.

gotcha Plugin does not support esbuild's watch mode properly; analysis may not update on rebuild. ↓

fix Restart build every time for accurate results.

gotcha Large bundles (>10MB) may cause out-of-memory errors. ↓

fix Analyze subsets of the bundle or increase Node memory limit (--max-old-space-size).

gotcha Only analyzes JavaScript/TypeScript files; CSS, images, and other assets are ignored. ↓

fix Use separate tools for non-JS assets.

Install

npm install esbuild-bundle-analyzer

yarn add esbuild-bundle-analyzer

pnpm add esbuild-bundle-analyzer

Imports

bundleAnalyzer

wrong

const bundleAnalyzer = require('esbuild-bundle-analyzer')

correct

import { bundleAnalyzer } from 'esbuild-bundle-analyzer'

ESM-only. No CJS support.

default
```
import bundleAnalyzer from 'esbuild-bundle-analyzer'
```
Default export aliases the named export. Avoid as it may be removed.
BundleAnalyzerPlugin
```
import { BundleAnalyzerPlugin } from 'esbuild-bundle-analyzer'
```
Internal class name, not public API. Unlikely to work.

type Options

import type { Options } from 'esbuild-bundle-analyzer'

Utility type for plugin options.

Quickstart

Shows how to add the bundle analyzer as an esbuild plugin to generate a report JSON file during build.

import * as esbuild from 'esbuild';
import { bundleAnalyzer } from 'esbuild-bundle-analyzer';

await esbuild.build({
  entryPoints: ['app.js'],
  bundle: true,
  outfile: 'out.js',
  plugins: [bundleAnalyzer({
    outfile: 'report.json',
    verbose: false
  })],
});
console.log('Bundle analysis written to report.json');