esbuild-visualizer

0.7.0 verified Mon Apr 27 auth: no javascript

Visualize and analyze your esbuild bundle to determine module sizes and composition. Current stable version is 0.7.0, with irregular release cadence. Generates interactive HTML charts (treemap, sunburst, network) from esbuild metafiles. Key differentiator: works specifically with esbuild's metadata output, producing visual bundle analysis without including source code content. Requires Node >=18, ships TypeScript types. Alternative to webpack-bundle-analyzer for esbuild users.

Common errors

error Error: Could not find file: /path/to/meta.json ↓

cause The metafile path provided does not exist or is incorrect.

fix

Verify the metafile path: visualizer({ metafile: './meta.json' }) after running esbuild with metafile: true.

error TypeError: visualizer is not a function ↓

cause The visualizer is not imported correctly; default import was used instead of named import.

fix

Use: import { visualizer } from 'esbuild-visualizer';

error Error: Unknown template 'circlepacking' ↓

cause An invalid template name was passed.

fix

Use one of: 'treemap', 'sunburst', 'network'.

Warnings

gotcha The visualizer function only works with esbuild metafiles (--metafile flag). If you pass a non-esbuild JSON, it will fail. ↓

fix Ensure the input JSON is produced by esbuild with { metafile: true } or the --metafile CLI flag.

deprecated Option 'metadata' (misspelled) was deprecated in v0.4.0 and removed in v0.5.0. Use 'metafile' instead. ↓

fix Use { metafile: ... } instead of { metadata: ... }.

gotcha Generated HTML files do not contain source code, but they do include file paths and sizes. Avoid exposing these files if filesystem layout is sensitive. ↓

fix Review the generated stats.html before sharing; it contains statistical data but not source content.

gotcha The CLI command 'esbuild-visualizer' requires Node >=18. On older Node versions, it will fail to run. ↓

fix Use Node 18 or later.

Install

npm install esbuild-visualizer

yarn add esbuild-visualizer

pnpm add esbuild-visualizer

Imports

visualizer

wrong

import visualizer from 'esbuild-visualizer'

correct

import { visualizer } from 'esbuild-visualizer'

The package exposes a named export 'visualizer', not a default export.

visualizer

wrong

const visualizer = require('esbuild-visualizer')

correct

const { visualizer } = require('esbuild-visualizer')

CommonJS require must destructure the named export.

type VisualizerOptions

wrong

import { VisualizerOptions } from 'esbuild-visualizer'

correct

import type { VisualizerOptions } from 'esbuild-visualizer'

TypeScript users should use `import type` to avoid runtime import if not needed.

metafileName

wrong

import { metafile } from 'esbuild-visualizer'

correct

// Not imported; usage: visualizer({ metafile: './meta.json', ... })

Options are passed as an object argument, not imported.

Quickstart

Builds an esbuild bundle with metafile, then generates an interactive treemap visualization HTML file.

import { visualizer } from 'esbuild-visualizer';
import { build } from 'esbuild';

async function analyze() {
  const result = await build({
    entryPoints: ['app.ts'],
    bundle: true,
    outfile: 'out.js',
    metafile: true,
  });

  // Write metafile to disk
  const fs = await import('fs');
  fs.writeFileSync('meta.json', JSON.stringify(result.metafile));

  await visualizer({
    metafile: 'meta.json',
    filename: 'stats.html',
    title: 'My Bundle Analysis',
    template: 'treemap',  // 'treemap', 'sunburst', or 'network'
  });

  console.log('Visualization generated at stats.html');
}

analyze().catch(console.error);