vite-plugin-react-server 0.1.0

package/src/react-server/plugin.ts

@@ -0,0 +1,349 @@
+import { readFileSync } from "node:fs";
+import type { ServerResponse } from "node:http";
+import { resolve as resolvePath } from "node:path";
+import { performance } from "node:perf_hooks";
+import { Worker } from "node:worker_threads";
+import type { Plugin as RollupPlugin } from "rollup";
+import type { Manifest, Plugin as VitePlugin } from "vite";
+import {
+  createLogger,
+  type ResolvedConfig,
+  type UserConfig,
+  type ViteDevServer,
+} from "vite";
+import { createBuildConfig } from "../build/createBuildConfig.js";
+import { checkFilesExist } from "../checkFilesExist.js";
+import { getEnv } from "../getEnv.js";
+import { createPageLoader } from "../html/createPageLoader.js";
+import { renderPages } from "../worker/renderPages.js";
+import { resolveOptions, resolvePages, resolveUserConfig } from "../options.js";
+import type { BuildTiming, ReactStreamPluginMeta } from "../types.js";
+import { type StreamPluginOptions } from "../types.js";
+import { createWorker } from "../worker/createWorker.js";
+import { createHandler } from "./createHandler.js";
+
+let pageSet: Set<string>;
+let pageMap: Map<string, string>;
+let worker: Worker;
+let config: ResolvedConfig;
+let cssModules = new Set<string>();
+let clientComponents = new Map<string, string>();
+let define: Record<string, string>;
+let buildCssFiles = new Set<string>();
+
+interface BuildStats {
+  htmlFiles: number;
+  clientComponents: number;
+  cssFiles: number;
+  totalRoutes: number;
+  timing: {
+    config: number;
+    build: number;
+    render: number;
+    total: number;
+  };
+}
+
+export async function reactStreamPlugin(
+  options: StreamPluginOptions = {} as StreamPluginOptions
+): Promise<VitePlugin & RollupPlugin & { meta: ReactStreamPluginMeta }> {
+  const timing: BuildTiming = {
+    start: performance.now(),
+  };
+  const resolvedOptions = resolveOptions(options);
+  if (resolvedOptions.type === "error") {
+    console.error(
+      "[vite-react-stream:server] Error resolving userOptions. Please check your userOptions."
+    );
+    throw resolvedOptions.error;
+  }
+  const { userOptions } = resolvedOptions;
+  return {
+    name: "vite:react-stream",
+    meta: {
+      timing,
+    } as ReactStreamPluginMeta,
+    api: {
+      addCssFile(path: string) {
+        buildCssFiles.add(path);
+      },
+    },
+    configResolved(resolvedConfig) {
+      if (resolvedConfig.command === "build") {
+        timing.configResolved = performance.now();
+        console.log("[vite-react-stream] Starting build...");
+      }
+      config = resolvedConfig;
+    },
+    async configureServer(server: ViteDevServer) {
+      if (server.config.root) {
+        console.log(
+          "[vite-react-stream] Root dir changed",
+          server.config.root,
+          server.config.root
+        );
+      }
+
+      const activeStreams = new Set<ServerResponse>();
+
+      // Handle Vite server restarts
+      server.ws.on("restart", (path) => {
+        console.log(
+          "[vite-react-stream] 🔧 Plugin changed, preparing for restart:",
+          path
+        );
+
+        // Close streams with restart message
+        for (const res of activeStreams) {
+          res.writeHead(503, {
+            "Content-Type": "text/x-component",
+            "Retry-After": "1",
+          });
+          res.end('{"error":"Server restarting..."}');
+        }
+        activeStreams.clear();
+      });
+
+      server.ws.on("connection", (socket, req) => {
+        console.log("[vite-react-stream] hooking up ws connection");
+      });
+
+      server.ws.on("listening", () => {
+        console.log("[vite-react-stream] hooking up ws listening");
+      });
+
+      server.middlewares.use(async (req, res, next) => {
+        if (req.headers.accept !== "text/x-component") return next();
+        console.log("[vite-react-stream] middleware called");
+        try {
+          const handler = await createHandler(
+            req.url ?? "",
+            {
+              Page: userOptions.Page,
+              props: userOptions.props,
+              build: userOptions.build,
+              Html: ({ children }) => children,
+              pageExportName: userOptions.pageExportName,
+              propsExportName: userOptions.propsExportName,
+              moduleBase: userOptions.moduleBase,
+              moduleBasePath: userOptions.moduleBasePath,
+              projectRoot: server.config.root,
+            },
+            {
+              cssFiles: Array.from(cssModules),
+              logger: createLogger(),
+              loader: server.ssrLoadModule,
+              moduleGraph: server.moduleGraph,
+            }
+          );
+          handler?.stream?.pipe(res);
+        } finally {
+          res.on("close", () => {
+            console.log("[vite-react-stream] ➖ Stream closed for:", req.url);
+            activeStreams.delete(res);
+          });
+        }
+      });
+    },
+
+    async config(config, configEnv): Promise<UserConfig> {
+      const resolvedPages = await resolvePages(userOptions.build.pages);
+      if(resolvedPages.type === 'error') {
+        throw resolvedPages.error;
+      }
+      const { pages } = resolvedPages;
+      const resolvedConfig = resolveUserConfig(
+        "react-server",
+        pages,
+        config,
+        configEnv,
+        userOptions
+      );
+      if(resolvedConfig.type === "error") {
+        throw resolvedConfig.error;
+      }
+      const { userConfig } = resolvedConfig;
+
+      const envResult = getEnv(userConfig, configEnv);
+      const files = await checkFilesExist(pages, userOptions, userConfig.root);
+      pageSet = files.pageSet;
+      pageMap = files.pageMap;
+      define = envResult.define;
+      const entries = Array.from(
+        new Set([
+          ...Array.from(files.pageSet.values()),
+          ...Array.from(files.propsSet.values()),
+        ]).values()
+      );
+
+      const buildConfig = createBuildConfig({
+        root: config.root ?? process.cwd(),
+        base: config.base ?? envResult.publicUrl,
+        outDir: config.build?.outDir ?? "dist/server",
+        entries,
+      });
+      return {
+        ...buildConfig,
+        define,
+        plugins: config.plugins,
+      };
+    },
+    async buildStart() {
+      timing.buildStart = performance.now();
+    },
+    async closeBundle() {
+      if(!config) return;
+      console.log("RSC CLOSE BUNDLE CALLED");
+      if (!pageSet?.size) return;
+      timing.renderStart = performance.now();
+
+      try {
+        const manifest = JSON.parse(
+          readFileSync(
+            resolvePath(
+              config.root,
+              config.build.outDir,
+              ".vite",
+              "manifest.json"
+            ),
+            "utf-8"
+          )
+        ) as Manifest;
+        const clientManifest = JSON.parse(
+          readFileSync(
+            resolvePath(
+              config.root,
+              userOptions.build.client,
+              ".vite",
+              "manifest.json"
+            ),
+            "utf-8"
+          )
+        ) as Manifest;
+        // Create a single worker for all routes
+        if (!worker)
+          worker = await createWorker(
+            config.root,
+            config.build.outDir,
+            "worker.js",
+            process.env["NODE_ENV"] === "development" ? "development" : "production"
+          );
+        // this is based on the user config - the routes should lead to a page and props but the rendering is agnostic of that
+        const routes = Array.from(pageMap.keys());
+        const indexEntry = clientManifest["index.html"];
+        if (!indexEntry) {
+          throw new Error("root /index.html not found");
+        }
+        await renderPages(routes, {
+          pipableStreamOptions: {
+            bootstrapModules: ["/" + indexEntry.file],
+          },
+          outDir: config.build.outDir,
+          clientCss: indexEntry.css?.map((css) => "/" + css) ?? [],
+          pluginOptions: {
+            Page: userOptions.Page,
+            props: userOptions.props,
+            build: userOptions.build,
+            Html: userOptions.Html,
+            pageExportName: userOptions.pageExportName,
+            propsExportName: userOptions.propsExportName,
+            moduleBase: userOptions.moduleBase,
+            moduleBasePath: userOptions.moduleBasePath,
+            moduleBaseURL: userOptions.moduleBaseURL,
+            projectRoot: config.root,
+          },
+          worker: worker,
+          manifest: clientManifest as Manifest,
+          loader: createPageLoader({
+            manifest,
+            root: config.root,
+            outDir: config.build.outDir,
+            moduleBase: userOptions.moduleBase,
+            alwaysRegisterServer: false,
+            alwaysRegisterClient: false,
+            registerServer: [],
+            registerClient: Object.keys(clientManifest).filter(
+              (key) =>
+                key.endsWith(".client.tsx") && clientManifest[key].isEntry
+            ),
+          }),
+          onCssFile: (path) => buildCssFiles.add(path),
+        });
+        console.log("[vite-react-stream] Render complete");
+        console.log("[vite-react-stream] Terminating worker");
+        if (worker) await worker.terminate();
+
+        timing.renderEnd = performance.now();
+        timing.total = (timing.renderEnd - timing.start) / 1000;
+
+        // Collect stats
+        const stats: BuildStats = {
+          htmlFiles: routes.length,
+          clientComponents: clientComponents.size,
+          cssFiles: cssModules.size,
+          totalRoutes: routes.length,
+          timing: {
+            config: ((timing.configResolved ?? 0) - timing.start) / 1000,
+            build:
+              ((timing.buildStart ?? 0) - (timing.configResolved ?? 0)) / 1000,
+            render:
+              ((timing.renderEnd ?? 0) - (timing.renderStart ?? 0)) / 1000,
+            total: (timing.renderEnd ?? 0 - timing.start) / 1000,
+          },
+        };
+
+        // Format duration helper
+        const formatDuration = (seconds: number) => {
+          if (seconds < 0.001) {
+            return `${(seconds * 1000000).toFixed(0)}μs`;
+          }
+          if (seconds < 1) {
+            return `${(seconds * 1000).toFixed(0)}ms`;
+          }
+          return `${seconds.toFixed(2)}s`;
+        };
+
+        console.log("\n[vite-react-stream] Build Summary:");
+        console.log("─".repeat(50));
+        console.log(`📄 Generated ${stats.htmlFiles} HTML files`);
+        console.log(`🎯 Processed ${stats.clientComponents} client components`);
+        console.log(`🎨 Included ${stats.cssFiles} CSS files`);
+        console.log(`🛣️  Total routes: ${stats.totalRoutes}`);
+        console.log("─".repeat(50));
+        console.log("⏱️  Timing:");
+        console.log(`  Config:  ${formatDuration(stats.timing.config)}`);
+        console.log(`  Build:   ${formatDuration(stats.timing.build)}`);
+        console.log(`  Render:  ${formatDuration(stats.timing.render)}`);
+        console.log("  ".repeat(12));
+        console.log(`  Total:   ${formatDuration(stats.timing.total)}`);
+        console.log("─".repeat(50));
+      } catch (error) {
+        console.error("[vite-react-stream] Build failed:", error);
+        throw error;
+      }
+    },
+    async buildEnd(error) {
+      if (error) {
+        console.error("[vite-react-stream] Build error:", error);
+      }
+      if (worker) await worker.terminate();
+    },
+    handleHotUpdate({ file }) {
+      if (file.endsWith(".css")) {
+        cssModules.add(file);
+      }
+    },
+    transform(code: string, id: string) {
+      if (
+        (id.includes(".client") ||
+          code.startsWith('"use client"') ||
+          code.startsWith("use client")) &&
+        !id.includes("node_modules")
+      ) {
+        console.log("[vite-react-stream] Client component added", id);
+        clientComponents.set(id, code);
+      }
+      return { code };
+    },
+  };
+}

