vite-plugin-react-server 1.0.2 → 1.1.0

package/plugin/react-static/renderPage.ts

@@ -0,0 +1,151 @@
+import { createRenderMetrics } from "../helpers/metrics.js";
+import { resolvePageAndProps } from "../helpers/resolvePageAndProps.js";
+import type { CreateHandlerOptions, RenderPageResult } from "../types.js";
+import { renderStreams } from "./renderStreams.js";
+import { collectHtmlWorkerContent } from "./collectHtmlWorkerContent.js";
+import { collectRscContent } from "./collectRscContent.js";
+
+export async function* renderPage(
+  handlerOptions: CreateHandlerOptions<unknown, React.ComponentType<unknown>>
+): AsyncGenerator<RenderPageResult, void, unknown> {
+  if (!handlerOptions.pagePath) {
+    yield {
+      type: "skip",
+    };
+    return;
+  }
+
+  try {
+    const metrics = createRenderMetrics(handlerOptions.route);
+
+    const pageAndPropsResult = await resolvePageAndProps(handlerOptions);
+
+    if (pageAndPropsResult.type === "error") {
+      yield {
+        type: "error",
+        error: pageAndPropsResult.error,
+      };
+      return;
+    }
+
+    if (pageAndPropsResult.type === "skip") {
+      yield {
+        type: "skip",
+      };
+      return;
+    }
+
+    const { PageComponent, pageProps } = pageAndPropsResult;
+
+    const newHandlerOptions = {
+      ...handlerOptions,
+      PageComponent: PageComponent,
+      pageProps: pageProps,
+    } satisfies CreateHandlerOptions;
+    // Create streams with CSS files
+    const [rscFull, rscHeadless] = await renderStreams(newHandlerOptions);
+
+    // Handle stream creation errors
+    if (rscFull.type !== "success") {
+      yield {
+        type: "error",
+        error: new Error(
+          rscFull.type === "error"
+            ? `Failed to create RSC full stream: ${
+                rscFull.error instanceof Error
+                  ? rscFull.error.message
+                  : String(rscFull.error)
+              }`
+            : "RSC full stream creation was skipped"
+        ),
+      };
+      return;
+    }
+
+    if (!rscFull.stream) {
+      yield {
+        type: "error",
+        error: new Error("RSC full stream is undefined"),
+      };
+      return;
+    }
+
+    if (rscHeadless.type !== "success") {
+      yield {
+        type: "error",
+        error: new Error(
+          rscHeadless.type === "error"
+            ? `Failed to create RSC headless stream: ${
+                rscHeadless.error instanceof Error
+                  ? rscHeadless.error.message
+                  : String(rscHeadless.error)
+              }`
+            : "RSC headless stream creation was skipped"
+        ),
+      };
+      return;
+    }
+
+    if (!rscHeadless.stream) {
+      yield {
+        type: "error",
+        error: new Error("RSC headless stream is undefined"),
+      };
+      return;
+    }
+
+    // Collect HTML and RSC content
+    const [
+      { stream: rscStream, metrics: rscMetrics },
+      { stream: htmlStream, metrics: htmlMetrics },
+    ] = await Promise.all([
+      collectRscContent(rscHeadless.stream, handlerOptions),
+      collectHtmlWorkerContent(rscFull.stream, handlerOptions),
+    ]);
+
+    // Update metrics
+    metrics.htmlSizes.set(handlerOptions.route, htmlMetrics.bytes);
+    metrics.rscSizes.set(handlerOptions.route, rscMetrics.bytes);
+    metrics.htmlSize = htmlMetrics.bytes;
+    metrics.rscSize = rscMetrics.bytes;
+
+    // Combine metrics from both streams
+    metrics.streamMetrics = {
+      ...htmlMetrics,
+      chunks: Math.max(htmlMetrics.chunks, rscMetrics.chunks),
+      bytes: Math.max(htmlMetrics.bytes, rscMetrics.bytes),
+      duration: Math.max(htmlMetrics.duration, rscMetrics.duration),
+      startTime: Math.min(htmlMetrics.startTime, rscMetrics.startTime),
+    };
+
+    metrics.processingTime = metrics.streamMetrics.duration;
+    metrics.chunks = metrics.streamMetrics.chunks;
+    metrics.chunkRate =
+      metrics.streamMetrics.chunks / (metrics.processingTime / 1000);
+
+    // Emit metrics via callback
+    if (handlerOptions.onMetrics) {
+      handlerOptions.onMetrics(metrics);
+    }
+
+    yield {
+      type: "success",
+      html: htmlStream,
+      rsc: rscStream,
+      metrics: {
+        rscFull: htmlMetrics,
+        rscHeadless: rscMetrics,
+      },
+    } as const;
+  } catch (err) {
+    yield {
+      type: "error",
+      error:
+        err instanceof Error
+          ? err
+          : typeof err === "string"
+          ? new Error(err)
+          : (err as Error),
+    };
+  }
+}

