vite-plugin-react-server 1.2.4 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-react-server",
-  "version": "1.2.4",
+  "version": "1.3.0",
   "description": "Vite plugin for React Server Components (RSC)",
   "type": "module",
   "main": "./dist/plugin/index.js",
@@ -11,9 +11,11 @@
     "plugin",
     "bin",
     "scripts",
+    "virtual.d.ts",
     "README.md",
     "LICENSE",
-    "tsconfig.json"
+    "tsconfig.json",
+    "oss-experimental/react-server-dom-esm"
   ],
   "exports": {
     ".": "./dist/plugin/index.js",
@@ -25,6 +27,9 @@
     "./worker": "./dist/plugin/worker/index.js",
     "./package.json": "./package.json",
     "./patch": "./bin/patch.mjs",
+    "./virtual": {
+      "types": "./virtual.d.ts"
+    },
     "./check-react-version": "./scripts/check-react-version.mjs",
     "./components": "./dist/plugin/components/index.js",
     "./types": "./dist/plugin/types.js",
@@ -149,6 +154,9 @@
       ],
       "helpers/resolveStreamElements": [
         "./dist/plugin/helpers/resolveStreamElements.d.ts"
+      ],
+      "virtual": [
+        "./virtual.d.ts"
       ]
     }
   },
@@ -211,6 +219,8 @@
     "experimental:copy": "cp -r ./oss-experimental/* ./node_modules/",
     "experimental:patch": "npx patch-package react-server-dom-esm react react-dom --exclude 'nothing'",
     "experimental:move-patches": "mv patches/* ./scripts/",
+    "experimental:build-oss": "bash scripts/build-oss-experimental.sh",
+    "experimental:build-oss-full": "bash scripts/build-oss-experimental.sh --full",
     "experimental:setup": "rm -rf patches/* && npm run experimental:clean-install && npm run experimental:copy && npm run experimental:patch && npm run experimental:move-patches",
     "experimental:patch-react": "npm run experimental:clean-install && node scripts/check-react-version.mjs && node bin/patch.mjs",
     "postinstall": "patch-package",