package/src/resolvePage.ts

@@ -0,0 +1,65 @@
+type ResolvePageOptions = {
+  pageModule: Record<string, any>;
+  path: string;
+  url: string;
+  exportName: string;
+};
+
+type ResolvePageResult =
+  | { type: "success"; key: string; Page: any }
+  | { type: "error"; error: Error }
+  | { type: "skip" };
+
+export async function resolvePage({
+  pageModule,
+  path,
+  url,
+  exportName,
+}: ResolvePageOptions): Promise<ResolvePageResult> {
+  if (!pageModule) {
+    return {
+      type: "error",
+      error: new Error(`pageModule is ${typeof pageModule}`),
+    };
+  }
+  const keys =
+    typeof pageModule === "object" && pageModule != null
+      ? Object.keys(pageModule)
+      : [];
+  const found = keys.find((v) => v === exportName || v === url || v === path);
+  if (found) {
+    if (typeof pageModule[found] === "function") {
+      return {
+        type: "success",
+        key: found,
+        Page: pageModule[found],
+      };
+    } else {
+      if (
+        typeof pageModule === "object" &&
+        pageModule != null &&
+        Object.keys(pageModule).includes("type")
+      )
+        return pageModule as ResolvePageResult;
+      return {
+        type: "error",
+        [exportName]: () => found,
+        error: pageModule[found]["error"],
+      };
+    }
+  }
+  if (keys.includes("type")) return pageModule as ResolvePageResult;
+  return {
+    type: "error",
+    error: new Error(
+      `Could not find Page export "${exportName}" in "${path}". ${
+        typeof pageModule === "object" && pageModule != null
+          ? keys.length
+            ? "Available exports: " + keys.join(", ")
+            : "The object was defined but has no properties."
+          : "typeof pageModule =" + typeof pageModule
+      }`,
+      { cause: pageModule }
+    ),
+  };
+}

