rollup-plugin-visualizer: reading your bundle instead of guessing at it

The question the plugin answers: why is this file in my bundle

Bundlers are good at producing a single file and bad at explaining it. You notice a chunk grew by 200 KB, you open the minified output, and you find a wall of mangled identifiers with no path back to the module that caused the growth. rollup-plugin-visualizer is aimed at that moment. It hooks into the build, reads the module graph and the emitted chunks, and writes a report you open in a browser or commit to a repository.

The audience is narrow and specific: people who own a Rollup, Rolldown or Vite build configuration. Not application developers who never touch the config, and not teams on webpack, which the README does not cover. If your build is generated and you never read it, the plugin has nothing to tell you.

How the report is assembled: bundle metadata, not source code

The plugin runs as a build plugin and collects statistical metadata about the output. The README is explicit about what ends up in the generated HTML: the JS, HTML and CSS needed for the chart UI, plus sizes of files in the bundle, sizes of files in source maps, file paths and file hierarchy. It does not include your source code contents. That distinction matters if you plan to attach a report to a pull request or a ticket, because the artefact describes shape and size rather than behaviour.

Colouring is decided by path. Blue marks project files, including files generated by the build tool, and green marks dependencies. The rule is literal: a file is a dependency if its path starts with node_modules. That is a cheap heuristic and it shows. A vendored library copied into src/ renders blue. A workspace package symlinked through node_modules renders green.

Each template reads the same underlying data differently. Sunburst is the circular view for spotting large chunks; clicking an arc zooms in and enlarges nested arcs. Flamegraph is described as a top-down version of the same data. Treemap gives a rectangular hierarchy that makes large modules easy to find and can reveal repeated modules, because duplicated content tends to show similar structure and relative size. Network answers a different question, why something is included, with gray circles for tree-shaken files and a tooltip listing the files that import a node. Raw-data emits JSON, list emits YAML, markdown emits summary tables with notes about config and size precision.

Installing it and getting a first treemap out of a Vite build

The package installs as a dev dependency. The README gives npm and yarn forms; the npm one is below.

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

The README states the package requires Node.js >= 22, so check that before anything else. If your CI image or local runtime is older, the install succeeds and the build is where you find out.

For Vite, the README's example imports the named export and adds it to the plugins array. Keep it last in that array, which the README repeats for Rollup and for the sourcemap option.

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

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

Run your normal build command. With no options, the template defaults to treemap and the file is named stats plus an extension based on the template, so you should see a stats.html in the working directory after the build finishes. Open it in a browser. The treemap is the default because it is the least ambiguous layout: rectangles sized by module, nested by hierarchy, blue for your files and green for node_modules.

TypeScript configs need a cast, because the plugin type does not line up with Vite's PluginOption. The README shows this form.

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

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

Two options are worth setting on the first run. gzipSize and brotliSize both default to false; turning them on adds compressed sizes to the report, which is closer to what a user downloads than raw bytes. open defaults to false and, when set, launches the generated file in your default browser.

Picking a template, and why the network view is the awkward one

The template option takes sunburst, treemap, treemap-3d, network, raw-data, list, markdown or flamegraph, and defaults to treemap. filename defaults to stats plus an extension derived from the template, and title defaults to Rollup Visualizer and sets the HTML title element.

Network is the only view that answers causality rather than size, and the README is honest that it can be noisy on real projects. It suggests a procedure: remove highly connected helper nodes such as commonjsHelpers, tslib or react when they dominate the graph, wait for the force layout to stabilise, then explore the clusters that become readable. Dragging nodes is possible once the layout settles. Gray circles are tree-shaken files, which is the detail worth checking, because a gray node inside a chunk you thought was dead code is a concrete finding.

If you want a report that survives a commit, list is the template the README points at for tracking bundle changes over time. It produces YAML, and the README states list output follows SemVer. Raw-data produces JSON and carries its own version field. Markdown produces summary tables and notes about config and size precision, and the README says it does not follow any versioning for now. That is a real constraint if you were planning to parse markdown output in a script.

Merging reports from several builds with the CLI

The package ships a binary, rollup-plugin-visualizer, declared in package.json as ./dist/bin/cli.js. The README describes the use case directly: multiple build configs whose reports you want combined into one chart. The invocation takes the report files as positional arguments.

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

The README says to use --help for the full option list, and that is the honest place to look, because the README does not enumerate the CLI flags beyond this. The inputs are the JSON reports produced by the raw-data template, which the README describes as usually used together with the CLI. So the workflow is: set template to raw-data in each config, build each one, then merge.

