tessl/npm-react-server-dom-webpack

React Server Components bindings for DOM using Webpack, enabling server-side rendering with streaming support and client-server communication.

—

Pending

Overview

Eval results

Files

Webpack Plugin

Name: tessl/npm-react-server-dom-webpack
Author: tessl

Webpack plugin for processing React Server Components, automatically detecting client references with "use client" directives, and generating client and server manifests for module resolution.

Capabilities

ReactFlightWebpackPlugin

Main webpack plugin class that integrates React Server Components processing into the webpack build pipeline.

/**
 * Webpack plugin for React Server Components processing
 * @param options - Plugin configuration options
 */
class ReactFlightWebpackPlugin {
  constructor(options: PluginOptions);
  
  /**
   * Applies the plugin to the webpack compiler
   * @param compiler - Webpack compiler instance
   */
  apply(compiler: WebpackCompiler): void;
}

Usage Example:

const ReactFlightWebpackPlugin = require("react-server-dom-webpack/plugin");

module.exports = {
  plugins: [
    new ReactFlightWebpackPlugin({
      isServer: false,
      clientReferences: [
        {
          directory: "./src/components",
          recursive: true,
          include: /\.(js|jsx|ts|tsx)$/,
          exclude: /\.test\./
        },
        "./src/pages/**/*.client.js"
      ],
      chunkName: "client-[index]",
      clientManifestFilename: "client-manifest.json",
      serverConsumerManifestFilename: "server-manifest.json"
    })
  ]
};

Plugin Configuration

The plugin accepts comprehensive configuration options for customizing client reference detection and manifest generation.

interface PluginOptions {
  /** Whether this is a server-side build (currently must be false) */
  isServer: boolean;
  /** Client reference paths or search configurations */
  clientReferences?: ClientReferencePath | ClientReferencePath[];
  /** Chunk naming pattern for client references */
  chunkName?: string;
  /** Output filename for client manifest */
  clientManifestFilename?: string;
  /** Output filename for server consumer manifest */
  serverConsumerManifestFilename?: string;
}

type ClientReferencePath = string | ClientReferenceSearchPath;

interface ClientReferenceSearchPath {
  /** Directory to search for client references */
  directory: string;
  /** Whether to search recursively in subdirectories */
  recursive?: boolean;
  /** RegExp pattern for files to include */
  include: RegExp;
  /** RegExp pattern for files to exclude */
  exclude?: RegExp;
}

Configuration Examples:

// Simple string-based client references
{
  isServer: false,
  clientReferences: [
    "./src/components/Button.tsx",
    "./src/components/Modal.tsx"
  ]
}

// Directory-based search configuration
{
  isServer: false,
  clientReferences: [
    {
      directory: "./src",
      recursive: true,
      include: /\.(js|jsx|ts|tsx)$/,
      exclude: /\.(test|spec)\./
    }
  ]
}

// Mixed configuration
{
  isServer: false,
  clientReferences: [
    "./src/components/SpecialComponent.tsx",
    {
      directory: "./src/pages",
      recursive: true,
      include: /\.client\.(js|tsx)$/
    }
  ]
}

Client Reference Detection

The plugin automatically detects files with "use client" directive and processes them for client-side code splitting.

Client Component Example:

// src/components/Button.tsx
"use client";

import { useState } from "react";

export function Button({ children, onClick }) {
  const [loading, setLoading] = useState(false);
  
  return (
    <button 
      onClick={async () => {
        setLoading(true);
        await onClick();
        setLoading(false);
      }}
      disabled={loading}
    >
      {loading ? "Loading..." : children}
    </button>
  );
}

Manifest Generation

The plugin generates two key manifest files for runtime module resolution:

Client Manifest

Maps client components to their webpack chunks for dynamic loading.

{
  "file:///path/to/Button.tsx": {
    "id": "./src/components/Button.tsx",
    "chunks": ["client-0", "client-0.js"],
    "name": "*"
  }
}

Server Consumer Manifest

Provides server-side module loading configuration and mappings.

{
  "moduleLoading": {
    "prefix": "/static/js/",
    "crossOrigin": "anonymous"
  },
  "moduleMap": {
    "./src/components/Button.tsx": {
      "*": {
        "specifier": "file:///path/to/Button.tsx",
        "name": "*"
      }
    }
  }
}

Chunk Naming

Customizable chunk naming patterns for client reference bundles.

// Default chunk naming
chunkName: "client[index]"

// Custom naming with request path
chunkName: "rsc-[request]-[index]"

// Results in chunks like: rsc-Button-0.js, rsc-Modal-1.js

Chunk Naming Patterns:

[index] - Sequential index number for each client reference
[request] - Transformed request path of the client component
Custom prefix/suffix - Any static string to identify RSC chunks

Error Handling and Warnings

The plugin provides detailed error reporting and warnings for common configuration issues.

Common Warnings:

// Warning when client runtime is not found
"Client runtime at react-server-dom-webpack/client was not found. 
 React Server Components module map file client-manifest.json was not created."

// Error for invalid server configuration
"React Server Plugin: You must specify the isServer option as a boolean."

// Error for unsupported server mode
"TODO: Implement the server compiler."

Advanced Configuration

Additional configuration options for fine-tuning plugin behavior.

// Advanced webpack.config.js setup
module.exports = {
  plugins: [
    new ReactFlightWebpackPlugin({
      isServer: false,
      clientReferences: [
        {
          directory: "./src",
          recursive: true,
          include: /\.(js|jsx|ts|tsx)$/,
          exclude: /\.(test|spec|d\.ts)$/
        }
      ],
      chunkName: "rsc-[request]-[index]",
      clientManifestFilename: "rsc-client-manifest.json",
      serverConsumerManifestFilename: "rsc-server-manifest.json"
    })
  ],
  output: {
    crossOriginLoading: "anonymous", // Affects manifest crossOrigin setting
    publicPath: "/assets/"           // Affects manifest prefix setting
  }
};

Integration Notes

Build Pipeline Integration

The plugin integrates deeply with webpack's compilation process:

Module Analysis: Scans specified directories for client references
Directive Processing: Parses files using acorn to detect "use client"
Dependency Injection: Adds client references as async dependencies
Chunk Generation: Creates separate chunks for client components
Manifest Creation: Generates runtime manifests during asset processing

Runtime Requirements

The plugin requires the React Server DOM client runtime to be imported somewhere in the build to establish the dependency graph:

// This import must exist in your client bundle
import "react-server-dom-webpack/client";

Multi-Environment Builds

For applications supporting multiple environments, configure separate webpack builds:

// webpack.client.js
module.exports = {
  entry: "./src/client.js",
  plugins: [
    new ReactFlightWebpackPlugin({
      isServer: false,
      clientReferences: [/* client refs */]
    })
  ]
};

// webpack.server.js
module.exports = {
  entry: "./src/server.js",
  target: "node",
  // Server builds currently use external manifest consumption
  externals: {
    "react-server-dom-webpack/client": "commonjs2 react-server-dom-webpack/client"
  }
};

Install with Tessl CLI

npx tessl i tessl/npm-react-server-dom-webpack

docs

client-apis.md

data-communication.md

index.md

nodejs-integration.md