Update readme

btd · btd · commit 96639070b46f · 2026-02-20T15:18:50.000+01:00
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 [![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)
 
-Visualize and analyze your Rollup bundle to see which modules are taking up space.
+Visualize and analyze your bundle to quickly see which modules are taking up space.
 
 ## Screenshots
 
@@ -20,44 +20,49 @@ or via yarn:
 yarn add --dev rollup-plugin-visualizer
 ```
 
-## Usage
-
 ## Requirements
 
-This package is **ESM-only** and requires Node.js >= 22.
+This package requires Node.js >= 22.
+
+## Usage
 
-Import
+Import the plugin:
 
 ```javascript
 import { visualizer } from "rollup-plugin-visualizer";
 ```
 
-Usage with rollup (rollup.config.js)
+Or in CommonJS:
+
+```js
+const { visualizer } = require("rollup-plugin-visualizer");
+```
+
+### Rollup (`rollup.config.js`)
 
 ```js
 import { visualizer } from "rollup-plugin-visualizer";
 
 export default {
   plugins: [
-    // put it last
+    // Keep it last.
     visualizer(),
   ],
 };
 ```
 
-Usage with rolldown (rolldown.config.ts)
+### Rolldown (`rolldown.config.ts`)
 
 ```js
-import { defineConfig, type RolldownPlugin } from 'rolldown';
+import { defineConfig, type RolldownPlugin } from "rolldown";
+import { visualizer } from "rollup-plugin-visualizer";
 
 export default defineConfig({
-  plugins: [
-    visualizer() as RolldownPlugin
-  ],
-})
+  plugins: [visualizer() as RolldownPlugin],
+});
 ```
 
-Usage with vite (vite.config.js)
+### Vite (`vite.config.js`)
 
 ```js
 import { visualizer } from "rollup-plugin-visualizer";
@@ -67,17 +72,18 @@ export default {
 };
 ```
 
-Usage with vite TypeScript (vite.config.ts)
+### 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],
 });
 ```
 
-Usage with SvelteKit (vite.config.js)
+### SvelteKit (`vite.config.js`)
 
 ```js
 import { visualizer } from "rollup-plugin-visualizer";
@@ -92,131 +98,129 @@ export default {
 };
 ```
 
-You will find 2/3 files in .svelte-kit/output dir named stats.html (see vite logs for file locations) . You can use this snippet as a starting point and change props/path.
-You can also generate 3 json files and combine them to one with cli util.
-
-## How to use generated files
-
-Blue color used to to mark project-own files. This could be: written by you files or generated by build tool files.
+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.
 
-Green color used to mark your dependencies.
+## Understanding The Report
 
-Internally it just checks if file id prefix is `node_modules`.
-
-All charts refresh layout on window resize.
+- 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
 
-This circular hierarchical diagram can help you find huge pieces of code (aka that one huge thing). If you click on some arc it will increase its and all nested arcs size for better inspection.
+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 diagram is top down version of sunburst. It is used a lot by other JS developer tools and would be very familar to developers.
+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 diagram can help you find huge pieces. Just look on biggest rectangle. But also it can help you find modules included several times, they will have the same topology and relative size. If you click on rectangle it will increase in size for further inspection.
+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
 
-This diagram should help you answer for the question 'why it is included?'. After force layout stabilize all nodes, you can move it back and forth by dragging with your mouse. Gray circles are treeshaken out files.
+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:
 
-In real life scenarios, sometimes you will see terribly connected diagrams. There is no 100% working solution for everyone, it is expected you topology will look 'terrible' and not hold on screen. To make it still visually inspectable, first remove all highly connected nodes that you see (typical examples: commonjsHelpers, tslib, react etc, basically if tooltip for the node is not hold on the screen - exclude this node), after layout stabilization you will see, your layout is not that terrible anymore and most of dependencies cluster together. Move layout to find pieces you looked for.
+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.
 
-When you click on node it will highlight nodes that are listed in tooltip (the files that imports current node).
+Clicking a node highlights nodes listed in its tooltip (the files that import that node).
 
 ### Raw-data
 
-This template produce JSON output with raw data. Normally it should be used with CLI from this plugin.
+Produces JSON output with raw data. Usually used together with the CLI.
 
 ### List
 
-Output yml file with all the data, could be good idea to commit this file to track file changes.
+Produces a YAML file with report data. This is useful to commit and track bundle changes over time.
 
 ### Markdown
 