package/src/resolveProps.ts

@@ -0,0 +1,122 @@
+type ResolvePropsOptions = {
+  propsModule: Record<string, any>;
+  path: string;
+  exportName: string;
+  url: string;
+};
+
+type ResolvePropsResult =
+  | { type: "success"; key: string; props: any }
+  | { type: "error"; error: Error }
+  | { type: "skip" };
+
+function isFunction(value: any) {
+  return typeof value === "function";
+}
+
+export async function resolveProps({
+  propsModule,
+  path,
+  exportName,
+  url,
+}: ResolvePropsOptions): Promise<ResolvePropsResult> {
+  if (!propsModule) {
+    return {
+      type: "error",
+      error: new Error(`propsModule is ${typeof propsModule}`),
+    };
+  }
+
+  if (typeof propsModule !== "object") {
+    return {
+      type: "error",
+      error: new Error(
+        `propsModule must be an object, got ${typeof propsModule}`
+      ),
+    };
+  }
+
+  const keys = Object.keys(propsModule);
+  const found = keys.find((v) => v === exportName || v === url || v === path);
+  if (found) {
+    const value = propsModule[found];
+
+    try {
+      // If it's a function, call it with the URL
+      if (isFunction(value)) {
+        const props = await value(url);
+        return {
+          type: "success",
+          key: found,
+          props,
+        };
+      }
+
+      // If it's a promise, await it
+      if (value && typeof value.then === "function") {
+        const props = await value;
+        return {
+          type: "success",
+          key: found,
+          props,
+        };
+      }
+
+      // If it's a plain object, use it directly
+      if (typeof value === "object" && value !== null) {
+        return {
+          type: "success",
+          key: found,
+          props: value,
+        };
+      }
+
+      console.warn(found, "error in resolveProps", propsModule, url, path);
+      return {
+        type: "error",
+        error: new Error(
+          `Expected props export "${exportName}" in "${path}" to be a function, promise, or object that resolves to props, instead got typeof ${typeof value}.`
+        ),
+      };
+    } catch (error) {
+      console.warn(found, "error in resolveProps", propsModule, url, path);
+      return {
+        type: "error",
+        error: error as Error,
+      };
+    }
+  }
+  const commonjs = keys.find((v) => v === "exports");
+
+  if (!!commonjs) {
+    const exportKeys = (commonjs as unknown as { exports: any })["exports"]
+      ? Object.keys((commonjs as unknown as { exports: any })["exports"])
+      : [];
+    const foundCommonJS = exportKeys.find(
+      (v) => v === exportName || v === url || v === path
+    );
+    return {
+      type: "error",
+      error: new Error(
+        `Expected props export "${exportName}" in "${path}", but instead got "exports" with ${
+          !!foundCommonJS
+            ? foundCommonJS.toString()
+            : exportKeys.length
+            ? exportKeys.join(", ")
+            : "no keys"
+        }, this will not work. Make sure to set esModule: true in rollupOptions.output`
+      ),
+    };
+  }
+
+  return {
+    type: "error",
+    error: new Error(
+      `Could not find props export "${exportName}" in "${path}". ${
+        keys.length
+          ? "Available exports: " + keys.join(", ")
+          : "The object was defined but has no properties."
+      }`
+    ),
+  };
+}

