0
# Next.js Bundle Analyzer
1

2
Next.js Bundle Analyzer is a configuration wrapper that integrates webpack-bundle-analyzer into Next.js projects. It provides a higher-order function that conditionally enables bundle analysis based on configuration, generating detailed reports for client-side, server-side (Node.js), and edge runtime bundles to help developers optimize their application bundles.
3

4
## Package Information
5

6
- **Package Name**: @next/bundle-analyzer
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install @next/bundle-analyzer`
10

11
## Core Imports
12

13
```javascript
14
const withBundleAnalyzer = require('@next/bundle-analyzer');
15
```
16

17
For TypeScript:
18

19
```typescript
20
import withBundleAnalyzer from '@next/bundle-analyzer';
21
```
22

23
## Basic Usage
24

25
```javascript
26
// next.config.js
27
const withBundleAnalyzer = require('@next/bundle-analyzer')({
28
  enabled: process.env.ANALYZE === 'true',
29
});
30

31
module.exports = withBundleAnalyzer({
32
  // Your Next.js config
33
});
34
```
35

36
Build with analysis enabled:
37

38
```bash
39
ANALYZE=true npm run build
40
```
41

42
This generates bundle analysis reports in `<distDir>/analyze/`:
43
- `client.html` - Client-side bundle analysis
44
- `nodejs.html` - Node.js server bundle analysis
45
- `edge.html` - Edge runtime bundle analysis
46

47
## Capabilities
48

49
### Bundle Analyzer Configuration
50

51
Creates a Next.js configuration wrapper that conditionally enables webpack-bundle-analyzer.
52

53
```typescript { .api }
54
/**
55
 * Creates a Next.js configuration wrapper with webpack-bundle-analyzer integration
56
 * @param options - Configuration options for bundle analysis
57
 * @returns Function that takes Next.js config and returns enhanced config
58
 */
59
function NextBundleAnalyzer(options?: {
60
  /** Whether to enable bundle analysis (default: true) */
61
  enabled?: boolean;
62
  /** Whether to automatically open the report in browser */
63
  openAnalyzer?: boolean;
64
  /** Output format - 'static' for HTML, 'json' for JSON data (default: 'static') */
65
  analyzerMode?: 'json' | 'static';
66
  /** Log level for bundle analyzer (default: 'info') */
67
  logLevel?: 'info' | 'warn' | 'error' | 'silent' | undefined;
68
}): (config?: NextConfig) => NextConfig;
69
```
70

71
**Usage Examples:**
72

73
```javascript
74
// Basic usage with environment variable control
75
const withBundleAnalyzer = require('@next/bundle-analyzer')({
76
  enabled: process.env.ANALYZE === 'true',
77
});
78

79
module.exports = withBundleAnalyzer({
80
  // Your Next.js configuration
81
  experimental: {
82
    appDir: true,
83
  },
84
});
85
```
86

87
```javascript
88
// Advanced configuration
89
const withBundleAnalyzer = require('@next/bundle-analyzer')({
90
  enabled: process.env.ANALYZE === 'true',
91
  openAnalyzer: false,
92
  analyzerMode: 'json',
93
  logLevel: 'warn',
94
});
95

96
module.exports = withBundleAnalyzer({
97
  // Your Next.js configuration
98
});
99
```
100

101
```javascript
102
// Use with next-compose-plugins
103
const withPlugins = require('next-compose-plugins');
104
const withBundleAnalyzer = require('@next/bundle-analyzer')({
105
  enabled: process.env.ANALYZE === 'true',
106
});
107

108
module.exports = withPlugins([
109
  [withBundleAnalyzer],
110
  // other plugins here
111
]);
112
```
113

114
```javascript
115
// Configuration as a function
116
module.exports = (phase, defaultConfig) => {
117
  const withBundleAnalyzer = require('@next/bundle-analyzer')({
118
    enabled: process.env.ANALYZE === 'true',
119
  });
120
  return withBundleAnalyzer(defaultConfig);
121
};
122
```
123

124
### Configuration Options
125

126
The bundle analyzer accepts an options object with the following properties:
127

128
#### enabled
129
- **Type**: `boolean`
130
- **Default**: `true`
131
- **Description**: Controls whether bundle analysis is enabled. Commonly set to `process.env.ANALYZE === 'true'` for conditional activation.
132

133
#### openAnalyzer
134
- **Type**: `boolean`
135
- **Default**: `undefined` (uses webpack-bundle-analyzer default)
136
- **Description**: Whether to automatically open the bundle report in the default browser after analysis completes.
137

138
#### analyzerMode
139
- **Type**: `'json' | 'static'`
140
- **Default**: `'static'`
141
- **Description**: Output format for bundle analysis reports. `'static'` generates HTML files, `'json'` generates JSON data files.
142

143
#### logLevel
144
- **Type**: `'info' | 'warn' | 'error' | 'silent' | undefined`
145
- **Default**: `'info'`
146
- **Description**: Controls the verbosity of bundle analyzer logging output.
147

148
## Types
149

150
```typescript { .api }
151
import type { NextConfig } from 'next';
152

153
interface BundleAnalyzerOptions {
154
  enabled?: boolean;
155
  openAnalyzer?: boolean;
156
  analyzerMode?: 'json' | 'static';
157
  logLevel?: 'info' | 'warn' | 'error' | 'silent' | undefined;
158
}
159

160
type ConfigEnhancer = (config?: NextConfig) => NextConfig;
161
```
162

163
## Output Files
164

165
When enabled, the bundle analyzer generates reports in the following locations within your Next.js build output directory:
166

167
- **Client Bundle**: `analyze/client.html` (or `.json`)
168
  - Analysis of the client-side JavaScript bundle
169
  - Shows modules included in the browser bundle
170

171
- **Node.js Server Bundle**: `analyze/nodejs.html` (or `.json`)
172
  - Analysis of the server-side bundle for Node.js runtime
173
  - Shows server-side modules and dependencies
174

175
- **Edge Runtime Bundle**: `analyze/edge.html` (or `.json`)
176
  - Analysis of the edge runtime bundle
177
  - Shows modules optimized for edge computing environments
178

179
## Installation Notes
180

181
If installing as a `devDependency`, wrap the require in a process.env check in your `next.config.js` since the config file is loaded during `next start`:
182

183
```javascript
184
const withBundleAnalyzer = process.env.NODE_ENV === 'development' 
185
  ? require('@next/bundle-analyzer')({
186
      enabled: process.env.ANALYZE === 'true',
187
    })
188
  : (config) => config;
189

190
module.exports = withBundleAnalyzer({
191
  // Your Next.js config
192
});
193
```
194

195
## Dependencies
196

197
This package depends on `webpack-bundle-analyzer@4.10.1` which provides the core bundle analysis functionality.