0
# Next.js React Development Overlay
1

2
@next/react-dev-overlay is a comprehensive development overlay system specifically designed for React applications during development. It provides real-time error reporting and debugging capabilities by intercepting and displaying unhandled errors, promise rejections, and build errors in an intuitive overlay interface.
3

4
## Package Information
5

6
- **Package Name**: @next/react-dev-overlay
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @next/react-dev-overlay`
10

11
## Core Imports
12

13
```typescript
14
import { ReactDevOverlay, register, unregister } from "@next/react-dev-overlay";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { ReactDevOverlay, register, unregister } = require("@next/react-dev-overlay");
21
```
22

23
Middleware imports:
24

25
```typescript
26
import { getOverlayMiddleware } from "@next/react-dev-overlay/middleware";
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { ReactDevOverlay, register } from "@next/react-dev-overlay";
33
import React from "react";
34

35
// Register error handlers
36
register();
37

38
function App() {
39
  return (
40
    <ReactDevOverlay>
41
      <YourApplication />
42
    </ReactDevOverlay>
43
  );
44
}
45

46
// Optional: emit build events
47
import { onBuildOk, onBuildError } from "@next/react-dev-overlay";
48

49
// Signal successful build
50
onBuildOk();
51

52
// Signal build error
53
onBuildError("TypeScript compilation failed");
54
```
55

56
## Architecture
57

58
The React Development Overlay is built around several key components:
59

60
- **Error Handler System**: Global error capturing for unhandled errors and promise rejections
61
- **Event Bus**: Communication system for build status updates and error notifications
62
- **Overlay Components**: React components for displaying errors, build status, and development information
63
- **Source Mapping**: Integration with webpack/turbopack for accurate error locations
64
- **Editor Integration**: Click-to-open functionality with external editors
65
- **Middleware**: Express middleware for handling overlay API requests
66

67
## Capabilities
68

69
### Client Error Handling
70

71
Core client-side error handling and overlay functionality for React applications.
72

73
```typescript { .api }
74
function register(): void;
75
function unregister(): void;
76
const ReactDevOverlay: React.ComponentType<ReactDevOverlayProps>;
77

78
interface ReactDevOverlayProps {
79
  children?: React.ReactNode;
80
  preventDisplay?: ErrorType[];
81
  globalOverlay?: boolean;
82
}
83
```
84

85
[Client Error Handling](./client-error-handling.md)
86

87
### Build Status Management
88

89
Build event management system for communicating build status and errors.
90

91
```typescript { .api }
92
function onBuildOk(): void;
93
function onBuildError(message: string): void;
94
function onRefresh(): void;
95
function onBeforeRefresh(): void;
96
```
97

98
[Build Status Management](./build-status.md)
99

100
### Webpack Middleware
101

102
Express middleware for handling overlay requests and source map processing with webpack.
103

104
```typescript { .api }
105
function getOverlayMiddleware(options: OverlayMiddlewareOptions): (req: IncomingMessage, res: ServerResponse, next: () => void) => void;
106

107
interface OverlayMiddlewareOptions {
108
  rootDirectory: string;
109
  stats(): webpack.Stats | null;
110
  serverStats(): webpack.Stats | null;
111
  edgeServerStats(): webpack.Stats | null;
112
}
113
```
114

115
[Webpack Middleware](./webpack-middleware.md)
116

117
### Turbopack Middleware
118

119
Turbopack-specific middleware for handling overlay requests with Turbopack builds.
120

121
```typescript { .api }
122
function getOverlayMiddleware(project: Project): (req: IncomingMessage, res: ServerResponse, next: () => void) => void;
123

124
interface Project {
125
  // Project interface for Turbopack operations
126
}
127
```
128

129
[Turbopack Middleware](./turbopack-middleware.md)
130

131
### Error Processing
132

133
Advanced error processing utilities for server-side error handling and stack frame analysis.
134

135
```typescript { .api }
136
function getErrorByType(ev: SupportedErrorEvent): Promise<ReadyRuntimeError>;
137
function getServerError(error: Error, type: ErrorType): Error;
138
function parseStack(stack: string): StackFrame[];
139

140
interface ReadyRuntimeError {
141
  id: number;
142
  runtime: true;
143
  error: Error;
144
  frames: OriginalStackFrame[];
145
  componentStack?: string[];
146
}
147
```
148

149
[Error Processing](./error-processing.md)
150

151
## Types
152

153
```typescript { .api }
154
type ErrorType = 'runtime' | 'build';
155

156
interface SupportedErrorEvent {
157
  id: number;
158
  event: BusEvent;
159
}
160

161
type OriginalStackFrame = OriginalStackFrameError | OriginalStackFrameExternal | OriginalStackFrameInternal;
162

163
interface OriginalStackFrameResponse {
164
  originalStackFrame: StackFrame;
165
  originalCodeFrame: string | null;
166
  sourcePackage?: string;
167
}
168

169
interface BusEvent {
170
  type: string;
171
  [key: string]: any;
172
}
173

174
type BusEventHandler = (ev: BusEvent) => void;
175
```