Skip to content

πŸ“ˆβš–οΈ Visuallize your bundle

License

Notifications You must be signed in to change notification settings

btd/rollup-plugin-visualizer

Repository files navigation

Rollup Plugin Visualizer

Visualize and analyze your bundle to quickly see which modules are taking up space.

NPM Version Node.js CI

Screenshots

pic

Installation

npm install --save-dev rollup-plugin-visualizer

or via yarn:

yarn add --dev rollup-plugin-visualizer

Requirements

This package requires Node.js >= 22.

Usage

Import the plugin:

import { visualizer } from "rollup-plugin-visualizer";

Or in CommonJS:

const { visualizer } = require("rollup-plugin-visualizer");

Rollup (rollup.config.js)

import { visualizer } from "rollup-plugin-visualizer";

export default {
  plugins: [
    // Keep it last.
    visualizer(),
  ],
};

Rolldown (rolldown.config.ts)

import { defineConfig, type RolldownPlugin } from "rolldown";
import { visualizer } from "rollup-plugin-visualizer";

export default defineConfig({
  plugins: [visualizer() as RolldownPlugin],
});

Vite (vite.config.js)

import { visualizer } from "rollup-plugin-visualizer";

export default {
  plugins: [visualizer()],
};

Vite + TypeScript (vite.config.ts)

import { defineConfig, type PluginOption } from "vite";
import { visualizer } from "rollup-plugin-visualizer";

export default defineConfig({
  plugins: [visualizer() as PluginOption],
});

SvelteKit (vite.config.js)

import { visualizer } from "rollup-plugin-visualizer";

export default {
  plugins: [
    visualizer({
      emitFile: true,
      filename: "stats.html",
    }),
  ],
};

SvelteKit may run Vite multiple times, so you can get 2-3 generated files in .svelte-kit/output (check Vite logs for exact locations).
You can also generate raw JSON reports and merge them with the CLI.

Understanding The Report

  • Blue marks project files (including files generated by your build tool).
  • Green marks dependencies.
  • This is determined by whether a file path starts with node_modules.
  • All chart layouts refresh when the window is resized.

Sunburst

The circular view is useful for spotting large chunks of code. Clicking an arc zooms into that section and enlarges nested arcs for inspection.

Flamegraph

This is a top-down version of the sunburst view and should feel familiar if you use other JavaScript performance tooling.

Treemap

This rectangular hierarchical view makes large modules easy to find quickly. It can also reveal repeated modules, because repeated content tends to show similar structure and relative size.

Network

Use this view to answer, "Why is this included?"
After the force layout stabilizes, you can drag nodes around. Gray circles are tree-shaken files.

In real projects, network graphs can look noisy. A practical way to explore them is:

  1. Remove highly connected helper nodes (for example commonjsHelpers, tslib, react) when they dominate the graph.
  2. Wait for layout stabilization.
  3. Explore clusters that become easier to read.

Clicking a node highlights nodes listed in its tooltip (the files that import that node).

Raw-data

Produces JSON output with raw data. Usually used together with the CLI.

List

Produces a YAML file with report data. This is useful to commit and track bundle changes over time.

Markdown

Produces a Markdown report with summary tables and notes about config and size precision.

Options

  • filename (string, default stats.{ext based on template}): Name of the generated report file.
  • title (string, default Rollup Visualizer): HTML <title> value.
  • open (boolean, default false): Open the generated file in your default browser.
  • template (string, default treemap): Report type: sunburst, treemap, treemap-3d, network, raw-data, list, markdown, flamegraph.
  • gzipSize (boolean, default false): Include gzip size in the report.
  • brotliSize (boolean, default false): Include Brotli size in the report.

Advanced options (only if needed)

  • emitFile (boolean, default false): Use Rollup emitFile to generate output. Useful when you want all assets managed by Rollup output settings. Also helpful for SvelteKit multi-build runs. When this is true, filename must be a file name, not a path.
  • sourcemap (boolean, default false): Use source maps for module size calculations (for example after Terser/UglifyJS). Keep this plugin last.
  • projectRoot (string | RegExp, default process.cwd()): Common root path used to trim absolute file paths in reports.
  • include (Filter | Filter[], default undefined): Include filter.
  • exclude (Filter | Filter[], default undefined): Exclude filter.

Filter type: { bundle?: picomatchPattern, file?: picomatchPattern }

Note on include and exclude:
If include is omitted or empty, files are included by default.
Otherwise, an ID must match at least one include pattern and must not match any exclude pattern.

Include And Exclude

Filters use picomatch globs, and support these forms:

  • Bundle + file in one string: translation-*.js:*/**/index.js
  • Bundle only: translation-*.js:
  • File only (default): */**/index.js

Format: BUNDLE_GLOB:FILE_GLOB (: is required when bundle matching is used).

CLI

This package provides a CLI utility: rollup-plugin-visualizer.

Use --help to see all available options:

rollup-plugin-visualizer [OPTIONS] stat1.json stat2.json ../stat3.json

This is useful when you have multiple build configs and want to combine reports into one chart.

Build plugin

For local development:

npm run build

Disclaimer about generated files

Generated HTML files do not include your source code contents. They only include:

  • JS/HTML/CSS required for the chart UI
  • Statistical metadata about your code

This metadata can include:

  • Sizes of files in the bundle
  • Sizes of files in source maps
  • File paths
  • File hierarchy

Upgrades

See CHANGELOG.md.

Versioning

  • The plugin API (the part used in your build config) follows SemVer.
  • Frontend report templates can change visual details (network, treemap, sunburst, flamegraph) without strict SemVer guarantees.
  • raw-data uses its own version field.
  • list and markdown outputs follow SemVer.

Sponsor this project

 

Packages

No packages published