0
# Client Error Handling
1

2
Client-side error handling and overlay functionality for React applications, providing comprehensive error capture and display capabilities.
3

4
## Capabilities
5

6
### Error Handler Registration
7

8
Register and unregister global error handlers for capturing unhandled errors and promise rejections.
9

10
```typescript { .api }
11
/**
12
 * Registers global error handlers for unhandled errors and promise rejections
13
 * Sets Error.stackTraceLimit to 50 for detailed stack traces
14
 */
15
function register(): void;
16

17
/**
18
 * Unregisters global error handlers and restores original Error.stackTraceLimit
19
 */
20
function unregister(): void;
21
```
22

23
**Usage Examples:**
24

25
```typescript
26
import { register, unregister } from "@next/react-dev-overlay";
27

28
// Register error handlers when starting development
29
register();
30

31
// Unregister when shutting down (optional, usually not needed)
32
unregister();
33
```
34

35
### ReactDevOverlay Component
36

37
Main React component that provides the development overlay interface for displaying errors and build status.
38

39
```typescript { .api }
40
/**
41
 * Main React component for the development overlay
42
 * Renders error displays, build status, and development tools
43
 */
44
const ReactDevOverlay: React.ComponentType<ReactDevOverlayProps>;
45

46
interface ReactDevOverlayProps {
47
  /** Child components to render */
48
  children?: React.ReactNode;
49
  /** Array of error types to prevent from displaying */
50
  preventDisplay?: ErrorType[];
51
  /** Whether to show overlay globally across the application */
52
  globalOverlay?: boolean;
53
}
54

55
type ErrorType = 'runtime' | 'build';
56
```
57

58
**Usage Examples:**
59

60
```typescript
61
import { ReactDevOverlay } from "@next/react-dev-overlay";
62
import React from "react";
63

64
// Basic usage
65
function App() {
66
  return (
67
    <ReactDevOverlay>
68
      <MyApplication />
69
    </ReactDevOverlay>
70
  );
71
}
72

73
// Prevent certain error types from displaying
74
function ProductionApp() {
75
  return (
76
    <ReactDevOverlay preventDisplay={['runtime']}>
77
      <MyApplication />
78
    </ReactDevOverlay>
79
  );
80
}
81

82
// Global overlay configuration
83
function GlobalOverlayApp() {
84
  return (
85
    <ReactDevOverlay globalOverlay={true}>
86
      <MyApplication />
87
    </ReactDevOverlay>
88
  );
89
}
90
```
91

92
### Error Processing Utilities
93

94
Utilities for processing and formatting different types of errors with full type information.
95

96
```typescript { .api }
97
/**
98
 * Processes and formats errors by type, returning structured error objects
99
 * @param ev - Error event with ID and event data
100
 * @returns Promise resolving to formatted runtime error
101
 */
102
function getErrorByType(ev: SupportedErrorEvent): Promise<ReadyRuntimeError>;
103

104
/**
105
 * Creates server errors with proper stack traces and context
106
 * @param error - Original error object
107
 * @param type - Type of error context ('server' | 'edge-server' | null)
108
 * @returns Enhanced error object with server context
109
 */
110
function getServerError(error: Error, type: ErrorType): Error;
111

112
interface SupportedErrorEvent {
113
  id: number;
114
  event: BusEvent;
115
}
116

117
interface ReadyRuntimeError {
118
  id: number;
119
  runtime: true;
120
  error: Error;
121
  frames: OriginalStackFrame[];
122
  componentStack?: string[];
123
}
124

125
interface BusEvent {
126
  type: string;
127
  reason?: Error;
128
  message?: string;
129
  frames?: StackFrame[];
130
  componentStack?: string[];
131
}
132
```
133

134
**Usage Examples:**
135

136
```typescript
137
import { getErrorByType, getServerError } from "@next/react-dev-overlay";
138

139
// Process error events
140
async function handleError(errorEvent: SupportedErrorEvent) {
141
  const processedError = await getErrorByType(errorEvent);
142
  console.log('Processed error:', processedError);
143
}
144

145
// Create server error
146
function createServerError(originalError: Error) {
147
  const serverError = getServerError(originalError, 'server');
148
  return serverError;
149
}
150
```
151

152
### Error Types
153

154
Core type definitions for error handling and processing.
155

156
```typescript { .api }
157
type OriginalStackFrame = 
158
  | OriginalStackFrameError 
159
  | OriginalStackFrameExternal 
160
  | OriginalStackFrameInternal;
161

162
interface OriginalStackFrameError {
163
  error: true;
164
  reason: string;
165
  external: false;
166
  expanded: false;
167
  sourceStackFrame: StackFrame;
168
}
169

170
interface OriginalStackFrameExternal {
171
  error: false;
172
  external: true;
173
  expanded: boolean;
174
  sourceStackFrame: StackFrame;
175
}
176

177
interface OriginalStackFrameInternal {
178
  error: false;
179
  reason: null;
180
  external: false;
181
  expanded: boolean;
182
  sourceStackFrame: StackFrame;
183
  originalCodeFrame: string | null;
184
  originalStackFrame: StackFrame;
185
}
186

187
interface StackFrame {
188
  file: string | null;
189
  methodName: string | null;  
190
  arguments: string[];
191
  lineNumber: number | null;
192
  column: number | null;
193
}
194
```