@@ -241,7 +251,6 @@
   "peerDependencies": {
     "react": ">=0.0.0-experimental-0",
     "react-dom": ">=0.0.0-experimental-0",
-    "react-server-dom-esm": "^0.0.1",
     "vite": "*"
   },
   "peerDependenciesMeta": {
@@ -253,6 +262,9 @@
     },
     "vite": {
       "optional": false
+    },
+    "react-server-dom-esm": {
+      "optional": true
     }
   },
   "devDependencies": {

package/plugin/orchestrator/createPluginOrchestrator.client.ts

@@ -5,6 +5,7 @@ import { vitePluginReactDevServer } from "../dev-server/plugin.client.js";
 import { reactStaticPlugin } from "../react-static/plugin.client.js";
 import { createTransformerPlugin } from "../transformer/createTransformerPlugin.js";
 import { virtualRscHmrPlugin } from "../dev-server/virtualRscHmrPlugin.js";
+import { vitePluginVendorAlias } from "../vendor/vendor-alias.js";
 
 // Client-first orchestrator - includes client SSG plugin for reverse paradigm
 export const createPluginOrchestrator = (
@@ -15,6 +16,9 @@ export const createPluginOrchestrator = (
 
   const plugins: Plugin[] = [];
 
+  // Alias react-server-dom-esm to our vendored copy
+  plugins.push(vitePluginVendorAlias());
+
   // Virtual module for RSC HMR utilities (works in both dev and build)
   plugins.push(virtualRscHmrPlugin());
   

package/plugin/orchestrator/createPluginOrchestrator.server.ts

@@ -5,6 +5,7 @@ import { vitePluginReactDevServer } from "../dev-server/plugin.server.js";
 import { reactStaticPlugin } from "../react-static/plugin.server.js";
 import { createTransformerPlugin } from "../transformer/createTransformerPlugin.js";
 import { virtualRscHmrPlugin } from "../dev-server/virtualRscHmrPlugin.js";
+import { vitePluginVendorAlias } from "../vendor/vendor-alias.js";
 
 // Server-first orchestrator - only imports server plugins
 export const createPluginOrchestrator = (
@@ -21,6 +22,9 @@ export const createPluginOrchestrator = (
 
   const plugins: Plugin[] = [];
 
+  // Alias react-server-dom-esm to our vendored copy
+  plugins.push(vitePluginVendorAlias());
+
   // Virtual module for RSC HMR utilities (works in both dev and build)
   plugins.push(virtualRscHmrPlugin());
   

package/plugin/types/react-server-dom-esm.d.ts

@@ -18,7 +18,10 @@
 
 // Client-side modules (browser environment)
 declare module 'react-server-dom-esm/client' {
-  import type { ReactNode, Usable } from 'react';
+  import type { ReactNode } from 'react';
+  // Usable was added in React 19 experimental — define locally to avoid
+  // type errors for consumers without react/experimental types
+  type Usable<T> = PromiseLike<T>;
 
   export type CreateFromFetchOptions = {
     moduleBaseURL?: string;
@@ -69,6 +72,7 @@ declare module 'react-server-dom-esm/client' {
 
 declare module 'react-server-dom-esm/client.browser' {
   import type { ReactNode } from 'react';
+  type Usable<T> = PromiseLike<T>;
 
   // ReactDOM renderToPipeableStream options (for HTML rendering)
   export type RenderToPipeableStreamOptions = {
@@ -352,6 +356,7 @@ declare module 'react-server-dom-esm/server.node' {
  */
 declare module 'react-server-dom-esm/static.node' {
   import type { ReactElement, ReactNode } from 'react';
+  type Usable<T> = PromiseLike<T>;
 
   export type PrerenderToNodeStreamOptions = {
     onError?: (error: unknown) => void;
@@ -367,5 +372,5 @@ declare module 'react-server-dom-esm/static.node' {
     model: ReactNode,
     moduleBasePath: string,
     options?: PrerenderToNodeStreamOptions
-  ): React.Usable<ReactNode>;
+  ): Usable<ReactNode>;
 }

package/plugin/types/virtual-rsc-hmr.d.ts

@@ -1,5 +1,18 @@
+interface RscHmrData {
+  file: string;
+  path: string;
+}
+
+// Augment Vite's CustomEventMap so hot.on()/hot.send() are typed
+// See: https://vite.dev/guide/api-plugin#typescript-for-custom-events
+declare module 'vite/types/customEvent' {
+  interface CustomEventMap {
+    'vite-plugin-react-server:server-component-update': RscHmrData;
+  }
+}
+
 declare module 'virtual:react-server/hmr' {
-  export const RSC_HMR_EVENT: string;
+  export const RSC_HMR_EVENT: 'vite-plugin-react-server:server-component-update';
 
   export interface RscHmrData {
     file: string;

package/plugin/utils/createReactFetcher.ts

@@ -1,3 +1,4 @@
+import type React from "react";
 import { createFromFetch } from "react-server-dom-esm/client.browser";
 import { createCallServer } from "./createCallServer.js";
 import { env } from "./env.js";
@@ -17,7 +18,7 @@ export function createReactFetcher({
   publicOrigin?: string;
   indexRSC?: string;
   headers?: HeadersInit;
-} = {}) {
+} = {}): PromiseLike<React.ReactNode> {
   const parsedURL = createPageURL(
     moduleBaseURL,
     publicOrigin,

package/plugin/vendor/vendor-alias.ts

@@ -0,0 +1,102 @@
+import type { Plugin } from "vite";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+
+// Find package root by walking up from current file until we find oss-experimental/
+// Works from both plugin/vendor/ (source) and dist/plugin/vendor/ (built)
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function findPkgRoot(): string {
+  let dir = __dirname;
+  for (let i = 0; i < 5; i++) {
+    if (existsSync(join(dir, "oss-experimental", "react-server-dom-esm"))) return dir;
+    dir = dirname(dir);
+  }
+  return dirname(dirname(__dirname)); // fallback
+}
+const pkgRoot = findPkgRoot();
+const ossDir = join(pkgRoot, "oss-experimental");
+
+/**
+ * Vite plugin that aliases `react-server-dom-esm/*` imports to the vendored
+ * copy shipped with this plugin. This eliminates the need for consumers to
+ * install `react-server-dom-esm` separately or use patch-package.
+ *
+ * Browser client entries use true ESM files for Rollup tree-shaking.
+ * Server/static entries are marked external during builds — they're CJS
+ * modules loaded at runtime via createRequire in vendor.*.ts files.
+ */
+export function vitePluginVendorAlias(): Plugin {
+  let isBuild = false;
+
+  return {
+    name: "vite-plugin-react-server:vendor-alias",
+    enforce: "pre",
+
+    config(_config, env) {
+      const pkg = join(ossDir, "react-server-dom-esm");
+      const isProd = env.mode === "production";
+      
+      // Only alias browser client to ESM for Rollup tree-shaking.
+      // Server/static are handled by resolveId with external:true.
+      return {
+        resolve: {
+          alias: [
+            { 
+              find: "react-server-dom-esm/client.browser", 
+              replacement: join(pkg, "esm", isProd 
+                ? "react-server-dom-esm-client.browser.production.js" 
+                : "react-server-dom-esm-client.browser.development.js") 
+            },
+          ],
+        },
+      };
+    },
+
+    configResolved(config) {
+      isBuild = config.command === "build";
+    },
+
+    resolveId(source) {
+      // Only handle react-server-dom-esm specifiers (not already aliased paths)
+      if (!source.startsWith("react-server-dom-esm")) {
+        return;
+      }
+
+      // Skip client.browser — handled by config alias above
+      if (source === "react-server-dom-esm/client.browser") {
+        return;
+      }
+
+      // For server/static entries during build: mark external with resolved path.
+      // At runtime, vendor.*.ts uses createRequire to load from this path.
+      if (isBuild && isServerEntry(source)) {
+        const resolved = resolveVendored(source);
+        return { id: resolved, external: true };
+      }
+
+      // For all other entries (client.node, client, index), resolve to vendored path
+      return resolveVendored(source);
+    },
+  };
+}
+
+function isServerEntry(source: string): boolean {
+  return (
+    source.includes("/server") ||
+    source.includes("/static")
+  );
+}
+
+function resolveVendored(source: string): string {
+  const vendorRequire = createRequire(
+    join(ossDir, "react-server-dom-esm", "package.json")
+  );
+  try {
+    return vendorRequire.resolve(source);
+  } catch {
+    const subpath = source.replace("react-server-dom-esm", "");
+    return join(ossDir, "react-server-dom-esm", subpath || "index.js");
+  }
+}

package/plugin/vendor/vendor.client.ts

@@ -1,15 +1,30 @@
 import { createRequire } from "node:module";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
 import { assertNonReactServer } from "../config/getCondition.js";
 
 assertNonReactServer();
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function findPkgRoot(): string {
+  let dir = __dirname;
+  for (let i = 0; i < 5; i++) {
+    if (existsSync(join(dir, "oss-experimental", "react-server-dom-esm"))) return dir;
+    dir = dirname(dir);
+  }
+  return dirname(dirname(__dirname));
+}
+const ossDir = join(findPkgRoot(), "oss-experimental");
+
+// Resolve react-server-dom-esm from our vendored copy
+const vendorRequire = createRequire(join(ossDir, "react-server-dom-esm", "package.json"));
+const ReactDOMClient = vendorRequire("react-server-dom-esm/client.node") as typeof import("react-server-dom-esm/client.node");
+
+// React and react-dom still come from the consumer's project
 const projectRoot = process.env["npm_config_local_prefix"] || process.cwd();
-const nodeRequire = createRequire(join(projectRoot, "package.json"));
-
-// Import ReactDOM from the project's node_modules
-const ReactDOMServer = nodeRequire("react-dom/server") as typeof import("react-dom/server");
-const ReactDOMClient = nodeRequire("react-server-dom-esm/client.node") as typeof import("react-server-dom-esm/client.node");
-const React = nodeRequire("react") as typeof import("react");
-   
-export { ReactDOMServer, React, ReactDOMClient };
+const projectRequire = createRequire(join(projectRoot, "package.json"));
+const ReactDOMServer = projectRequire("react-dom/server") as typeof import("react-dom/server");
+const React = projectRequire("react") as typeof import("react");
+
+export { ReactDOMServer, React, ReactDOMClient };

package/plugin/vendor/vendor.server.ts

@@ -1,13 +1,28 @@
 import { createRequire } from "node:module";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
 
-const projectRoot = process.env["npm_config_local_prefix"] || process.cwd();
-const nodeRequire = createRequire(join(projectRoot, "package.json"));
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function findPkgRoot(): string {
+  let dir = __dirname;
+  for (let i = 0; i < 5; i++) {
+    if (existsSync(join(dir, "oss-experimental", "react-server-dom-esm"))) return dir;
+    dir = dirname(dir);
+  }
+  return dirname(dirname(__dirname));
+}
+const ossDir = join(findPkgRoot(), "oss-experimental");
+
+// Resolve react-server-dom-esm from our vendored copy
+const vendorRequire = createRequire(join(ossDir, "react-server-dom-esm", "package.json"));
+const ReactDOMServer = vendorRequire("react-server-dom-esm/server.node") as typeof import("react-server-dom-esm/server.node");
 
-// Import ReactDOM from the project's node_modules
-const ReactDOMServer = nodeRequire("react-server-dom-esm/server.node") as typeof import("react-server-dom-esm/server.node");
-const React = nodeRequire("react") as typeof import("react");
+// React still comes from the consumer's project
+const projectRoot = process.env["npm_config_local_prefix"] || process.cwd();
+const projectRequire = createRequire(join(projectRoot, "package.json"));
+const React = projectRequire("react") as typeof import("react");
 
 export { ReactDOMServer, React };
 export type * from "react-server-dom-esm/server.node";
-export type React = typeof import("react");
+export type React = typeof import("react");

package/plugin/vendor/vendor.static.ts

@@ -1,12 +1,26 @@
 import { createRequire } from "node:module";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
 
-const projectRoot = process.env["npm_config_local_prefix"] || process.cwd();
-const nodeRequire = createRequire(join(projectRoot, "package.json"));
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function findPkgRoot(): string {
+  let dir = __dirname;
+  for (let i = 0; i < 5; i++) {
+    if (existsSync(join(dir, "oss-experimental", "react-server-dom-esm"))) return dir;
+    dir = dirname(dir);
+  }
+  return dirname(dirname(__dirname));
+}
+const ossDir = join(findPkgRoot(), "oss-experimental");
+
+// Resolve react-server-dom-esm from our vendored copy
+const vendorRequire = createRequire(join(ossDir, "react-server-dom-esm", "package.json"));
+const ReactDOMServer = vendorRequire("react-server-dom-esm/static.node") as typeof import("react-server-dom-esm/static.node");
 
-// Import ReactDOM from the project's node_modules for static pre-rendering
-// This includes unstable_prerenderToNodeStream for build-time stream creation
-const ReactDOMServer = nodeRequire("react-server-dom-esm/static.node") as typeof import("react-server-dom-esm/static.node");
-const React = nodeRequire("react") as typeof import("react");
+// React still comes from the consumer's project
+const projectRoot = process.env["npm_config_local_prefix"] || process.cwd();
+const projectRequire = createRequire(join(projectRoot, "package.json"));
+const React = projectRequire("react") as typeof import("react");
 
 export { ReactDOMServer, React };

package/scripts/build-oss-experimental.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Build react-server-dom-esm from React source for the oss-experimental/ folder.
+#
+# Usage:
+#   ./scripts/build-oss-experimental.sh [--react-dir PATH] [--full]
+#
+# Prerequisites:
+#   - yarn (React repo uses yarn workspaces)
+#   - Node.js 18+
+#   - java (for Google Closure Compiler, used by React's build)
+#
+# This script:
+#   1. Clones facebook/react into ../react (or uses existing checkout)
+#   2. Installs dependencies with yarn
+#   3. Builds react-server-dom-esm (targeted) or full experimental channel
+#   4. Runs packaging to create the publishable output
+#   5. Copies results into oss-experimental/
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLUGIN_DIR="$(dirname "$SCRIPT_DIR")"
+REACT_DIR="${REACT_DIR:-$(dirname "$PLUGIN_DIR")/react}"
+OSS_DIR="$PLUGIN_DIR/oss-experimental"
+FULL_BUILD=false
+
+# Parse args
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --react-dir) REACT_DIR="$2"; shift 2 ;;
+    --full) FULL_BUILD=true; shift ;;
+    --help|-h)
+      echo "Usage: $0 [--react-dir PATH] [--full]"
+      echo ""
+      echo "Build react-server-dom-esm from React source."
+      echo ""
+      echo "Options:"
+      echo "  --react-dir PATH  Path to React checkout (default: ../react)"
+      echo "  --full            Build ALL packages (slow, ~15 min)"
+      echo "                    Default: targeted build of react-server-dom-esm only (~2 min)"
+      exit 0
+      ;;
+    *) echo "Unknown option: $1"; exit 1 ;;
+  esac
+done
+
+echo "Plugin dir:  $PLUGIN_DIR"
+echo "React dir:   $REACT_DIR"
+echo "Output dir:  $OSS_DIR"
+echo "Full build:  $FULL_BUILD"
+echo ""
+
+# Step 1: Clone or update React
+if [ ! -d "$REACT_DIR" ]; then
+  echo "==> Cloning facebook/react (shallow)..."
+  git clone --depth 1 https://github.com/facebook/react.git "$REACT_DIR"
+else
+  echo "==> Using existing React checkout at $REACT_DIR"
+  echo "    Branch: $(cd "$REACT_DIR" && git branch --show-current 2>/dev/null || echo 'detached')"
+  echo "    Commit: $(cd "$REACT_DIR" && git rev-parse --short HEAD)"
+  echo ""
+  read -p "    Pull latest? [y/N] " -n 1 -r
+  echo
+  if [[ $REPLY =~ ^[Yy]$ ]]; then
+    (cd "$REACT_DIR" && git pull)
+  fi
+fi
+
+# Step 2: Install dependencies
+echo ""
+echo "==> Installing React dependencies (yarn)..."
+cd "$REACT_DIR"
+
+if ! command -v yarn &>/dev/null; then
+  echo "ERROR: yarn is required but not installed."
+  echo "Install with: npm install -g yarn"
+  exit 1
+fi
+
+yarn install --frozen-lockfile 2>&1 | tail -5
+
+# Step 3: Build
+echo ""
+if [ "$FULL_BUILD" = true ]; then
+  echo "==> Building full React experimental channel (this takes ~15 min)..."
+  RELEASE_CHANNEL=experimental node scripts/rollup/build-all-release-channels.js \
+    --releaseChannel experimental 2>&1 | tail -20
+else
+  echo "==> Building react-server-dom-esm (targeted, ~2 min)..."
+  echo "    (Use --full to build all packages)"
+  echo ""
+
+  # React's build.js accepts bundle names as positional args to filter.
+  # We need react-server-dom-esm but it imports from shared React internals,
+  # so we also need to build the core 'react' package first.
+  #
+  # RELEASE_CHANNEL=experimental ensures __EXPERIMENTAL__ is true.
+  RELEASE_CHANNEL=experimental node scripts/rollup/build.js \
+    react react-server-dom-esm 2>&1 | tail -30
+
+  # Run packaging step to create the final publishable package structure
+  # (copies files into build/oss-experimental/)
+  echo ""
+  echo "==> Running packaging..."
+  RELEASE_CHANNEL=experimental node scripts/rollup/build-all-release-channels.js \
+    --releaseChannel experimental --unsafe-partial 2>&1 | tail -20
+fi
+
+# Step 4: Copy to oss-experimental/
+echo ""
+echo "==> Copying packages to oss-experimental/..."
+
+BUILD_BASE="$REACT_DIR/build/oss-experimental"
+
+if [ ! -d "$BUILD_BASE" ]; then
+  echo "ERROR: Build output not found at $BUILD_BASE"
+  echo ""
+  echo "If the targeted build didn't create the packaging output,"
+  echo "try running with --full flag."
+  exit 1
+fi
+
+mkdir -p "$OSS_DIR"
+
+# Always copy react-server-dom-esm (the one we need)
+for pkg in react-server-dom-esm react react-dom; do
+  BUILD_PKG="$BUILD_BASE/$pkg"
+  if [ -d "$BUILD_PKG" ]; then
+    rm -rf "$OSS_DIR/$pkg"
+    cp -r "$BUILD_PKG" "$OSS_DIR/$pkg"
+    echo "  ✓ $pkg"
+  else
+    echo "  ✗ $pkg (not found in build output)"
+  fi
+done
+
+# If full build, copy everything
+if [ "$FULL_BUILD" = true ]; then
+  for pkg in "$BUILD_BASE"/*/; do
+    pkg_name=$(basename "$pkg")
+    if [[ "$pkg_name" != "react" && "$pkg_name" != "react-dom" && "$pkg_name" != "react-server-dom-esm" ]]; then
+      rm -rf "$OSS_DIR/$pkg_name"
+      cp -r "$pkg" "$OSS_DIR/$pkg_name"
+      echo "  ✓ $pkg_name"
+    fi
+  done
+fi
+
+# Report version
+VERSION=$(python3 -c "import json; print(json.load(open('$OSS_DIR/react-server-dom-esm/package.json'))['version'])" 2>/dev/null || echo "unknown")
+echo ""
+echo "==> Done! react-server-dom-esm version: $VERSION"
+echo "    Output: $OSS_DIR/"
+echo ""
+echo "Next steps:"
+echo "  1. Update TEMPLATE_VERSION in bin/patch.mjs to:"
+echo "     $VERSION"
+echo "  2. Regenerate patches:"
+echo "     npm run experimental:setup"
+echo "  3. Test:"
+echo "     npm run experimental:patch-react"

package/virtual.d.ts

@@ -0,0 +1,20 @@
+/// <reference path="./plugin/types/virtual-rsc-hmr.d.ts" />
+
+// Type declarations for virtual modules and custom events provided by vite-plugin-react-server.
+//
+// To enable, add to your tsconfig.json:
+//   "types": ["vite/client", "vite-plugin-react-server/virtual"]
+//
+// This provides:
+// - Type support for `virtual:react-server/hmr` (useRscHmr, setupRscHmr)
+// - Typed custom HMR event: `vite-plugin-react-server:server-component-update`
+//   (augments Vite's CustomEventMap for import.meta.hot.on() / hot.send())
+// - ImportMetaEnv augmentation for PUBLIC_ORIGIN
+
+declare global {
+  interface ImportMetaEnv {
+    readonly PUBLIC_ORIGIN: string;
+  }
+}
+
+export {};