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

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Next.js React Development Overlay

Name: tessl/npm-next--react-dev-overlay
Author: tessl

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