0
# Reporter System
1

2
WebpackBar provides a flexible reporter system with built-in reporters and support for custom reporters. Reporters control how build progress and completion information is displayed.
3

4
## Capabilities
5

6
### Reporter Interface
7

8
All reporters implement the Reporter interface with optional lifecycle methods.
9

10
```typescript { .api }
11
import type webpack from "webpack";
12

13
interface Reporter {
14
  /**
15
   * Called when (re)compile is started
16
   */
17
  start?(context: WebpackBar): void;
18

19
  /**
20
   * Called when a file changed on watch mode
21
   */
22
  change?(context: WebpackBar, payload: { path: string; shortPath: string; time: number }): void;
23

24
  /**
25
   * Called after each progress update
26
   */
27
  update?(context: WebpackBar): void;
28

29
  /**
30
   * Called when compile finished
31
   */
32
  done?(context: WebpackBar, payload: { stats: webpack.Stats }): void;
33

34
  /**
35
   * Called when build progress updated
36
   */
37
  progress?(context: WebpackBar): void;
38

39
  /**
40
   * Called when all compiles finished
41
   */
42
  allDone?(context: WebpackBar): void;
43

44
  /**
45
   * Called before all compiles finished
46
   */
47
  beforeAllDone?(context: WebpackBar): void;
48

49
  /**
50
   * Called after all compiles finished
51
   */
52
  afterAllDone?(context: WebpackBar): void;
53
}
54
```
55

56
### Built-in Reporters
57

58
WebpackBar includes several built-in reporters for different use cases.
59

60
#### Basic Reporter
61

62
Simple log-based reporter for minimal environments and CI systems.
63

64
```typescript { .api }
65
class SimpleReporter implements Reporter {
66
  start(context: WebpackBar): void;
67
  change(context: WebpackBar, payload: { path: string; shortPath: string; time: number }): void;
68
  done(context: WebpackBar): void;
69
}
70
```
71

72
**Features:**
73
- Logs compilation start with build name
74
- Logs file changes in watch mode
75
- Logs final status (success/error) with completion message
76
- Ideal for CI/CD environments and minimal terminal displays
77

78
**Usage:**
79

80
```javascript
81
new WebpackBar({
82
  reporters: ['basic']
83
});
84
```
85

86
#### Fancy Reporter
87

88
Advanced progress bar reporter with real-time visual updates.
89

90
```typescript { .api }
91
class FancyReporter implements Reporter {
92
  progress(context: WebpackBar): void;
93
  done(context: WebpackBar): void;
94
  allDone(): void;
95
}
96
```
97

98
**Features:**
99
- Real-time progress bars with percentage indicators
100
- Color-coded status indicators (running, completed, error)
101
- Module-level progress details
102
- File processing information
103
- Throttled updates (50ms intervals) for performance
104

105
**Usage:**
106

107
```javascript
108
new WebpackBar({
109
  reporters: ['fancy']
110
});
111
```
112

113
#### Profile Reporter
114

115
Performance profiling reporter for build analysis and optimization.
116

117
```typescript { .api }
118
class ProfileReporter implements Reporter {
119
  progress(context: WebpackBar): void;
120
  done(context: WebpackBar): void;
121
  allDone(context: WebpackBar): void;
122
}
123
```
124

125
**Features:**
126
- Tracks request timing and performance metrics
127
- Generates detailed profiling statistics
128
- Formats and outputs performance analysis
129
- Identifies build bottlenecks and slow modules
130

131
**Usage:**
132

133
```javascript
134
new WebpackBar({
135
  profile: true  // Automatically adds profile reporter
136
});
137

138
// Or explicitly
139
new WebpackBar({
140
  reporters: ['profile']
141
});
142
```
143

144
#### Stats Reporter
145

146
Statistical analysis reporter for detailed build metrics.
147

148
```typescript { .api }
149
class StatsReporter implements Reporter {
150
  // Implementation details in src/reporters/stats.ts
151
}
152
```
153

