0
# Error Overlay
1

2
The error overlay system provides a rich development experience by displaying compilation and runtime errors directly in the browser with detailed stack traces and formatting.
3

4
## Capabilities
5

6
### Error Overlay Options
7

8
Configuration interface for customizing error overlay behavior.
9

10
```javascript { .api }
11
interface ErrorOverlayOptions {
12
  /**
13
   * Path to a JS file that sets up the error overlay integration.
14
   */
15
  entry?: string | false;
16
  
17
  /**
18
   * The error overlay module to use.
19
   */
20
  module?: string | false;
21
  
22
  /**
23
   * Path to a JS file that sets up the Webpack socket integration.
24
   */
25
  sockIntegration?: 'wds' | 'whm' | 'wps' | false | string;
26
}
27
```
28

29
**Default Configuration:**
30
```javascript
31
{
32
  entry: '@pmmmwh/react-refresh-webpack-plugin/client/ErrorOverlayEntry',
33
  module: '@pmmmwh/react-refresh-webpack-plugin/overlay',
34
  sockIntegration: 'wds'
35
}
36
```
37

38
### Entry Option
39

40
Controls the error overlay entry point integration.
41

42
```javascript { .api }
43
entry?: string | false;
44
```
45

46
**Usage Examples:**
47

48
```javascript
49
// Use default entry
50
new ReactRefreshPlugin({
51
  overlay: {
52
    entry: '@pmmmwh/react-refresh-webpack-plugin/client/ErrorOverlayEntry'
53
  }
54
});
55

56
// Use custom entry point
57
new ReactRefreshPlugin({
58
  overlay: {
59
    entry: './src/custom-overlay-entry.js'
60
  }
61
});
62

63
// Disable entry injection
64
new ReactRefreshPlugin({
65
  overlay: {
66
    entry: false
67
  }
68
});
69
```
70

71
**Default:** `'@pmmmwh/react-refresh-webpack-plugin/client/ErrorOverlayEntry'`
72

73
### Module Option
74

75
Specifies the error overlay module that handles error display and clearing.
76

77
```javascript { .api }
78
module?: string | false;
79
```
80

81
**Required Module Exports:**
82

83
```javascript { .api }
84
/**
85
 * Handle runtime errors during module execution
86
 * @param {Error} error - The runtime error that occurred
87
 */
88
function handleRuntimeError(error: Error): void;
89

90
/**
91
 * Clear runtime errors when module is re-initialized
92
 */
93
function clearRuntimeErrors(): void;
94

95
/**
96
 * Show compilation error from Webpack (when using default entry)
97
 * @param {string} webpackErrorMessage - Webpack error message (may be ANSI encoded)
98
 */
99
function showCompileError(webpackErrorMessage: string): void;
100

101
/**
102
 * Clear compilation error when new compilation starts (when using default entry)
103
 */
104
function clearCompileError(): void;
105
```
106

107
**Usage Examples:**
108

109
```javascript
110
// Use built-in overlay module
111
new ReactRefreshPlugin({
112
  overlay: {
113
    module: '@pmmmwh/react-refresh-webpack-plugin/overlay'
114
  }
115
});
116

117
// Use react-error-overlay with interop
118
new ReactRefreshPlugin({
119
  overlay: {
120
    module: 'react-dev-utils/refreshOverlayInterop'
121
  }
122
});
123

124
// Use custom overlay module
125
new ReactRefreshPlugin({
126
  overlay: {
127
    module: './src/custom-error-overlay.js'
128
  }
129
});
130

131
// Disable overlay module
132
new ReactRefreshPlugin({
133
  overlay: {
134
    module: false
135
  }
136
});
137
```
138

139
**Default:** `'@pmmmwh/react-refresh-webpack-plugin/overlay'`
140

141
### Socket Integration
142

143
Configures communication with development servers for error reporting.
144

145
```javascript { .api }
146
sockIntegration?: 'wds' | 'whm' | 'wps' | false | string;
147
```
148

149
**Built-in Integrations:**
150

151
```javascript { .api }
152
type SocketIntegration = 
153
  | 'wds'    // webpack-dev-server
154
  | 'whm'    // webpack-hot-middleware
155
  | 'wps'    // webpack-plugin-serve
156
  | false    // disable socket integration
157
  | string;  // custom integration module path
158
```
159

160
**Usage Examples:**
161

