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

Turbopack Middleware

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

Turbopack-specific middleware for handling overlay requests with Turbopack builds, providing optimized source map processing and error handling for Turbopack's build system.

Capabilities

Turbopack Overlay Middleware

Create Express middleware specifically designed for Turbopack build integration.

/**
 * Creates Turbopack-specific overlay middleware
 * @param project - Turbopack project interface for source operations
 * @returns Express middleware function optimized for Turbopack
 */
function getOverlayMiddleware(
  project: Project
): (req: IncomingMessage, res: ServerResponse) => Promise<void>;

interface Project {
  /** Turbopack project interface for source map and file operations */
  // Note: This is a Turbopack-internal interface
  // Exact methods depend on Turbopack version
}

Usage Examples:

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

// Assuming you have a Turbopack project instance
const turbopackProject = createTurbopackProject();

const app = express();

// Setup Turbopack overlay middleware
const overlayMiddleware = getOverlayMiddleware(turbopackProject);

// Use middleware for Turbopack-specific endpoints
app.use('/__nextjs_original-stack-frame', overlayMiddleware);

Turbopack Stack Frame Processing

Create original stack frames optimized for Turbopack's source map format and build system.

/**
 * Creates original stack frames for Turbopack builds
 * @param project - Turbopack project instance
 * @param frame - Turbopack-specific stack frame data
 * @returns Promise resolving to original stack frame information
 */
function createOriginalStackFrame(
  project: Project,
  frame: TurbopackStackFrame
): Promise<OriginalStackFrameResponse | null>;

interface TurbopackStackFrame {
  /** File path in Turbopack's module system */
  file: string;
  /** Method or function name */
  methodName: string | null;
  /** Line number in original source */
  line: number;
  /** Column number in original source */
  column: number | null;
  /** Whether this frame is from server-side code */
  isServer: boolean;
}

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

Usage Examples:

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

// Process Turbopack stack frame
async function processTurbopackError(
  project: Project, 
  stackFrame: TurbopackStackFrame
) {
  try {
    const originalFrame = await createOriginalStackFrame(project, stackFrame);
    
    console.log('Original stack frame:', originalFrame.originalStackFrame);
    console.log('Code frame:', originalFrame.originalCodeFrame);
    console.log('Source package:', originalFrame.sourcePackage);
    
    return originalFrame;
  } catch (error) {
    console.error('Failed to process Turbopack stack frame:', error);
    return null;
  }
}

// Handle multiple stack frames
async function processErrorStack(
  project: Project, 
  frames: TurbopackStackFrame[]
) {
  const processedFrames = await Promise.all(
    frames.map(frame => createOriginalStackFrame(project, frame))
  );
  
  return processedFrames.filter(frame => frame !== null);
}

Turbopack Integration Patterns

Next.js with Turbopack

// next.config.js with Turbopack
const { getOverlayMiddleware } = require("@next/react-dev-overlay/middleware-turbopack");

module.exports = {
  experimental: {
    turbo: {
      // Turbopack configuration
    },
  },
  
  // Custom server integration
  async rewrites() {
    return [
      {
        source: '/__nextjs_original-stack-frame',
        destination: '/api/overlay/stack-frame',
      },
    ];
  },
};

Custom Development Server

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

// Setup custom development server with Turbopack
async function setupDevServer() {
  const app = express();
  
  // Initialize Turbopack project (implementation specific)
  const turbopackProject = await initializeTurbopackProject({
    root: process.cwd(),
    mode: 'development',
  });
  
  // Setup overlay middleware
  const overlayMiddleware = getOverlayMiddleware(turbopackProject);
  
  // Mount middleware
  app.use('/__nextjs_original-stack-frame', overlayMiddleware);
  app.use('/__nextjs_launch-editor', overlayMiddleware);
  
  app.listen(3000, () => {
    console.log('Dev server with Turbopack overlay ready');
  });
}

Differences from Webpack Middleware

The Turbopack middleware differs from the webpack middleware in several key ways:

Source Map Handling

Turbopack uses a different source map format and provides different APIs for source resolution:

// Webpack middleware approach
const webpackStats = compiler.getStats();
const source = getSourceById(moduleId, compilation);

// Turbopack middleware approach  
const originalFrame = await createOriginalStackFrame(project, frame);

Performance Optimizations

Turbopack middleware is optimized for Turbopack's faster build system:

Faster source map resolution
Optimized module resolution
Better integration with Turbopack's incremental compilation

Error Context

Turbopack provides enhanced error context:

interface TurbopackStackFrame extends StackFrame {
  // Additional Turbopack-specific properties
  // May include module graph information
  // Enhanced source mapping data
}

API Endpoints

The Turbopack middleware provides the same API endpoints as the webpack middleware but with Turbopack-optimized implementations:

Original Stack Frame Endpoint

Endpoint: GET /__nextjs_original-stack-frame

Processes stack frames using Turbopack's source map system for faster and more accurate source resolution.

Launch Editor Endpoint

Endpoint: GET /__nextjs_launch-editor

Opens files in external editors with Turbopack's enhanced file resolution.

Error Handling

Turbopack middleware includes enhanced error handling for Turbopack-specific scenarios:

// Handle Turbopack compilation errors
function handleTurbopackError(error: Error) {
  // Turbopack errors may have additional context
  if (error.message.includes('turbo')) {
    // Handle Turbopack-specific error
    console.error('Turbopack compilation error:', error);
  }
}

Migration from Webpack

When migrating from webpack to Turbopack middleware:

Replace webpack-specific configuration with Turbopack project setup
Update stack frame processing to use Turbopack-specific functions
Adapt error handling for Turbopack's error format
Test with Turbopack's development workflow

// Before (webpack)
import { getOverlayMiddleware } from "@next/react-dev-overlay/middleware";

const middleware = getOverlayMiddleware({
  rootDirectory: __dirname,
  stats: () => webpackStats,
  serverStats: () => serverStats,
  edgeServerStats: () => null,
});

// After (Turbopack)
import { getOverlayMiddleware } from "@next/react-dev-overlay/middleware-turbopack";

const middleware = getOverlayMiddleware(turbopackProject);