package/src/transformer/README.md

@@ -0,0 +1,44 @@
+# Vite React Client Transform plugin
+
+When consuming such a client file, you need to call vite with the react-server condition.
+
+```json
+{ 
+    "scripts":{
+        "build": "NODE_OPTIONS='--conditions react-server' vite build",
+        "dev": "NODE_OPTIONS='--conditions react-server' vite",
+    }
+}
+```
+
+## Key Concepts
+
+1. **Environment Separation**
+   - The main thread runs with Vite's `react-server` condition
+   - HTML rendering must happen in a clean Node environment (worker thread)
+   - Worker needs `NODE_OPTIONS=''` to avoid inheriting Vite's conditions
+
+2. **RSC Stream Flow**
+   ```
+   Main Thread (Vite)     Worker Thread (Clean Node)            Vite Dev Thread (Browser)
+   ---------------        ---------------------                 ---------------------
+   RSC Stream     →       HTML Rendering                        React Client
+   (react-server) →       (react-dom/server.node)               (react-dom/client)
+                  →       (react-server-dom-esm/client.node)    (react-server-dom-esm/client.browser)
+   ```
+
+3. **Request Handling**
+   - Skip Vite's internal requests (`/@vite/client`, etc.)
+   - Handle HTML and directory requests
+   - Pass through static files
+
+4. **Module Resolution**
+   - Client components need proper import maps
+   - Use Vite's module resolution for dependencies
+   - Bootstrap modules must be properly resolved
+
+5. **Common Pitfalls**
+   - Don't try to use `react-dom/server.node` in the main thread
+   - Don't mix React server/client conditions in the same environment
+   - Be careful with stream handling between threads
+   - Watch for proper module resolution in both environments