-Output markdown report with summary tables and bottom notes about report config and size precision.
+Produces a Markdown report with summary tables and notes about config and size precision.
 
 ## Options
 
-`filename` (string, default `stats.{ext depending template}`) - name of the file with diagram to generate
-
-`title` (string, default `Rollup Visualizer`) - title tag value
-
-`open` (boolean, default `false`) - Open generated file in default user agent
-
-`template` (string, default `treemap`) - Which diagram type to use: `sunburst`, `treemap`, `network`, `raw-data`, `list`, `markdown`, `flamegraph`.
-
-`gzipSize` (boolean, default `false`) - Collect gzip size from source code and display it at chart.
-
-`brotliSize` (boolean, default `false`) - Collect brotli size from source code and display it at chart.
+- `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`, `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 (touch only if you really need it):
+### Advanced options (only if needed)
 
-`emitFile` (boolean, default `false`) - Use rollup's `emitFile` to generate file. Useful if you want to control all output in one place (via rollup output options). This also could be useful with svelte as it calls vite several times.
+- `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.
 
-`sourcemap` (boolean, default `false`) - Use sourcemaps to calculate sizes (e.g. after UglifyJs or Terser). **Always add plugin as last option.**
+`Filter` type: `{ bundle?: picomatchPattern, file?: picomatchPattern }`
 
-`projectRoot` (string | RegExp, default `process.cwd()`) - This is some common root(s) path to your files. This is used to cut absolute files paths out.
+**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` (Filter | Filter[], default `undefined`) - Filter for inclusion
+### Include And Exclude
 
-`exclude` (Filter | Filter[], default `undefined`) - Filter for exclusion
+Filters use picomatch globs, and support these forms:
 
-`Filter` type is `{ bundle?: picomatchPattern, file?: picomatchPattern }`
+- Bundle + file in one string: `translation-*.js:*/**/index.js`
+- Bundle only: `translation-*.js:`
+- File only (default): `*/**/index.js`
 
-**Note about `include` and `exclude`** - If options.include is omitted or has zero length, filter will return true by default. Otherwise, an ID must match one or more of the picomatch patterns, and must not match any of the options.exclude patterns. This entries will not be included in stats at all.
-
-#### Include and Exclude
-
-Include and exclude filters uses glob matchers with picomatch. In UI you can do such combinations (both exclude and include):
-
-- Filter bundle and file in one string
-  - `translation-*.js:*/**/index.js` - this selects all bundles that matches `translation-*.js` and all the files by all paths that name is `index.js`. `:` is separator and required only when bundle search used.
-  - Format for this kind of filter is `BUNDLE_GLOB:FILE_GLOB`
-- Filter bundle in one string
-  - This is special case of bundle+file filter, you need to omit `FILE_GLOB` part (empty string)
-- Filter file in one string
-  - **This is DEFAULT search option**
-  - `*/**/index.js` - select all files that name is index.js
+Format: `BUNDLE_GLOB:FILE_GLOB` (`:` is required when bundle matching is used).
 
 ## CLI
 
-This plugin provides cli util `rollup-plugin-visualizer`. Add `--help` to check actual options. It can be used like:
+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 can be useful in case you have different config files in the same project and you want to display all of them in the same chart.
+This is useful when you have multiple build configs and want to combine reports into one chart.
 
 ## Build plugin
 
-For development if you need to build plugin, just exec:
+For local development:
 
-```js
+```sh
 npm run build
 ```
 
 ## Disclaimer about generated files
 
-Generated html files do not and never will contain your source code (contents of files). They can contain only js/html/css code required to build chart (plugin code) and statistical information about your source code.
+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 statistical information can contain:
+This metadata can include:
 
-- size of files included in bundle
-- size of files included in source map
-- file's paths
-- files hierarchy (fs tree for your files)
+- Sizes of files in the bundle
+- Sizes of files in source maps
+- File paths
+- File hierarchy
 
 ## Upgrades
 
-See CHANGELOG.md.
+See `CHANGELOG.md`.
 
 ## Versioning
 
-- Plugin backend (one appears in configs) are strictly follows SemVer
-  - Plugin frontend (generated file):
-  - `network`, `treemap`, `sunburst`, `flamegraph` can change does not matter of version (colors, texts, visual structure etc)
-  - `raw-data` format follows own `version` property
-  - `list` and `markdown` follows semver
+- 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` output follows SemVer.
+- `markdown` output is experimental and does not follow strict versioning. It will evolve with LLM capabilities.
