0
# React Error Overlay
1

2
React Error Overlay is a development-only error reporting system for React applications. It displays formatted runtime errors and compilation errors in an iframe-based overlay with syntax highlighting, source code context, and clickable stack frames that can open files in editors. The library provides error deduplication, automatic error listening, and seamless integration with Create React App's development workflow.
3

4
## Package Information
5

6
- **Package Name**: react-error-overlay
7
- **Package Type**: npm
8
- **Language**: JavaScript (with Flow types)
9
- **Installation**: `npm install react-error-overlay`
10
- **Environment**: Development only (warnings if used in production)
11

12
## Core Imports
13

14
```javascript
15
import {
16
  startReportingRuntimeErrors,
17
  stopReportingRuntimeErrors,
18
  reportBuildError,
19
  reportRuntimeError,
20
  dismissBuildError,
21
  dismissRuntimeErrors,
22
  setEditorHandler
23
} from "react-error-overlay";
24
```
25

26
For CommonJS:
27

28
```javascript
29
const {
30
  startReportingRuntimeErrors,
31
  stopReportingRuntimeErrors,
32
  reportBuildError,
33
  reportRuntimeError,
34
  dismissBuildError,
35
  dismissRuntimeErrors,
36
  setEditorHandler
37
} = require("react-error-overlay");
38
```
39

40
## Basic Usage
41

42
```javascript
43
import { 
44
  startReportingRuntimeErrors, 
45
  stopReportingRuntimeErrors,
46
  setEditorHandler 
47
} from "react-error-overlay";
48

49
// Start automatic error reporting in development mode
50
if (process.env.NODE_ENV === 'development') {
51
  startReportingRuntimeErrors({
52
    onError: () => {
53
      console.log('Error detected and displayed in overlay');
54
    }
55
  });
56

57
  // Set up editor integration (optional)
58
  setEditorHandler((errorLocation) => {
59
    // Open file in editor at specific location
60
    fetch('/__open-stack-frame-in-editor', {
61
      method: 'POST',
62
      headers: { 'Content-Type': 'application/json' },
63
      body: JSON.stringify(errorLocation)
64
    });
65
  });
66
}
67

68
// Later: stop error reporting when switching modes
69
// stopReportingRuntimeErrors();
70
```
71

72
## Architecture
73

74
React Error Overlay consists of several key components:
75

76
- **Error Reporting System**: Core functions for starting/stopping error monitoring and manually reporting errors
77
- **Overlay Management**: iframe-based overlay that displays errors with formatted stack traces and source context
78
- **Editor Integration**: Configurable handlers for opening files in editors when stack frames are clicked
79
- **Error Processing**: Stack frame parsing with source mapping support and error deduplication
80
- **Global Hooks**: Browser-level error listeners for unhandled exceptions and promise rejections
81

82
## Capabilities
83

84
### Error Reporting
85

86
Core error reporting functionality for both automatic monitoring and manual error reporting. Handles runtime errors, build errors, and provides error deduplication.
87

88
```javascript { .api }
89
function startReportingRuntimeErrors(options: RuntimeReportingOptions): void;
90
function stopReportingRuntimeErrors(): void;
91
function reportRuntimeError(error: Error, options?: RuntimeReportingOptions): void;
92
function reportBuildError(error: string): void;
93

94
interface RuntimeReportingOptions {
95
  onError: () => void;
96
  filename?: string;
97
  /** @deprecated launchEditorEndpoint is no longer supported. Use setEditorHandler instead. */
98
  launchEditorEndpoint?: string;
99
}
100
```
101

102
[Error Reporting](./error-reporting.md)
103

104
### Error Dismissal
105

106
Functions for clearing and dismissing errors from the overlay interface.
107

108
```javascript { .api }
109
function dismissRuntimeErrors(): void;
110
function dismissBuildError(): void;
111
```
112

113
[Error Dismissal](./error-dismissal.md)
114

115
### Editor Integration
116

117
Integration with code editors to enable opening files at specific locations when stack frames are clicked.
118

119
```javascript { .api }
120
function setEditorHandler(handler: EditorHandler | null): void;
121

122
type EditorHandler = (errorLoc: ErrorLocation) => void;
123

124
interface ErrorLocation {
125
  fileName: string;
126
  lineNumber: number;
127
  colNumber?: number;
128
}
129
```
130

131
[Editor Integration](./editor-integration.md)
132

133

134
## Types
135

136
```javascript { .api }
137
interface RuntimeReportingOptions {
138
  onError: () => void;
139
  filename?: string;
140
  /** @deprecated launchEditorEndpoint is no longer supported. Use setEditorHandler instead. */
141
  launchEditorEndpoint?: string;
142
}
143

144
type EditorHandler = (errorLoc: ErrorLocation) => void;
145

146
interface ErrorLocation {
147
  fileName: string;
148
  lineNumber: number;
149
  colNumber?: number;
150
}
151
```