0
# Performance Profiling
1

2
WebpackBar includes a comprehensive profiling system for analyzing build performance, identifying bottlenecks, and optimizing compilation times.
3

4
## Capabilities
5

6
### State Management
7

8
WebpackBar tracks detailed state information for each compilation process.
9

10
```typescript { .api }
11
interface State {
12
  /**
13
   * High-resolution start time using process.hrtime()
14
   */
15
  start: [number, number] | null;
16

17
  /**
18
   * Progress percentage from -1 (not started) to 100 (complete)
19
   */
20
  progress: number;
21

22
  /**
23
   * Whether compilation is complete
24
   */
25
  done: boolean;
26

27
  /**
28
   * Current status message
29
   */
30
  message: string;
31

32
  /**
33
   * Additional status details array
34
   */
35
  details: string[];
36

37
  /**
38
   * Current processing request information
39
   */
40
  request: null | {
41
    file: null | string;      // File being processed
42
    loaders: string[];        // Loaders being applied
43
  };
44

45
  /**
46
   * Whether compilation has errors
47
   */
48
  hasErrors: boolean;
49

50
  /**
51
   * Associated color for display
52
   */
53
  color: string;
54

55
  /**
56
   * Display name
57
   */
58
  name: string;
59
}
60
```
61

62
### Enabling Profiling
63

64
Enable profiling through configuration options.
65

66
**Basic Profiling:**
67

68
```javascript
69
new WebpackBar({
70
  name: 'Production Build',
71
  profile: true
72
});
73
```
74

75
**Profiling with Custom Reporter:**
76

77
```javascript
78
new WebpackBar({
79
  name: 'Performance Analysis',
80
  profile: true,
81
  reporters: ['basic', 'profile']
82
});
83
```
84

85
### Profile Reporter
86

87
The Profile Reporter automatically tracks and displays performance metrics when profiling is enabled.
88

89
```typescript { .api }
90
class ProfileReporter implements Reporter {
91
  /**
92
   * Track request timing data during compilation
93
   */
94
  progress(context: WebpackBar): void;
95

96
  /**
97
   * Generate profiling statistics when compilation completes
98
   */
99
  done(context: WebpackBar): void;
100

101
  /**
102
   * Output formatted profile results after all builds complete
103
   */
104
  allDone(context: WebpackBar): void;
105
}
106
```
107

108
**Profiling Features:**
109
- Request-level timing analysis
110
- Module processing performance
111
- Loader execution times
112
- Build phase breakdowns
113
- Bottleneck identification
114

115
### Build State Access
116

117
Access comprehensive build state information for custom profiling.
118

119
```typescript { .api }
120
import type webpack from "webpack";
121

122
// WebpackBar class instance passed to reporters
123
declare class WebpackBar {
124
  /**
125
   * Check if any compilation is currently running
126
   */
127
  readonly hasRunning: boolean;
128

129
  /**
130
   * Check if any compilation has errors
131
   */
132
  readonly hasErrors: boolean;
133

134
  /**
135
   * Array of all compilation states sorted by name
136
   */
137
  readonly statesArray: State[];
138

139
  /**
140
   * Global states object with all tracked compilations
141
   */
142
  readonly states: { [key: string]: State };
143

144
  /**
145
   * Current state for this plugin instance
146
   */
147
  readonly state: State;
148
  
149
  constructor(options?: WebpackBarOptions);
150
  apply(compiler: webpack.Compiler): void;
151
  updateProgress(percent?: number, message?: string, details?: string[]): void;
152
}
153
```
154

155
**Usage Examples:**
156

157
```javascript
158
// Custom profiling reporter
159
class ProfilingReporter {
160
  constructor() {
161
    this.startTimes = new Map();
162
    this.metrics = [];
163
  }
164

165
  start(context) {
166
    this.startTimes.set(context.state.name, Date.now());
167
  }
168

169
  progress(context) {
170
    const { progress, request, message } = context.state;
171
    
172
    // Track module processing times
173
    if (request && request.file) {
174
      this.metrics.push({
175
        file: request.file,
176
        progress,
177
        timestamp: Date.now(),
178
        message
179
      });
180
    }
181
  }
182

183
  done(context) {
184
    const startTime = this.startTimes.get(context.state.name);
185
    const totalTime = Date.now() - startTime;
186
    
187
    console.log(`Build ${context.state.name} completed in ${totalTime}ms`);
188
    
189
    // Analyze slowest modules
190
    const slowModules = this.metrics
191
      .filter(m => m.file)
192
      .sort((a, b) => b.timestamp - a.timestamp)
193
      .slice(0, 10);
194
      
195
    console.log('Slowest modules:', slowModules);
196
  }
197
}
198

199
new WebpackBar({
200
  name: 'Profiled Build',
201
  reporter: ProfilingReporter
202
});
203
```
204

205
### Performance Metrics
206

207
WebpackBar tracks various performance metrics:
208

209
**Timing Metrics:**
210
- Total compilation time
211
- Module processing time
212
- Loader execution time
213
- Plugin hook execution time
214

215
**Progress Metrics:**
216
- Real-time progress percentage
217
- Module count and processing status
218
- File change detection timing
219

220
**Error Metrics:**
221
- Error occurrence tracking
222
- Error resolution timing
223
- Build failure analysis
224

225
### Multi-Build Profiling
226

227
Profile multiple concurrent builds (useful for SSR scenarios).
228

229
```javascript
230
// Client build with profiling
231
const clientConfig = {
232
  name: 'client',
233
  // ... webpack config
234
  plugins: [
235
    new WebpackBar({
236
      name: 'Client',
237
      color: 'blue',
238
      profile: true
239
    })
240
  ]
241
};
242

243
// Server build with profiling
244
const serverConfig = {
245
  name: 'server',
246
  // ... webpack config
247
  plugins: [
248
    new WebpackBar({
249
      name: 'Server',
250
      color: 'green',
251
      profile: true
252
    })
253
  ]
254
};
255

256
export default [clientConfig, serverConfig];
257
```
258

259
### Watch Mode Profiling
260

261
Special considerations for profiling in watch mode.
262

263
```javascript
264
new WebpackBar({
265
  name: 'Development',
266
  profile: true,
267
  reporter: class WatchProfiler {
268
    change(context, { shortPath, time }) {
269
      console.log(`File changed: ${shortPath} at ${new Date(time).toISOString()}`);
270
    }
271

272
    done(context) {
273
      if (context.state.start) {
274
        const [seconds, nanoseconds] = process.hrtime(context.state.start);
275
        const totalMs = seconds * 1000 + nanoseconds / 1000000;
276
        console.log(`Rebuild completed in ${totalMs.toFixed(2)}ms`);
277
      }
278
    }
279
  }
280
});
281
```
282

283
### Integration with External Tools
284

285
WebpackBar profiling data can be integrated with external performance analysis tools.
286

287
```javascript
288
// Export profiling data
289
class DataExporter {
290
  constructor() {
291
    this.buildData = [];
292
  }
293

294
  done(context) {
295
    const buildInfo = {
296
      name: context.state.name,
297
      duration: context.state.start ? 
298
        process.hrtime(context.state.start) : null,
299
      hasErrors: context.state.hasErrors,
300
      timestamp: Date.now(),
301
      progress: context.state.progress
302
    };
303

304
    this.buildData.push(buildInfo);
305
    
306
    // Export to JSON for analysis
307
    if (!context.hasRunning) {
308
      require('fs').writeFileSync(
309
        'build-metrics.json', 
310
        JSON.stringify(this.buildData, null, 2)
311
      );
312
    }
313
  }
314
}
315
```