or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

build-status.mdclient-error-handling.mderror-processing.mdindex.mdturbopack-middleware.mdwebpack-middleware.md
tile.json

tessl/npm-next--react-dev-overlay

A development-only overlay for developing React applications with comprehensive error reporting and debugging capabilities.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@next/react-dev-overlay@14.1.x

To install, run

npx @tessl/cli install tessl/npm-next--react-dev-overlay@14.1.0

index.mddocs/

Next.js React Development Overlay

@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.

Package Information

  • Package Name: @next/react-dev-overlay
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @next/react-dev-overlay

Core Imports

import { ReactDevOverlay, register, unregister } from "@next/react-dev-overlay";

For CommonJS:

const { ReactDevOverlay, register, unregister } = require("@next/react-dev-overlay");

Middleware imports:

import { getOverlayMiddleware } from "@next/react-dev-overlay/middleware";

Basic Usage

import { ReactDevOverlay, register } from "@next/react-dev-overlay";
import React from "react";

// Register error handlers
register();

function App() {
  return (
    <ReactDevOverlay>
      <YourApplication />
    </ReactDevOverlay>
  );
}

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

// Signal successful build
onBuildOk();

// Signal build error
onBuildError("TypeScript compilation failed");

Architecture

The React Development Overlay is built around several key components:

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

Capabilities

Client Error Handling

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

function register(): void;
function unregister(): void;
const ReactDevOverlay: React.ComponentType<ReactDevOverlayProps>;

interface ReactDevOverlayProps {
  children?: React.ReactNode;
  preventDisplay?: ErrorType[];
  globalOverlay?: boolean;
}

Client Error Handling

Build Status Management

Build event management system for communicating build status and errors.

function onBuildOk(): void;
function onBuildError(message: string): void;
function onRefresh(): void;
function onBeforeRefresh(): void;

Build Status Management

Webpack Middleware

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

function getOverlayMiddleware(options: OverlayMiddlewareOptions): (req: IncomingMessage, res: ServerResponse, next: () => void) => void;

interface OverlayMiddlewareOptions {
  rootDirectory: string;
  stats(): webpack.Stats | null;
  serverStats(): webpack.Stats | null;
  edgeServerStats(): webpack.Stats | null;
}

Webpack Middleware

Turbopack Middleware

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

function getOverlayMiddleware(project: Project): (req: IncomingMessage, res: ServerResponse, next: () => void) => void;

interface Project {
  // Project interface for Turbopack operations
}

Turbopack Middleware

Error Processing

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

function getErrorByType(ev: SupportedErrorEvent): Promise<ReadyRuntimeError>;
function getServerError(error: Error, type: ErrorType): Error;
function parseStack(stack: string): StackFrame[];

interface ReadyRuntimeError {
  id: number;
  runtime: true;
  error: Error;
  frames: OriginalStackFrame[];
  componentStack?: string[];
}

Error Processing

Types

type ErrorType = 'runtime' | 'build';

interface SupportedErrorEvent {
  id: number;
  event: BusEvent;
}

type OriginalStackFrame = OriginalStackFrameError | OriginalStackFrameExternal | OriginalStackFrameInternal;

interface OriginalStackFrameResponse {
  originalStackFrame: StackFrame;
  originalCodeFrame: string | null;
  sourcePackage?: string;
}

interface BusEvent {
  type: string;
  [key: string]: any;
}

type BusEventHandler = (ev: BusEvent) => void;