0
# Rollup Plugin Visualizer
1

2
Rollup Plugin Visualizer provides comprehensive bundle analysis and visualization for Rollup, Vite, and other build tools. It generates interactive charts and diagrams to help identify large modules, understand dependency relationships, and optimize bundle size through multiple visualization templates including treemap, sunburst, network diagrams, and flamegraphs.
3

4
## Package Information
5

6
- **Package Name**: rollup-plugin-visualizer
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install --save-dev rollup-plugin-visualizer`
10

11
## Core Imports
12

13
```typescript
14
import { visualizer } from "rollup-plugin-visualizer";
15
// or
16
import visualizer from "rollup-plugin-visualizer";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const { visualizer } = require("rollup-plugin-visualizer");
23
// or
24
const visualizer = require("rollup-plugin-visualizer").default;
25
```
26

27
## Basic Usage
28

29
```typescript
30
import { visualizer } from "rollup-plugin-visualizer";
31

32
export default {
33
  plugins: [
34
    // Put it last in plugins array
35
    visualizer({
36
      filename: 'stats.html',
37
      template: 'treemap',
38
      open: true,
39
      gzipSize: true
40
    })
41
  ]
42
};
43
```
44

45
With Vite:
46

47
```typescript
48
import { defineConfig, type PluginOption } from "vite";
49
import { visualizer } from "rollup-plugin-visualizer";
50

51
export default defineConfig({
52
  plugins: [
53
    visualizer({
54
      filename: 'dist/stats.html',
55
      template: 'sunburst'
56
    }) as PluginOption
57
  ]
58
});
59
```
60

61
## Architecture
62

63
Rollup Plugin Visualizer is built around several key components:
64

65
- **Plugin Factory**: Main `visualizer` function that creates Rollup plugin instances
66
- **Template Engine**: Multiple visualization templates (treemap, sunburst, network, flamegraph, etc.)
67
- **Data Processing**: Module tree building, sourcemap analysis, and size calculation
68
- **Filter System**: Include/exclude patterns for selective analysis
69
- **CLI Utility**: Standalone tool for combining multiple bundle analyses
70
- **Compression Analysis**: Optional gzip/brotli size calculation
71

72
## Capabilities
73

74
### Plugin Configuration
75

76
Core plugin factory function and configuration options for creating bundle visualization plugins.
77

78
```typescript { .api }
79
import { Plugin, OutputOptions } from "rollup";
80
import { Options as OpenOptions } from "open";
81

82
function visualizer(
83
  opts?: PluginVisualizerOptions | ((outputOptions: OutputOptions) => PluginVisualizerOptions)
84
): Plugin;
85

86
interface PluginVisualizerOptions {
87
  filename?: string;
88
  json?: boolean; // DEPRECATED: use template: "raw-data"
89
  title?: string;
90
  open?: boolean;
91
  openOptions?: OpenOptions;
92
  template?: TemplateType;
93
  gzipSize?: boolean;
94
  brotliSize?: boolean;
95
  sourcemap?: boolean;
96
  projectRoot?: string | RegExp;
97
  emitFile?: boolean;
98
  include?: Filter | Filter[];
99
  exclude?: Filter | Filter[];
100
}
101
```
102

103
[Plugin Configuration](./plugin-configuration.md)
104

105
### Data Types and Structures
106

107
Core type definitions for module trees, bundle data, and visualization information used throughout the plugin.
108

109
```typescript { .api }
110
interface VisualizerData {
111
  version: number;
112
  tree: ModuleTree;
113
  nodeParts: Record<ModuleUID, ModulePart>;
114
  nodeMetas: Record<ModuleUID, ModuleMeta>;
115
  env: { [key: string]: unknown };
116
  options: { gzip: boolean; brotli: boolean; sourcemap: boolean };
117
}
118

119
interface ModuleTree {
120
  name: string;
121
  children: Array<ModuleTree | ModuleTreeLeaf>;
122
}
123

124
type TemplateType = "sunburst" | "treemap" | "network" | "raw-data" | "list" | "flamegraph";
125
```
126

127
[Data Types](./data-types.md)
128

129
### Filter System
130

131
Module filtering functionality for selective bundle analysis based on bundle names and file patterns.
132

133
```typescript { .api }
134
function createFilter(
135
  include: Filter | Filter[] | undefined,
136
  exclude: Filter | Filter[] | undefined
137
): (bundleId: string, id: string) => boolean;
138

139
type Filter = {
140
  bundle?: string | null | undefined;
141
  file?: string | null | undefined;
142
};
143
```
144

145
[Filter System](./filter-system.md)
146

147
### CLI Utility
148

149
Command-line interface for processing and combining multiple visualization data files into unified analysis.
150

151
```typescript { .api }
152
// CLI binary available at: rollup-plugin-visualizer
153
// Usage: rollup-plugin-visualizer [OPTIONS] stat1.json stat2.json
154
```
155

156
[CLI Utility](./cli-utility.md)
157

158
## Types
159

160
```typescript { .api }
161
type ModuleUID = string;
162
type BundleId = string;
163
type SizeKey = "renderedLength" | "gzipLength" | "brotliLength";
164

165
interface ModuleLengths {
166
  renderedLength: number;
167
  gzipLength: number;
168
  brotliLength: number;
169
}
170

171
interface ModuleTreeLeaf {
172
  name: string;
173
  uid: ModuleUID;
174
}
175
```