package/plugin/react-static/renderPages.ts

@@ -0,0 +1,154 @@
+/**
+ * renderPages.ts
+ *
+ * PURPOSE: Processes React Server Components (RSC) streams and writes output files
+ *
+ * This module:
+ * 1. Creates RSC and HTML streams for each route
+ * 2. Pipes RSC stream directly to .rsc files
+ * 3. Transforms RSC to HTML via worker and pipes to .html files
+ * 4. Collects metrics and handles errors
+ */
+import { createRenderMetrics } from "../helpers/metrics.js";
+import { renderPage } from "./renderPage.js";
+import { PassThrough } from "node:stream";
+import type { StreamMetrics, RenderPagesResult, AutoDiscoveredFiles, CssContent, MultiPageHandlerOptions } from "../types.js";
+
+export async function* renderPages(
+  autoDiscoveredFiles: AutoDiscoveredFiles,
+  handlerOptions: MultiPageHandlerOptions,
+  cssFilesByPage: Map<string, Map<string, CssContent>>,
+): AsyncGenerator<RenderPagesResult, RenderPagesResult, unknown> {
+  const routes = Array.from(autoDiscoveredFiles.urlMap.keys());
+  const completedRoutes = new Set<string>();
+  const failedRoutes = new Set<string>();
+  const baseMetrics = createRenderMetrics(routes[0]);
+  const results = new Map<
+    string,
+    {
+      html: PassThrough;
+      rsc: PassThrough;
+      metrics: {
+        rscFull: StreamMetrics;
+        rscHeadless: StreamMetrics;
+      };
+    }
+  >();
+  const errors: Error[] = [];
+
+  if (!autoDiscoveredFiles.urlMap) {
+    throw new Error("No urlMap provided to renderPages");
+  }
+
+  for (const route of routes) {
+    const { page, props } = autoDiscoveredFiles.urlMap.get(route) || {};
+    if (!page) continue;
+
+    try {
+      const pageRenderer = renderPage({
+        ...handlerOptions,
+        route,
+        pagePath: page,
+        propsPath: props,
+        cssFiles: cssFilesByPage.get(route) ?? new Map(),
+      });
+
+      for await (const result of pageRenderer) {
+        if (result.type === "skip") continue;
+
+        if (result.type === "error") {
+          failedRoutes.add(route);
+          errors.push(result.error);
+          yield {
+            type: "error",
+            error: result.error,
+            failedRoutes,
+            completedRoutes,
+            htmlSizes: baseMetrics.htmlSizes,
+            rscSizes: baseMetrics.rscSizes,
+            streamMetrics: baseMetrics.streamMetrics,
+            results,
+          } as const;
+          continue;
+        }
+
+        if (result.type === "success") {
+          completedRoutes.add(route);
+          results.set(route, {
+            html: result.html,
+            rsc: result.rsc,
+            metrics: result.metrics,
+          });
+
+          // Update metrics
+          baseMetrics.htmlSizes.set(route, result.metrics.rscFull.bytes);
+          baseMetrics.rscSizes.set(route, result.metrics.rscHeadless.bytes);
+          baseMetrics.streamMetrics = {
+            ...baseMetrics.streamMetrics,
+            chunks: Math.max(
+              baseMetrics.streamMetrics.chunks,
+              result.metrics.rscFull.chunks
+            ),
+            bytes: Math.max(
+              baseMetrics.streamMetrics.bytes,
+              result.metrics.rscFull.bytes
+            ),
+            duration: Math.max(
+              baseMetrics.streamMetrics.duration,
+              result.metrics.rscFull.duration
+            ),
+            startTime: Math.min(
+              baseMetrics.streamMetrics.startTime,
+              result.metrics.rscFull.startTime
+            ),
+          };
+
+          yield {
+            type: "success",
+            completedRoutes,
+            htmlSizes: baseMetrics.htmlSizes,
+            rscSizes: baseMetrics.rscSizes,
+            streamMetrics: baseMetrics.streamMetrics,
+            results,
+          } as const;
+        }
+      }
+    } catch (err) {
+      failedRoutes.add(route);
+      errors.push(err instanceof Error ? err : new Error(String(err)));
+      yield {
+        type: "error",
+        error: err instanceof Error ? err : new Error(String(err)),
+        failedRoutes,
+        completedRoutes,
+        htmlSizes: baseMetrics.htmlSizes,
+        rscSizes: baseMetrics.rscSizes,
+        streamMetrics: baseMetrics.streamMetrics,
+        results,
+      } as const;
+    }
+  }
+
+  if (failedRoutes.size > 0) {
+    return {
+      type: "error",
+      error: errors[0],
+      failedRoutes,
+      completedRoutes,
+      htmlSizes: baseMetrics.htmlSizes,
+      rscSizes: baseMetrics.rscSizes,
+      streamMetrics: baseMetrics.streamMetrics,
+      results,
+    } as const;
+  }
+
+  return {
+    type: "success",
+    completedRoutes,
+    failedRoutes: undefined,
+    htmlSizes: baseMetrics.htmlSizes,
+    rscSizes: baseMetrics.rscSizes,
+    streamMetrics: baseMetrics.streamMetrics,
+    results,
+  } as const;
+}

