0
# WebpackBar
1

2
WebpackBar is an elegant progress bar and profiler plugin for Webpack and Rspack build tools. It provides real-time build progress visualization with customizable progress bars, supports multiple concurrent builds (useful for SSR scenarios), includes advanced build profiling capabilities, and offers a fully customizable reporting system.
3

4
## Package Information
5

6
- **Package Name**: webpackbar
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install webpackbar`
10

11
## Core Imports
12

13
```javascript
14
// Webpack usage
15
import WebpackBar from "webpackbar";
16
```
17

18
```javascript
19
// Rspack usage
20
import WebpackBar from "webpackbar/rspack";
21
```
22

23
For CommonJS:
24

25
```javascript
26
// Webpack usage
27
const WebpackBar = require("webpackbar");
28

29
// Rspack usage
30
const WebpackBar = require("webpackbar/rspack");
31
```
32

33
Type imports:
34

35
```typescript
36
import type { WebpackBarOptions, Reporter, State } from "webpackbar";
37
// or
38
import type { WebpackBarOptions, Reporter, State } from "webpackbar/rspack";
39
```
40

41
## Basic Usage
42

43
```javascript
44
// Webpack configuration
45
import WebpackBar from "webpackbar";
46

47
export default {
48
  // ... your webpack config
49
  plugins: [
50
    new WebpackBar({
51
      name: 'My App',
52
      color: 'blue',
53
      profile: true
54
    })
55
  ]
56
};
57
```
58

59
```javascript
60
// Rspack configuration
61
import WebpackBar from "webpackbar/rspack";
62

63
export default {
64
  // ... your rspack config
65
  plugins: [
66
    new WebpackBar({
67
      name: 'My App',
68
      color: 'blue',
69
      profile: true
70
    })
71
  ]
72
};
73
```
74

75
## Architecture
76

77
WebpackBar is built around several key components:
78

79
- **Plugin Entry Points**: Separate integrations for Webpack (`webpackbar`) and Rspack (`webpackbar/rspack`)
80
- **Core Plugin**: `WebpackBar` class that manages state and reporters
81
- **Reporter System**: Pluggable architecture for different progress display formats
82
- **State Management**: Global state tracking for multiple concurrent builds
83
- **Profiling System**: Performance analysis and timing measurements
84

85
## Capabilities
86

87
### Plugin Integration
88

89
Core plugin classes for integrating with Webpack and Rspack build processes.
90

91
```typescript { .api }
92
import type webpack from "webpack";
93
import type * as rspack from "@rspack/core";
94

95
// Webpack integration
96
export default class WebpackBarProgressPlugin extends webpack.ProgressPlugin {
97
  webpackbar: WebpackBar;
98
  constructor(options?: WebpackBarOptions);
99
  apply(compiler: webpack.Compiler): void;
100
}
101

102
// Rspack integration  
103
export default class WebpackBarProgressPlugin extends rspack.ProgressPlugin {
104
  webpackbar: WebpackBar;
105
  constructor(options?: WebpackBarOptions);
106
  apply(compiler: rspack.Compiler): void;
107
}
108
```
109

110
### Core Plugin Class
111

112
The main WebpackBar class that manages state and reporters.
113

114
```typescript { .api }
115
import type webpack from "webpack";
116

117
export declare class WebpackBar {
118
  // State properties
119
  readonly hasRunning: boolean;          // Whether any compilation is running
120
  readonly hasErrors: boolean;           // Whether any compilation has errors
121
  readonly statesArray: State[];         // Array of all compilation states
122
  readonly states: { [key: string]: State }; // Global states object
123
  readonly state: State;                 // Current state for this plugin instance
124
  
125
  constructor(options?: WebpackBarOptions);
126
  apply(compiler: webpack.Compiler): void;
127
  updateProgress(percent?: number, message?: string, details?: string[]): void;
128
}
129
```
130

131
### Configuration Options
132

133
Comprehensive configuration system for customizing progress display and behavior.
134

135
```typescript { .api }
136
interface WebpackBarOptions {
137
  name?: string;          // Display name (default: 'build')
138
  color?: string;         // Progress bar color (default: 'green')
139
  profile?: boolean;      // Enable profiler (default: false)
140
  fancy?: boolean;        // Enable bars reporter (default: true when not in CI)
141
  basic?: boolean;        // Enable simple log reporter (default: true in minimal envs)
142
  reporter?: ReporterInput;   // Single custom reporter
143
  reporters?: ReporterInput[]; // Array of custom reporters
144
}
145
```
146

147
[Configuration Options](./configuration.md)
148

149
### Reporter System
150

151
Built-in reporters and custom reporter interfaces for displaying build progress in different formats.
152

153
```typescript { .api }
154
import type webpack from "webpack";
155

156
interface Reporter {
157
  start?(context: WebpackBar): void;
158
  change?(context: WebpackBar, payload: { path: string; shortPath: string; time: number }): void;
159
  update?(context: WebpackBar): void;
160
  done?(context: WebpackBar, payload: { stats: webpack.Stats }): void;
161
  progress?(context: WebpackBar): void;
162
  allDone?(context: WebpackBar): void;
163
  beforeAllDone?(context: WebpackBar): void;
164
  afterAllDone?(context: WebpackBar): void;
165
}
166

167
// WebpackBar class that serves as the context for reporters
168
declare class WebpackBar {
169
  readonly hasRunning: boolean;          // Whether any compilation is running
170
  readonly hasErrors: boolean;           // Whether any compilation has errors
171
  readonly statesArray: State[];         // Array of all compilation states
172
  readonly states: { [key: string]: State }; // Global states object
173
  readonly state: State;                 // Current state for this plugin instance
174
  
175
  constructor(options?: WebpackBarOptions);
176
  apply(compiler: webpack.Compiler): void;
177
  updateProgress(percent?: number, message?: string, details?: string[]): void;
178
}
179
```
180

181
[Reporter System](./reporters.md)
182

183
### Performance Profiling
184

185
Built-in profiling system for analyzing build performance and identifying bottlenecks.
186

187
```typescript { .api }
188
interface State {
189
  start: [number, number] | null;     // High-resolution start time
190
  progress: number;                   // Progress percentage (-1 to 100)
191
  done: boolean;                      // Compilation completion status
192
  message: string;                    // Current status message
193
  details: string[];                  // Additional status details
194
  request: null | {                   // Current processing request
195
    file: null | string;
196
    loaders: string[];
197
  };
198
  hasErrors: boolean;                 // Error status
199
  color: string;                      // Associated color
200
  name: string;                       // Display name
201
}
202
```
203

204
[Performance Profiling](./profiling.md)
205

206
## Types
207

208
```typescript { .api }
209
type ReporterOpts = { reporter: Reporter | string; options?: any };
210
type ReporterInput = string | [Reporter | string, any?] | ReporterOpts;
211

212
// Re-exported from main entry points
213
export { WebpackBarOptions, Reporter, State } from "webpackbar";
214
export { WebpackBarOptions, Reporter, State } from "webpackbar/rspack";
215
```