162
```javascript
163
// webpack-dev-server (default)
164
new ReactRefreshPlugin({
165
  overlay: {
166
    sockIntegration: 'wds'
167
  }
168
});
169

170
// webpack-hot-middleware
171
new ReactRefreshPlugin({
172
  overlay: {
173
    sockIntegration: 'whm'
174
  }
175
});
176

177
// webpack-plugin-serve
178
new ReactRefreshPlugin({
179
  overlay: {
180
    sockIntegration: 'wps'
181
  }
182
});
183

184
// Custom integration
185
new ReactRefreshPlugin({
186
  overlay: {
187
    sockIntegration: './src/custom-socket-integration.js'
188
  }
189
});
190

191
// Disable socket integration
192
new ReactRefreshPlugin({
193
  overlay: {
194
    sockIntegration: false
195
  }
196
});
197
```
198

199
**Default:** `'wds'`
200

201
### Normalized Error Overlay Options
202

203
Internal interface representing processed overlay options.
204

205
```javascript { .api }
206
interface NormalizedErrorOverlayOptions {
207
  entry: string | false;
208
  module: string | false;
209
  sockIntegration: string | false;
210
}
211
```
212

213
### Built-in Overlay Components
214

215
The default overlay module includes several React components for error display:
216

217
**Component Structure:**
218
- **CompileErrorContainer**: Container for compilation errors
219
- **RuntimeErrorContainer**: Container for runtime errors
220
- **CompileErrorTrace**: Displays compilation error stack traces
221
- **RuntimeErrorStack**: Displays runtime error stack traces
222
- **RuntimeErrorHeader**: Header information for runtime errors
223
- **RuntimeErrorFooter**: Footer actions for runtime errors
224
- **PageHeader**: Main page header with branding
225
- **Spacer**: Layout spacing component
226

227
### Overlay Theming
228

229
The built-in overlay includes theming support:
230

231
```javascript { .api }
232
// overlay/theme.js
233
const theme = {
234
  colors: {
235
    background: '#1d1f21',
236
    text: '#ffffff',
237
    error: '#ff6b6b',
238
    warning: '#ffa500'
239
  },
240
  fonts: {
241
    monospace: 'Menlo, Consolas, monospace'
242
  }
243
};
244
```
245

246
### Overlay Utilities
247

248
Utility functions for error processing and display:
249

250
```javascript { .api }
251
// overlay/utils.js - Error processing utilities
252
function formatStackTrace(error: Error): string[];
253
function parseWebpackErrors(errors: string[]): ParsedError[];
254
function highlightSyntaxErrors(code: string): string;
255
```
256

257
### Client Entry Points
258

259
Pre-built client entry points for different integration scenarios:
260

261
**ReactRefreshEntry:**
262
```javascript
263
// client/ReactRefreshEntry.js
264
// Sets up React Refresh runtime and error handling
265
```
266

267
**ErrorOverlayEntry:**
268
```javascript
269
// client/ErrorOverlayEntry.js  
270
// Integrates error overlay with webpack compilation events
271
```
272

273
### Client Utilities
274

275
Helper utilities for client-side error handling:
276

277
```javascript { .api }
278
// client/utils/errorEventHandlers.js
279
function handleUnhandledRejection(event: PromiseRejectionEvent): void;
280
function handleError(event: ErrorEvent): void;
281

282
// client/utils/formatWebpackErrors.js
283
function formatWebpackErrors(errors: string[]): FormattedError[];
284

285
// client/utils/retry.js
286
function retry<T>(fn: () => Promise<T>, attempts: number): Promise<T>;
287
```
288

289
### Custom Overlay Implementation
290

291
To create a custom error overlay module:
292

293
```javascript
294
// custom-overlay.js
295
function handleRuntimeError(error) {
296
  console.error('Runtime Error:', error);
297
  // Custom error display logic
298
}
299

300
function clearRuntimeErrors() {
301
  // Custom error clearing logic
302
}
303

304
function showCompileError(message) {
305
  console.error('Compile Error:', message);
306
  // Custom compile error display
307
}
308

309
function clearCompileError() {
310
  // Custom compile error clearing
311
}
312

313
module.exports = {
314
  handleRuntimeError,
315
  clearRuntimeErrors,
316
  showCompileError,
317
  clearCompileError
318
};
319
```
320

321
### Disabling Overlay
322

323
To completely disable error overlay functionality:
324

325
```javascript
326
// Disable overlay entirely
327
new ReactRefreshPlugin({
328
  overlay: false
329
});
330

331
// Disable specific parts
332
new ReactRefreshPlugin({
333
  overlay: {
334
    entry: false,
335
    module: false,
336
    sockIntegration: false
337
  }
338
});
339
```
340

341
When disabled, the plugin defines stub modules to prevent runtime errors:
342
- `__react_refresh_error_overlay__`: `false`
343
- `__react_refresh_socket__`: `false`