package/plugin/react-static/renderStreams.ts

@@ -0,0 +1,48 @@
+/**
+ * renderStreams.ts
+ * 
+ * PURPOSE: Creates specialized streams for React Server Components (RSC) rendering
+ * 
+ * This module:
+ * 1. Creates RSC stream (React.Fragment wrapper) for client-side navigation
+ *    - This stream is saved to .rsc files and used when navigating between pages
+ *    - The Fragment wrapper allows the browser to update only the necessary parts of the DOM
+ *    - This is more efficient than reloading the entire HTML document
+ * 2. Creates Document stream (Html wrapper) for initial page loads
+ *    - This stream includes the full HTML document structure
+ *    - Used for the initial page load when the browser needs the complete HTML
+ * 3. Sets up stream handlers with proper wrappers and options
+ * 4. Returns streams for renderPages to process
+ */
+import { createHandler } from "../helpers/createHandler.js";
+import type {
+  CreateHandlerOptions,
+} from "../types.js";
+import React from "react";
+
+/**
+ * Creates handlers for both document and RSC streams
+ * 
+ * @param handler The handler options for creating streams
+ * @param options The render options
+ * @returns A tuple containing the document worker result and RSC direct result
+ */
+export function renderStreams(
+  handler: CreateHandlerOptions,
+) {
+  return Promise.all([
+    /**
+     * This stream goes to the document worker for client side rendering with full HTML structure, 
+     * links are already bubbled up in the static document which required us 
+     * to include the head in the stream as well
+     */
+    createHandler(handler),
+    
+    /**
+     * This stream is saved to index.rsc file (if configured) and can be used 
+     * for navigating to pages (without the Html wrapper, but does contain 
+     * css/head information that can bubble up to the browser's dom)
+     */
+    createHandler({...handler, Html: React.Fragment}),
+  ]);
+}

package/plugin/react-static/rscToHtmlStream.ts

@@ -0,0 +1,85 @@
+/**
+ * rscToHtmlStream.ts
+ *
+ * PURPOSE: Transforms RSC stream to HTML stream via worker communication
+ *
+ * This module:
+ * 1. Takes RSC stream as input
+ * 2. Communicates with worker to transform RSC to HTML
+ * 3. Returns a writeable stream of HTML content
+ * 4. Handles worker message processing and error cases
+ */
+
+import { Transform } from "node:stream";
+import type {
+  HtmlWorkerInputMessage,
+} from "../worker/types.js";
+import type { CreateHandlerOptions } from "../types.js";
+import type { Worker } from "node:worker_threads";
+import type { ViteDevServer } from "vite";
+
+export type RscToHtmlOptions = Pick<
+  CreateHandlerOptions,
+  | "worker"
+  | "route"
+  | "moduleRootPath"
+  | "moduleBaseURL"
+  | "pipeableStreamOptions"
+  | "build"
+  | "cssFiles"
+  | "projectRoot"
+>;
+
+/**
+ * Creates a transform stream that converts RSC content to HTML via worker
+ *
+ * @param options The options for RSC to HTML transformation
+ * @returns A transform stream that outputs HTML content
+ */
+export function createRscToHtmlStream(options: RscToHtmlOptions): Transform {
+  const worker = options.worker as Worker | ViteDevServer;
+  if (!("postMessage" in worker)) {
+    throw new Error("Worker is not a valid worker");
+  }
+  let sequence = 0;
+  const stream = new Transform({
+    transform(chunk, _encoding, callback) {
+      try {
+        worker.postMessage({
+          type: "RSC_CHUNK",
+          id: options.route,
+          chunk,
+          sequence: sequence++,
+        } satisfies HtmlWorkerInputMessage);
+        callback();
+      } catch (error) {
+        callback(error as Error);
+      }
+    },
+    flush(callback) {
+      try {
+        worker.postMessage({
+          type: "RSC_END",
+          id: options.route,
+        } satisfies HtmlWorkerInputMessage);
+        callback();
+      } catch (error) {
+        callback(error as Error);
+      }
+    },
+  });
+
+  // Signal ready to receive HTML
+  worker.postMessage({
+    type: "ROUTE_READY",
+    id: options.route,
+    // replace server with client
+    moduleRootPath: options.moduleRootPath,
+    moduleBaseURL: options.moduleBaseURL,
+    cssFiles: options.cssFiles,
+    pipeableStreamOptions: options.pipeableStreamOptions,
+    projectRoot: options.projectRoot,
+  } satisfies HtmlWorkerInputMessage);
+
+  return stream;
+}