package/src/transformer/index.ts

@@ -0,0 +1,112 @@
+import type { Plugin } from "vite";
+import { normalizePath } from "vite";
+import { DEFAULT_CONFIG } from "../options.js";
+import { createRscTransformer } from "./transformer.js";
+import type { ViteReactClientTransformOptions } from "./types.js";
+
+
+/**
+ * Plugin for transforming React Client Components.
+ *
+ * Core responsibilities:
+ * 1. Detects "use client" directives
+ * 2. Transforms client components for RSC boundaries
+ * 3. Adds client reference metadata for RSC
+ *
+ * When a component is marked with "use client", it:
+ * - Gets transformed into a client reference
+ * - Maintains module ID for RSC boundaries
+ * - Preserves class/function behavior
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *   plugins: [
+ *     viteReactClientTransformPlugin({
+ *       projectRoot: process.cwd(),
+ *     })
+ *   ]
+ * });
+ * ```
+ */
+
+export function viteReactClientTransformPlugin(
+  options?: ViteReactClientTransformOptions
+): Plugin {
+  if(process.env['NODE_OPTIONS']?.match(/--conditions=react-server/)) {
+    console.log('react-server')
+  } else {
+    throw new Error('react-server condition not found, set NODE_OPTIONS="--conditions react-server"')
+  }
+  const projectRoot = options?.projectRoot || process.cwd();
+  const include = options?.include || DEFAULT_CONFIG.FILE_REGEX;
+  const exclude = options?.exclude;
+  let transform: any;
+  // get the file we are imported from (parent)
+
+  return {
+    name: "vite:react-stream-transformer",
+    enforce: "pre",
+
+    configResolved(config) {
+      transform = createRscTransformer({
+        moduleId:
+          options?.moduleId ||
+          moduleIdDefault({
+            projectRoot: projectRoot,
+            output: {
+              dir: config.build?.outDir ?? DEFAULT_CONFIG.BUILD.server,
+            },
+            isProduction: config.isProduction,
+          }),
+      }).transform;
+    },
+
+    transform(code: string, id: string, opts) {
+      // Skip if file doesn't match patterns
+      if (
+        !matchPattern(id, include) ||
+        (exclude && matchPattern(id, exclude))
+      ) {
+        return null;
+      }
+
+      // Look for use client directive at start of file (no exceptions)
+      const directiveMatch =
+        code.startsWith('"use client"') || code.startsWith("'use client'");
+      if (!directiveMatch) return null;
+
+      // Transform client components
+      return transform(code, id, opts);
+    },
+  };
+}
+
+const moduleIdDefault =
+  ({
+    projectRoot,
+    output: _,
+    isProduction,
+  }: {
+    isProduction: boolean;
+    projectRoot: string;
+    output: { dir: string };
+  }) =>
+  (moduleId: string) => {
+    const normalized = normalizePath(moduleId);
+    const noRoot = normalized.startsWith(projectRoot)
+      ? normalized.slice(projectRoot.length)
+      : normalized;
+    if (!isProduction) {
+      return noRoot;
+    }
+    return noRoot.replace(DEFAULT_CONFIG.FILE_REGEX, ".js");
+  };
+
+const matchPattern = (
+  file: string,
+  pattern: string | RegExp | (string | RegExp)[]
+) =>
+  Array.isArray(pattern)
+    ? pattern.some((p) => file.match(p as RegExp))
+    : file.match(pattern as RegExp);