rollup-plugin-visualizer/README.md

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

# Rollup Plugin Visualizer

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

[![NPM Version](https://img.shields.io/npm/v/rollup-plugin-visualizer.svg)](https://npmjs.org/package/rollup-plugin-visualizer) [![Node.js CI](https://github.com/btd/rollup-plugin-visualizer/actions/workflows/node.js.yml/badge.svg)](https://github.com/btd/rollup-plugin-visualizer/actions/workflows/node.js.yml)

## Screenshots

![pic](https://github.com/btd/rollup-plugin-visualizer/blob/master/pics/collage.png?raw=true)

## Installation

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

or via yarn:

```sh
yarn add --dev rollup-plugin-visualizer
```

## Requirements

This package requires Node.js >= 22.

## Usage

Import the plugin:

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

Or in CommonJS:

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

### Rollup (`rollup.config.js`)

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

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

### Rolldown (`rolldown.config.ts`)

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

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

### Vite (`vite.config.js`)

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

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

### Vite + TypeScript (`vite.config.ts`)

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

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

### SvelteKit (`vite.config.js`)

```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:

```sh
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:

```sh
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` outputs follow SemVer.
- `markdown` do not follow any versioning for now and will change as LLM development changes