0
# Plugin Configuration
1

2
Core plugin factory function and configuration options for creating bundle visualization plugins.
3

4
```typescript
5
import { visualizer, PluginVisualizerOptions } from "rollup-plugin-visualizer";
6
import { Plugin, OutputOptions } from "rollup";
7
import { Options as OpenOptions } from "open";
8
```
9

10
## Capabilities
11

12
### Visualizer Function
13

14
Creates a Rollup plugin instance for bundle visualization and analysis.
15

16
```typescript { .api }
17
import { Plugin, OutputOptions } from "rollup";
18

19
/**
20
 * Creates a Rollup plugin instance for bundle visualization and analysis
21
 * @param opts - Configuration options or function returning options
22
 * @returns Rollup plugin instance
23
 */
24
function visualizer(
25
  opts?: PluginVisualizerOptions | ((outputOptions: OutputOptions) => PluginVisualizerOptions)
26
): Plugin;
27
```
28

29
The `visualizer` function is the main entry point that accepts either static configuration options or a function that receives Rollup's output options and returns configuration.
30

31
**Usage Examples:**
32

33
```typescript
34
import { visualizer } from "rollup-plugin-visualizer";
35

36
// Static configuration
37
export default {
38
  plugins: [
39
    visualizer({
40
      filename: 'bundle-stats.html',
41
      template: 'treemap',
42
      open: true
43
    })
44
  ]
45
};
46

47
// Dynamic configuration based on output options
48
export default {
49
  plugins: [
50
    visualizer((outputOptions) => ({
51
      filename: `${outputOptions.dir}/stats.html`,
52
      template: outputOptions.format === 'es' ? 'network' : 'treemap'
53
    }))
54
  ]
55
};
56
```
57

58
### Plugin Options Interface
59

60
Complete configuration interface for the visualizer plugin.
61

62
```typescript { .api }
63
import { Options as OpenOptions } from "open";
64

65
interface PluginVisualizerOptions {
66
  /** Output file name or path (default: "stats.html") */
67
  filename?: string;
68
  
69
  /** DEPRECATED: Use template: "raw-data" instead */
70
  json?: boolean;
71
  
72
  /** HTML title for generated file (default: "Rollup Visualizer") */
73
  title?: string;
74
  
75
  /** Open generated file in browser (default: false) */
76
  open?: boolean;
77
  
78
  /** Options for opening file */
79
  openOptions?: OpenOptions;
80
  
81
  /** Visualization template type (default: "treemap") */
82
  template?: TemplateType;
83
  
84
  /** Calculate gzipped sizes (default: false) */
85
  gzipSize?: boolean;
86
  
87
  /** Calculate brotli sizes (default: false) */
88
  brotliSize?: boolean;
89
  
90
  /** Use sourcemaps for size calculation (default: false) */
91
  sourcemap?: boolean;
92
  
93
  /** Project root path for file path normalization */
94
  projectRoot?: string | RegExp;
95
  
96
  /** Use rollup's emitFile API (default: false) */
97
  emitFile?: boolean;
98
  
99
  /** Inclusion filters */
100
  include?: Filter | Filter[];
101
  
102
  /** Exclusion filters */
103
  exclude?: Filter | Filter[];
104
}
105
```
106

107
**Key Configuration Options:**
108

109
- **`filename`**: Controls output file location. When using `emitFile: true`, must be filename only, not a path.
110
- **`template`**: Chooses visualization type. Each template provides different insights:
111
  - `treemap`: Best for finding large modules (rectangular layout)
112
  - `sunburst`: Hierarchical circular view, good for deep dependency trees
113
  - `network`: Shows dependency relationships, answers "why is this included?"
114
  - `flamegraph`: Familiar to developers, top-down hierarchical view
115
  - `raw-data`: JSON output for programmatic analysis
116
  - `list`: YAML output for tracking changes
117
- **`gzipSize`/`brotliSize`**: Add compression analysis (cannot be used with `sourcemap`)
118
- **`sourcemap`**: Use sourcemaps for more accurate size analysis
119
- **`emitFile`**: Integrate with Rollup's file emission system instead of writing files directly
120

121
**Advanced Configuration Examples:**
122

123
```typescript
124
// Production build with compression analysis
125
visualizer({
126
  filename: 'dist/bundle-analysis.html',
127
  template: 'treemap',
128
  gzipSize: true,
129
  brotliSize: true,
130
  open: false
131
})
132

133
// Development with network diagram
134
visualizer({
135
  filename: 'dev-stats.html',
136
  template: 'network',
137
  open: true,
138
  sourcemap: true
139
})
140

141
// JSON output for CI/CD integration
142
visualizer({
143
  filename: 'stats.json',
144
  template: 'raw-data',
145
  emitFile: true
146
})
147

148
// With filtering
149
visualizer({
150
  filename: 'filtered-stats.html',
151
  template: 'sunburst',
152
  exclude: [
153
    { file: 'node_modules/**' }, // Exclude all node_modules
154
    { bundle: 'vendor-*' }       // Exclude vendor bundles
155
  ]
156
})
157
```
158

159
### Template Types
160

161
Available visualization template types for different analysis needs.
162

163
```typescript { .api }
164
type TemplateType = "sunburst" | "treemap" | "network" | "raw-data" | "list" | "flamegraph";
165
```
166

167
Each template serves different analysis purposes:
168

169
- **sunburst**: Circular hierarchical diagram for finding large pieces and understanding structure
170
- **treemap**: Rectangular hierarchical diagram, excellent for spotting large modules and duplicates
171
- **network**: Force-directed graph showing dependency relationships
172
- **raw-data**: JSON output containing all analysis data
173
- **list**: YAML format suitable for version control tracking
174
- **flamegraph**: Top-down hierarchical view familiar from profiling tools
175

176
### Open Options
177

178
Configuration for automatically opening generated files.
179

180
```typescript { .api }
181
/**
182
 * Options for opening files with the 'open' package
183
 */
184
interface OpenOptions {
185
  /** App name or array of app names/arguments to open with */
186
  app?: string | string[];
187
  /** Wait for opened app to exit before calling callback */
188
  wait?: boolean;
189
  /** Do not bring the app to the foreground (macOS only) */
190
  background?: boolean;
191
  /** Open new instance of app even if one is already running */
192
  newInstance?: boolean;
193
  /** Allow app to exit with non-zero exit code */
194
  allowNonzeroExit?: boolean;
195
}
196
```
197

198
Used with the `open` option to customize how generated files are opened in the browser or other applications.