The SvelteKit case is where this becomes necessary rather than convenient. The README notes that SvelteKit may run Vite multiple times, so you can end up with two or three generated files in .svelte-kit/output, and it tells you to check the Vite logs for the exact locations. The README's SvelteKit example sets emitFile to true and filename to stats.html. When emitFile is true, filename must be a file name and not a path, because Rollup manages the output location.

Where the plugin stops being the right tool

The include and exclude filters use picomatch globs with a specific string grammar: BUNDLE_GLOB:FILE_GLOB, where the colon is required whenever bundle matching is used. Bundle only is translation-*.js: with a trailing colon. File only is the default form, */**/index.js. The Filter type is an object with bundle and file keys. The README's rule is simple but easy to get wrong in the other direction: 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. Add an include filter carelessly and you silently drop modules from the report rather than from the bundle, which is a confusing failure because the build output is fine and only the chart is wrong.

Source maps are a second sharp edge. The sourcemap option defaults to false and is described as using source maps for module size calculations, for example after Terser or UglifyJS, with the instruction to keep the plugin last. Without it, sizes reflect post-transform output, so a minified bundle reports sizes that do not map back to the modules you wrote.

The plugin is also the wrong tool when you want a number rather than a picture. It reports sizes and hierarchy; it does not tell you what to delete. And it is the wrong tool for anyone who needs a stable machine-readable contract from the markdown template, which the README says follows no versioning.

Alternatives, and the actual difference in approach

The closest alternative in the search data is Vite-bundle-visualizer, which people also look for as Vite plugin-visualizer. The difference is scope of integration: rollup-plugin-visualizer is a plugin you add to a config you already own, and it works across Rollup, Rolldown and Vite, with peer dependencies declared as rollup 2.x, 3.x or 4.x and rolldown 1.x including the beta and rc ranges, both optional. A Vite-only visualizer covers one bundler. If your repository has a Rollup library build and a Vite application build, the plugin form means one tool and one report format for both, and the CLI merge step exists precisely for that situation.

The other names in the search data, Rollup/plugin-node-resolve and Rollup/plugin-terser, are not alternatives at all; they are other plugins in the same pipeline, and the README references terser only as the reason you might enable the sourcemap option. Rollup-plugin analyzer is the generic label for this category rather than a distinct project.

Rolldown is the interesting case. The README gives a rolldown.config.ts example that imports defineConfig and the RolldownPlugin type from rolldown and casts the visualizer to RolldownPlugin. That cast is the tell: the plugin is written against the Rollup plugin interface and adapted, rather than being a native Rolldown plugin. It works, according to the documented example, but the type system needs convincing.

Maintenance, licence and what upgrades actually cost

The repository is not archived, and the last push was on 2026-08-14. The package version in package.json is 7.1.1, and the README points at CHANGELOG.md for upgrade notes rather than reproducing them. The licence is MIT, declared both in the README badge area and in package.json as "license": "MIT", with the author listed as Denis Bardadym. MIT is permissive and imposes no copyleft obligation on your build output; the generated reports are artefacts of your own code, and the README states they contain no source contents. That is a factual description of the licence and the artefact, not legal advice, and if you redistribute reports outside your organisation you should read the LICENSE file rather than this paragraph.

The upgrade cost is uneven by design, and the README says so. The plugin API, meaning the part used in your build config, follows SemVer. The frontend report templates for network, treemap, sunburst and flamegraph can change visual details without strict SemVer guarantees, so a minor release can alter how a chart looks without breaking your config. The list output follows SemVer. Raw-data carries its own version field. Markdown follows no versioning at all, which the README attributes to LLM development. If a downstream script parses markdown reports, that script is the thing most likely to break on an upgrade, not your build.

Editorial conclusion

Adopt it if you build with Rollup, Rolldown or Vite and need to answer why a dependency is in the output; the network view is the one view that answers that question, and the list template is the one that survives a commit. Skip it if you are on Node.js below 22, or if you need a stable, machine-readable schema for a dashboard, because the markdown template explicitly does not follow any versioning. Before wiring it in, check the Node version in your CI image and confirm which config file your framework actually reads, since Vite and SvelteKit both have their own conventions here.

Frequently asked questions

Official sources

1. btd/rollup-plugin-visualizer on GitHub
2. Issues
3. License: MIT
4. README