154
**Usage:**
155

156
```javascript
157
new WebpackBar({
158
  reporters: ['stats']
159
});
160
```
161

162
### Custom Reporters
163

164
Create custom reporters by implementing the Reporter interface.
165

166
**Simple Custom Reporter:**
167

168
```javascript
169
class CustomReporter {
170
  start(context) {
171
    console.log(`🚀 Starting ${context.state.name} build...`);
172
  }
173

174
  progress(context) {
175
    const { progress, message } = context.state;
176
    if (progress % 10 === 0) {  // Log every 10%
177
      console.log(`⚡ ${context.state.name}: ${progress}% - ${message}`);
178
    }
179
  }
180

181
  done(context) {
182
    const { hasErrors, message, name } = context.state;
183
    const emoji = hasErrors ? '❌' : '✅';
184
    console.log(`${emoji} ${name}: ${message}`);
185
  }
186
}
187

188
// Usage
189
new WebpackBar({
190
  reporter: CustomReporter
191
});
192
```
193

194
**Advanced Custom Reporter with Options:**
195

196
```javascript
197
class AdvancedReporter {
198
  constructor(options = {}) {
199
    this.options = {
200
      logLevel: 'info',
201
      showTimestamps: false,
202
      ...options
203
    };
204
  }
205

206
  start(context) {
207
    if (this.options.logLevel === 'verbose') {
208
      const timestamp = this.options.showTimestamps ? new Date().toISOString() : '';
209
      console.log(`${timestamp} Build started: ${context.state.name}`);
210
    }
211
  }
212

213
  done(context) {
214
    const { stats } = context.state;
215
    if (this.options.logLevel === 'verbose' && stats) {
216
      console.log(`Build time: ${stats.compilation.endTime - stats.compilation.startTime}ms`);
217
      console.log(`Modules: ${stats.compilation.modules.size}`);
218
    }
219
  }
220
}
221

222
// Usage
223
new WebpackBar({
224
  reporter: [AdvancedReporter, {
225
    logLevel: 'verbose',
226
    showTimestamps: true
227
  }]
228
});
229
```
230

231
### Reporter Configuration Types
232

233
```typescript { .api }
234
type ReporterOpts = { 
235
  reporter: Reporter | string; 
236
  options?: any 
237
};
238

239
type ReporterInput = string | [Reporter | string, any?] | ReporterOpts;
240
```
241

242
**Configuration Examples:**
243

244
```javascript
245
// String-based reporter
246
new WebpackBar({
247
  reporters: ['basic', 'fancy']
248
});
249

250
// Array format with options
251
new WebpackBar({
252
  reporters: [
253
    'basic',
254
    ['profile', { detailed: true }]
255
  ]
256
});
257

258
// Object format
259
new WebpackBar({
260
  reporters: [
261
    { reporter: 'basic' },
262
    { reporter: CustomReporter, options: { verbose: true } }
263
  ]
264
});
265

266
// Mixed formats
267
new WebpackBar({
268
  reporters: [
269
    'basic',
270
    ['fancy', { throttle: 100 }],
271
    { reporter: CustomReporter, options: { logFile: 'build.log' } }
272
  ]
273
});
274
```
275

276
### Reporter Context
277

278
All reporter methods receive a WebpackBar context object providing access to build state and utilities.
279

280
```typescript { .api }
281
import type webpack from "webpack";
282

283
declare class WebpackBar {
284
  // State properties
285
  readonly hasRunning: boolean;      // Whether any compilation is running
286
  readonly hasErrors: boolean;       // Whether any compilation has errors
287
  readonly statesArray: State[];     // Array of all compilation states
288
  readonly states: { [key: string]: State };  // Global states object
289
  readonly state: State;             // Current state for this plugin instance
290
  
291
  constructor(options?: WebpackBarOptions);
292
  apply(compiler: webpack.Compiler): void;
293
  updateProgress(percent?: number, message?: string, details?: string[]): void;
294
}
295
```