package/plugin/react-static/types.ts

@@ -1,3 +1,13 @@
+import type { FileWriteEvent } from "../types.js";
+
 export type ReactStaticPluginOptions = {
   
+};
+
+export type ReactStaticEvent = FileWriteEvent | {
+  type: 'build.start';
+  data: {
+    pages: string[];
+    files: Array<[string, { page: string; props?: string }]>;
+  };
 };

package/plugin/resolvePage.ts

@@ -1,74 +1,84 @@
-import { stashedPages } from "./config/resolvePages.js";
 
-type ResolvePageOptions = {
-  pageModule: Record<string, any>;
-  path: string;
-  url: string;
-  exportName: string;
+type ResolvePageOptions<N extends string> = {
+  id: string;
+  exportName: N;
+  loader: (id: string) => Promise<any>;
 };
 
-type ResolvePageResult =
-  | { type: "success"; key: string; Page: any }
+type ResolvePageResult<T, N extends string> =
+  | { type: "success"; Page: T; module: { [key in N]: T } }
   | { type: "error"; error: Error }
   | { type: "skip" };
 
-export async function resolvePage({
-  pageModule,
-  path,
-  url,
+/**
+ * Resolves a page component from a module.
+ *
+ * During development (ssrLoadModule):
+ * - Real modules have exports available directly on the module object
+ * - Virtual modules have exports stored in temporaryReferences
+ * 
+ * @param options.id - The module ID to resolve
+ * @param options.exportName - The name of the export to resolve (e.g. 'Page')
+ * @param options.loader - The loader function to use for loading the module
+ *
+ * @returns A result object containing:
+ *   - type: "success" | "error" | "skip"
+ *   - Page: The resolved page component if successful
+ *   - error: Error message if failed
+ */
+export const resolvePage = async <T, N extends string>({
+  id,
   exportName,
-}: ResolvePageOptions): Promise<ResolvePageResult> {
-  if(stashedPages.length > 0 && stashedPages.includes(path)){
-    return {
-      type: "success",
-      key: path,
-      Page: pageModule,
-    }
-  }
-  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") {
+  loader,
+}: ResolvePageOptions<N>): Promise<ResolvePageResult<T, N>> => {
+  // Check if this is a stashed page that needs special handling
+  const pageLoadResult = await (async (): Promise<
+    | { type: "success"; key: string; module: { [key in N]: T } }
+    | { type: "error"; error: Error; module?: never }
+  > => {
+    try {
       return {
         type: "success",
-        key: found,
-        Page: pageModule[found],
+        key: id,
+        module: await loader(id),
       };
-    } else {
-      if (
-        typeof pageModule === "object" &&
-        pageModule != null &&
-        Object.keys(pageModule).includes("type")
-      )
-        return pageModule as ResolvePageResult;
+    } catch (error) {
       return {
         type: "error",
-        [exportName]: () => found,
-        error: pageModule[found]["error"],
+        error: error instanceof Error ? error : new Error(String(error)),
       };
     }
+  })();
+
+  if (pageLoadResult.type !== "success") {
+    return pageLoadResult;
+  }
+  const { module } = pageLoadResult;
+  const Page = module[exportName as N];
+  if (module instanceof Error) {
+    return {
+      type: "error",
+      error: module,
+    };
+  } else if (!(exportName in module)) {
+    return {
+      type: "error",
+      error: new Error(`Export ${exportName} not found in module ${id}`),
+    };
+  } else if (!Page) {
+    return {
+      type: "error",
+      error: new Error(`Export ${exportName} is null or undefined in module ${id}`),
+    };
+  } else if (Page instanceof Error) {
+    return {
+      type: "error",
+      error: Page,
+    };
   }
-  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. \"" + JSON.stringify(pageModule) + "\""
-          : "typeof pageModule =" + typeof pageModule
-      }`,
-      { cause: pageModule }
-    ),
+    type: "success",
+    Page,
+    module: module as { [key in N]: T },
   };
-}
+};