CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-pmmmwh--react-refresh-webpack-plugin

Webpack plugin to enable React Fast Refresh (Hot Reloading) for React components during development

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

error-overlay.mddocs/

Error Overlay

The error overlay system provides a rich development experience by displaying compilation and runtime errors directly in the browser with detailed stack traces and formatting.

Capabilities

Error Overlay Options

Configuration interface for customizing error overlay behavior.

interface ErrorOverlayOptions {
  /**
   * Path to a JS file that sets up the error overlay integration.
   */
  entry?: string | false;
  
  /**
   * The error overlay module to use.
   */
  module?: string | false;
  
  /**
   * Path to a JS file that sets up the Webpack socket integration.
   */
  sockIntegration?: 'wds' | 'whm' | 'wps' | false | string;
}

Default Configuration:

{
  entry: '@pmmmwh/react-refresh-webpack-plugin/client/ErrorOverlayEntry',
  module: '@pmmmwh/react-refresh-webpack-plugin/overlay',
  sockIntegration: 'wds'
}

Entry Option

Controls the error overlay entry point integration.

entry?: string | false;

Usage Examples:

// Use default entry
new ReactRefreshPlugin({
  overlay: {
    entry: '@pmmmwh/react-refresh-webpack-plugin/client/ErrorOverlayEntry'
  }
});

// Use custom entry point
new ReactRefreshPlugin({
  overlay: {
    entry: './src/custom-overlay-entry.js'
  }
});

// Disable entry injection
new ReactRefreshPlugin({
  overlay: {
    entry: false
  }
});

Default: '@pmmmwh/react-refresh-webpack-plugin/client/ErrorOverlayEntry'

Module Option

Specifies the error overlay module that handles error display and clearing.

module?: string | false;

Required Module Exports:

/**
 * Handle runtime errors during module execution
 * @param {Error} error - The runtime error that occurred
 */
function handleRuntimeError(error: Error): void;

/**
 * Clear runtime errors when module is re-initialized
 */
function clearRuntimeErrors(): void;

/**
 * Show compilation error from Webpack (when using default entry)
 * @param {string} webpackErrorMessage - Webpack error message (may be ANSI encoded)
 */
function showCompileError(webpackErrorMessage: string): void;

/**
 * Clear compilation error when new compilation starts (when using default entry)
 */
function clearCompileError(): void;

Usage Examples:

// Use built-in overlay module
new ReactRefreshPlugin({
  overlay: {
    module: '@pmmmwh/react-refresh-webpack-plugin/overlay'
  }
});

// Use react-error-overlay with interop
new ReactRefreshPlugin({
  overlay: {
    module: 'react-dev-utils/refreshOverlayInterop'
  }
});

// Use custom overlay module
new ReactRefreshPlugin({
  overlay: {
    module: './src/custom-error-overlay.js'
  }
});

// Disable overlay module
new ReactRefreshPlugin({
  overlay: {
    module: false
  }
});

Default: '@pmmmwh/react-refresh-webpack-plugin/overlay'

Socket Integration

Configures communication with development servers for error reporting.

sockIntegration?: 'wds' | 'whm' | 'wps' | false | string;

Built-in Integrations:

type SocketIntegration = 
  | 'wds'    // webpack-dev-server
  | 'whm'    // webpack-hot-middleware
  | 'wps'    // webpack-plugin-serve
  | false    // disable socket integration
  | string;  // custom integration module path

Usage Examples:

// webpack-dev-server (default)
new ReactRefreshPlugin({
  overlay: {
    sockIntegration: 'wds'
  }
});

// webpack-hot-middleware
new ReactRefreshPlugin({
  overlay: {
    sockIntegration: 'whm'
  }
});

// webpack-plugin-serve
new ReactRefreshPlugin({
  overlay: {
    sockIntegration: 'wps'
  }
});

// Custom integration
new ReactRefreshPlugin({
  overlay: {
    sockIntegration: './src/custom-socket-integration.js'
  }
});

// Disable socket integration
new ReactRefreshPlugin({
  overlay: {
    sockIntegration: false
  }
});

Default: 'wds'

Normalized Error Overlay Options

Internal interface representing processed overlay options.

interface NormalizedErrorOverlayOptions {
  entry: string | false;
  module: string | false;
  sockIntegration: string | false;
}

Built-in Overlay Components

The default overlay module includes several React components for error display:

Component Structure:

  • CompileErrorContainer: Container for compilation errors
  • RuntimeErrorContainer: Container for runtime errors
  • CompileErrorTrace: Displays compilation error stack traces
  • RuntimeErrorStack: Displays runtime error stack traces
  • RuntimeErrorHeader: Header information for runtime errors
  • RuntimeErrorFooter: Footer actions for runtime errors
  • PageHeader: Main page header with branding
  • Spacer: Layout spacing component

Overlay Theming

The built-in overlay includes theming support:

// overlay/theme.js
const theme = {
  colors: {
    background: '#1d1f21',
    text: '#ffffff',
    error: '#ff6b6b',
    warning: '#ffa500'
  },
  fonts: {
    monospace: 'Menlo, Consolas, monospace'
  }
};

Overlay Utilities

Utility functions for error processing and display:

// overlay/utils.js - Error processing utilities
function formatStackTrace(error: Error): string[];
function parseWebpackErrors(errors: string[]): ParsedError[];
function highlightSyntaxErrors(code: string): string;

Client Entry Points

Pre-built client entry points for different integration scenarios:

ReactRefreshEntry:

// client/ReactRefreshEntry.js
// Sets up React Refresh runtime and error handling

ErrorOverlayEntry:

// client/ErrorOverlayEntry.js  
// Integrates error overlay with webpack compilation events

Client Utilities

Helper utilities for client-side error handling:

// client/utils/errorEventHandlers.js
function handleUnhandledRejection(event: PromiseRejectionEvent): void;
function handleError(event: ErrorEvent): void;

// client/utils/formatWebpackErrors.js
function formatWebpackErrors(errors: string[]): FormattedError[];

// client/utils/retry.js
function retry<T>(fn: () => Promise<T>, attempts: number): Promise<T>;

Custom Overlay Implementation

To create a custom error overlay module:

// custom-overlay.js
function handleRuntimeError(error) {
  console.error('Runtime Error:', error);
  // Custom error display logic
}

function clearRuntimeErrors() {
  // Custom error clearing logic
}

function showCompileError(message) {
  console.error('Compile Error:', message);
  // Custom compile error display
}

function clearCompileError() {
  // Custom compile error clearing
}

module.exports = {
  handleRuntimeError,
  clearRuntimeErrors,
  showCompileError,
  clearCompileError
};

Disabling Overlay

To completely disable error overlay functionality:

// Disable overlay entirely
new ReactRefreshPlugin({
  overlay: false
});

// Disable specific parts
new ReactRefreshPlugin({
  overlay: {
    entry: false,
    module: false,
    sockIntegration: false
  }
});

When disabled, the plugin defines stub modules to prevent runtime errors:

  • __react_refresh_error_overlay__: false
  • __react_refresh_socket__: false

Install with Tessl CLI

npx tessl i tessl/npm-pmmmwh--react-refresh-webpack-plugin

docs

client-utilities.md

error-overlay.md

index.md

loader-configuration.md

plugin-configuration.md

plugin-utilities.md

runtime-utilities.md

socket-integrations.md

tile.json