0
# Webpack Plugin
1

2
The BundleAnalyzerPlugin is the primary webpack plugin class that integrates bundle analysis into your webpack build process. It provides multiple analysis modes, flexible configuration options, and seamless integration with webpack's plugin system.
3

4
## Capabilities
5

6
### BundleAnalyzerPlugin Constructor
7

8
Creates a new instance of the webpack bundle analyzer plugin with optional configuration.
9

10
```javascript { .api }
11
/**
12
 * Creates a new BundleAnalyzerPlugin instance
13
 * @param options - Plugin configuration options
14
 */
15
class BundleAnalyzerPlugin {
16
  constructor(options?: BundleAnalyzerOptions);
17
  apply(compiler: object): void;
18
}
19

20
interface BundleAnalyzerOptions {
21
  /** Analysis mode: server starts HTTP server, static generates HTML file, json creates JSON report, disabled only generates stats */
22
  analyzerMode?: 'server' | 'static' | 'json' | 'disabled';
23
  /** Host for HTTP server in server mode */
24
  analyzerHost?: string;
25
  /** Port for HTTP server in server mode, 'auto' for automatic assignment */
26
  analyzerPort?: number | 'auto';
27
  /** Custom URL generation function for server mode */
28
  analyzerUrl?: (options: { listenHost: string; listenPort: number; boundAddress: object }) => string;
29
  /** Output filename for static and JSON modes, relative to webpack output directory */
30
  reportFilename?: string;
31
  /** Report title, can be string or function returning string */
32
  reportTitle?: string | (() => string);
33
  /** Default size type to display in visualization */
34
  defaultSizes?: 'stat' | 'parsed' | 'gzip';
35
  /** Whether to automatically open report in browser */
36
  openAnalyzer?: boolean;
37
  /** Whether to generate webpack stats JSON file */
38
  generateStatsFile?: boolean;
39
  /** Filename for webpack stats JSON file */
40
  statsFilename?: string;
41
  /** Options passed to stats.toJson() method */
42
  statsOptions?: object;
43
  /** Patterns to exclude assets from analysis */
44
  excludeAssets?: string | RegExp | ((assetName: string) => boolean) | Array<string | RegExp | ((assetName: string) => boolean)>;
45
  /** Logging level for plugin output */
46
  logLevel?: 'info' | 'warn' | 'error' | 'silent';
47
  /** Whether to start analyzer server (deprecated, use analyzerMode instead) */
48
  startAnalyzer?: boolean;
49
}
50
```
51

52
**Usage Examples:**
53

54
```javascript
55
const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer');
56

57
// Basic usage with default options
58
module.exports = {
59
  plugins: [
60
    new BundleAnalyzerPlugin()
61
  ]
62
};
63

64
// Server mode with custom port
65
module.exports = {
66
  plugins: [
67
    new BundleAnalyzerPlugin({
68
      analyzerMode: 'server',
69
      analyzerHost: 'localhost',
70
      analyzerPort: 9999,
71
      openAnalyzer: true
72
    })
73
  ]
74
};
75

76
// Static report generation
77
module.exports = {
78
  plugins: [
79
    new BundleAnalyzerPlugin({
80
      analyzerMode: 'static',
81
      reportFilename: 'bundle-report.html',
82
      openAnalyzer: false
83
    })
84
  ]
85
};
86

87
// JSON report with stats file
88
module.exports = {
89
  plugins: [
90
    new BundleAnalyzerPlugin({
91
      analyzerMode: 'json',
92
      reportFilename: 'bundle-report.json',
93
      generateStatsFile: true,
94
      statsFilename: 'webpack-stats.json'
95
    })
96
  ]
97
};
98
```
99

100
### Plugin Application
101

102
Applies the plugin to a webpack compiler instance, integrating with webpack's compilation lifecycle.
103

104
```javascript { .api }
105
/**
106
 * Applies the plugin to webpack compiler
107
 * @param compiler - Webpack compiler instance
108
 */
109
apply(compiler: object): void;
110
```
111

112
### Asset Exclusion Patterns
113

114
Configure which assets to exclude from bundle analysis using various pattern types.
115

116
```javascript { .api }
117
// Asset filter pattern types
118
type AssetFilterPattern = 
119
  | string              // Converted to RegExp
120
  | RegExp              // Used directly for matching
121
  | ((assetName: string) => boolean);  // Custom filter function
122

123
// Multiple patterns
124
type ExcludeAssets = AssetFilterPattern | AssetFilterPattern[];
125
```
126

127
**Usage Examples:**
128

129
```javascript
130
// Exclude by string pattern (converted to RegExp)
131
new BundleAnalyzerPlugin({
132
  excludeAssets: 'vendor'
133
});
134

135
// Exclude by RegExp
136
new BundleAnalyzerPlugin({
137
  excludeAssets: /\.(css|png|jpg|gif)$/
138
});
139

140
// Exclude by custom function
141
new BundleAnalyzerPlugin({
142
  excludeAssets: (assetName) => assetName.includes('legacy')
143
});
144

145
// Multiple exclusion patterns
146
new BundleAnalyzerPlugin({
147
  excludeAssets: [
148
    'vendor',
149
    /\.css$/,
150
    (assetName) => assetName.startsWith('runtime.')
151
  ]
152
});
153
```
154

155
### Analysis Modes
156

157
Different modes for bundle analysis output and behavior.
158

159
```javascript { .api }
160
type AnalyzerMode = 'server' | 'static' | 'json' | 'disabled';
161
```
162

163
- **server**: Starts HTTP server with interactive visualization (default)
164
- **static**: Generates single HTML file with embedded visualization
165
- **json**: Creates JSON report with bundle data
166
- **disabled**: Only generates stats file if `generateStatsFile` is true
167

168
### Size Types
169

170
Different size metrics available for bundle analysis.
171

172
```javascript { .api }
173
type SizeType = 'stat' | 'parsed' | 'gzip';
174
```
175

176
- **stat**: Original file sizes from webpack stats (before minification)
177
- **parsed**: Actual parsed bundle sizes (after minification)
178
- **gzip**: Gzipped sizes of the parsed bundles
179

180
### Report Title Configuration
181

182
Flexible report title configuration supporting static strings and dynamic generation.
183

184
```javascript { .api }
185
type ReportTitle = string | (() => string);
186
```
187

188
**Usage Examples:**
189

190
```javascript
191
// Static title
192
new BundleAnalyzerPlugin({
193
  reportTitle: 'My App Bundle Analysis'
194
});
195

196
// Dynamic title with current date
197
new BundleAnalyzerPlugin({
198
  reportTitle: () => `Bundle Analysis - ${new Date().toLocaleDateString()}`
199
});
200

201
// Using built-in default title function
202
const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer');
203
const utils = require('webpack-bundle-analyzer/lib/utils');
204

205
new BundleAnalyzerPlugin({
206
  reportTitle: utils.defaultTitle
207
});
208
```