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

Build Status Management

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

Build event management system for communicating build status, errors, and fast refresh events through the overlay system.

Capabilities

Build Success Events

Signal successful build completion to the overlay system.

/**
 * Emits a build success event to the overlay event bus
 * Typically called when webpack/turbopack compilation succeeds
 */
function onBuildOk(): void;

Usage Examples:

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

// Signal successful build
onBuildOk();

// In a webpack plugin or build system
class MyWebpackPlugin {
  apply(compiler) {
    compiler.hooks.done.tap('MyPlugin', (stats) => {
      if (!stats.hasErrors()) {
        onBuildOk();
      }
    });
  }
}

Build Error Events

Signal build errors and failures to the overlay system with detailed error messages.

/**
 * Emits a build error event to the overlay event bus
 * @param message - Error message describing the build failure
 */
function onBuildError(message: string): void;

Usage Examples:

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

// Signal build error with message
onBuildError("TypeScript compilation failed: Type 'string' is not assignable to type 'number'");

// In a webpack plugin
class MyWebpackPlugin {
  apply(compiler) {
    compiler.hooks.done.tap('MyPlugin', (stats) => {
      if (stats.hasErrors()) {
        const errors = stats.toJson().errors;
        onBuildError(errors[0]?.message || 'Build failed');
      }
    });
  }
}

// With detailed error information
function handleCompilationError(error: Error) {
  onBuildError(`Compilation failed: ${error.message}\n\nStack: ${error.stack}`);
}

Fast Refresh Events

Manage fast refresh lifecycle events for hot module replacement functionality.

/**
 * Emits a refresh event indicating fast refresh is occurring
 * Used to coordinate UI updates during hot module replacement
 */
function onRefresh(): void;

/**
 * Emits a before refresh event to prepare for fast refresh
 * Allows cleanup or preparation before hot module replacement
 */
function onBeforeRefresh(): void;

Usage Examples:

import { onRefresh, onBeforeRefresh } from "@next/react-dev-overlay";

// Signal before refresh event
onBeforeRefresh();

// Perform refresh
onRefresh();

// In a hot module replacement context
if (module.hot) {
  module.hot.dispose(() => {
    onBeforeRefresh();
  });
  
  module.hot.accept(() => {
    onRefresh();
  });
}

Event Bus Integration

The build status functions integrate with the internal event bus system that coordinates overlay behavior.

// Event types used internally (exported constants)
const TYPE_BUILD_OK = 'build-ok';
const TYPE_BUILD_ERROR = 'build-error';
const TYPE_REFRESH = 'fast-refresh';
const TYPE_BEFORE_REFRESH = 'before-fast-refresh';
const TYPE_UNHANDLED_ERROR = 'unhandled-error';
const TYPE_UNHANDLED_REJECTION = 'unhandled-rejection';

interface BuildOk {
  type: typeof TYPE_BUILD_OK;
}

interface BuildError {
  type: typeof TYPE_BUILD_ERROR;
  message: string;
}

interface FastRefresh {
  type: typeof TYPE_REFRESH;
}

interface BeforeFastRefresh {
  type: typeof TYPE_BEFORE_REFRESH;
}

interface UnhandledError {
  type: typeof TYPE_UNHANDLED_ERROR;
  reason: Error;
  frames: StackFrame[];
  componentStack?: string[];
}

interface UnhandledRejection {
  type: typeof TYPE_UNHANDLED_REJECTION;
  reason: Error;
  frames: StackFrame[];
}

Usage Examples:

// These constants are used internally but can be useful for event filtering
import { TYPE_BUILD_OK, TYPE_BUILD_ERROR } from "@next/react-dev-overlay/internal/bus";

// Custom event handling (advanced usage)
function handleBuildEvents() {
  // The overlay system automatically handles these events
  // This is just to show the event structure
  const buildOkEvent: BuildOk = { type: TYPE_BUILD_OK };
  const buildErrorEvent: BuildError = { 
    type: TYPE_BUILD_ERROR, 
    message: "Build failed" 
  };
}

Integration Patterns

Webpack Integration

// webpack.config.js or webpack plugin
const { onBuildOk, onBuildError } = require("@next/react-dev-overlay");

class OverlayPlugin {
  apply(compiler) {
    compiler.hooks.done.tap('OverlayPlugin', (stats) => {
      if (stats.hasErrors()) {
        const error = stats.toJson().errors[0];
        onBuildError(error?.message || 'Build failed');
      } else {
        onBuildOk();
      }
    });
  }
}

Next.js Integration

// next.config.js or Next.js plugin
const { onBuildOk, onBuildError, onRefresh, onBeforeRefresh } = require("@next/react-dev-overlay");

module.exports = {
  webpack(config, { dev, isServer }) {
    if (dev && !isServer) {
      // Add overlay integration
      config.plugins.push(
        new (class {
          apply(compiler) {
            compiler.hooks.done.tap('NextOverlay', (stats) => {
              if (stats.hasErrors()) {
                onBuildError('Next.js compilation failed');
              } else {
                onBuildOk();
              }
            });
          }
        })()
      );
    }
    return config;
  }
};