vite-plugin-react-server 1.2.0-alpha.1 → 1.2.1

package/plugin/helpers/README.md

@@ -0,0 +1,112 @@
+# Plugin Helpers
+
+This directory contains reusable helper functions that support the `vite-plugin-react-server` architecture across different environments and contexts.
+
+## Architecture Overview
+
+The plugin supports multiple rendering scenarios:
+
+### Environments
+- **Client**: Static generation, build-time rendering
+- **Server**: Runtime rendering, SSR
+
+### Contexts  
+- **Main Thread**: Direct component access, immediate rendering
+- **Worker Thread**: Message-based communication, component loading
+
+### Component Resolution Strategies
+- **Direct**: Components passed directly (main thread)
+- **From Paths**: Components loaded from file paths (worker thread)
+- **Message-based**: Components requested via messages (distributed)
+
+## Core Patterns
+
+### 1. Main Thread vs. Worker Thread
+- **Main Thread**: Can access React components directly, immediate rendering
+- **Worker Thread**: Must load components from file paths, message-based communication
+
+### 2. Stream Piping
+- RSC streams flow from RSC generation to HTML transformation
+- Server: RSC Stream → HTML Worker → HTML Stream
+- Client: RSC Stream → Main Thread HTML Transform → HTML Stream
+
+### 3. Dual Consumption
+- Node.js streams can only be consumed once
+- Use `createBufferedRscStream` to allow multiple consumers
+- Pattern: Buffer → Multiple Consumers (RSC file + HTML transform)
+
+## Helper Functions
+
+### Message Validation & Processing
+- `validateRscRenderMessage()` - Validates RSC render message types
+- `resolveRenderUrl()` - Resolves URLs for render operations
+- `mergeMessageWithDefaults()` - Merges message values with defaults
+- `logRenderStart()` - Consistent logging across render contexts
+
+### Component Resolution
+- `resolveComponents()` - Resolves components with fallbacks (main thread)
+
+### Stream Handling
+- `createBufferedRscStream()` - Creates buffered streams for dual consumption
+
+### Serialization & Communication
+- `createSerializableHandlerOptions()` - Extracts serializable parts for worker communication
+
+
+## Usage Examples
+
+### Main Thread Rendering
+```typescript
+import { createMainThreadRenderHandler } from "../helpers/index.js";
+
+const result = await createMainThreadRenderHandler(
+  handlerOptions,
+  "client", // or "server"
+  { verbose: true, logger }
+);
+```
+
+### Worker Thread Rendering
+```typescript
+import { createWorkerThreadRenderHandler } from "../helpers/index.js";
+
+const result = await createWorkerThreadRenderHandler(
+  handlerOptions,
+  "client", // or "server"
+  { verbose: true, logger }
+);
+```
+
+
+
+### Buffered Stream for Dual Consumption
+```typescript
+import { createBufferedRscStream } from "../helpers/index.js";
+
+const bufferedStream = createBufferedRscStream(rscStream, {
+  route: "/",
+  logger,
+  verbose: true,
+});
+
+// Can be consumed multiple times
+bufferedStream.pipe(rscFileWriter);
+bufferedStream.pipe(htmlTransform);
+```
+
+## Key Insights
+
+1. **Environment Separation**: Client and server environments have different constraints and capabilities
+2. **Thread Model**: Main thread vs. worker thread determines component access patterns
+3. **Stream Limitations**: Node.js streams are single-consumer, requiring buffering for dual use
+4. **Serialization**: Only serializable data can be passed between threads
+5. **Component Loading**: Workers must load components from file paths, not direct references
+
+## Future Improvements
+
+- [ ] Add more comprehensive error handling across all helpers
+- [ ] Implement caching for component resolution
+- [ ] Add performance metrics collection
+- [ ] Create more specialized helpers for specific use cases
+- [ ] Improve type safety across all helper functions
+

package/plugin/helpers/collectManifestCss.ts

@@ -13,13 +13,32 @@ export function collectManifestCss(
   // Convert startFile to array and ensure we have valid file paths
   const toVisit = Array.isArray(startFile) ? startFile : [startFile];
 
+  // Helper function to find manifest entry by file property
+  const findManifestEntryByFile = (filePath: string) => {
+    for (const [key, value] of Object.entries(manifest)) {
+      if (value && typeof value === 'object' && 'file' in value && value.file === filePath) {
+        return { key, value };
+      }
+    }
+    return null;
+  };
   
   while (toVisit.length > 0) {
     const currentFile = toVisit.pop()!;
     if (visited.has(currentFile)) continue;
     visited.add(currentFile);
     
-    const fileInfo = manifest[currentFile];
+    // First try to find by key (for direct matches)
+    let fileInfo = manifest[currentFile];
+    
+    // If not found by key, try to find by file property
+    if (!fileInfo) {
+      const found = findManifestEntryByFile(currentFile);
+      if (found) {
+        fileInfo = found.value;
+      }
+    }
+    
     if (!fileInfo) {
       continue;
     }
@@ -42,10 +61,10 @@ export function collectManifestCss(
         // Add the import to visit
         toVisit.push(importPath);
         
-        // Check if the imported file has CSS
-        const importedFile = manifest[importPath];
-        if (importedFile?.css) {
-          for (const cssFile of importedFile.css) {
+        // Check if the imported file has CSS by finding it in the manifest
+        const importedEntry = findManifestEntryByFile(importPath);
+        if (importedEntry?.value.css) {
+          for (const cssFile of importedEntry.value.css) {
             cssInputs[cssFile] = cssFile;
           }
         }

package/plugin/helpers/collectViteModuleGraphCss.ts

@@ -1,8 +1,9 @@
-import type {
-  EnvironmentModuleGraph,
-  EnvironmentModuleNode,
-  ModuleGraph,
-  ModuleNode,
+import {
+  createLogger,
+  type EnvironmentModuleGraph,
+  type EnvironmentModuleNode,
+  type ModuleGraph,
+  type ModuleNode,
 } from "vite";
 import type {
   CreateHandlerOptions,
@@ -22,7 +23,7 @@ type CollectViteModuleGraphCssResult =
     }
   | {
       type: "error";
-      error: Error;
+      error: unknown;
       cssFiles?: never;
       metrics: {
         cssFiles: number;
@@ -48,6 +49,8 @@ export type CollectViteModuleGraphCssOptions = Pick<
   | "normalizer"
   | "moduleID"
   | "publicOrigin"
+  | "logger"
+  | "verbose"
 >;
 
 export type CollectViteModuleGraphCssFn = <
@@ -78,14 +81,56 @@ export const collectViteModuleGraphCss: CollectViteModuleGraphCssFn =
       normalizer,
       moduleID,
     } = handlerOptions;
-    if (!pagePath) return { type: "skip" };
+    const logger = handlerOptions.logger ?? createLogger  ();
+    const verbose = handlerOptions.verbose ?? false;
+    if(handlerOptions.verbose) {
+      logger.info(`Starting CSS collection for pagePath: ${pagePath}`);
+    }
+    
+    if (!pagePath) {        
+      if(verbose) {
+        logger.info(`No pagePath, skipping`);
+      }
+      return { type: "skip" };
+    }
 
     const cssFiles = new Map<string, CssContent>();
-    const pageModule = await moduleGraph.getModuleByUrl(pagePath, true);
+    if(verbose) {
+      logger.info(`Getting module by URL: ${pagePath}`);
+    }
+    
+    // Try multiple path formats since different module graphs use different URL schemes
+    let pageModule = await moduleGraph.getModuleByUrl(pagePath, true);
+    
+    // If not found, try with full path (server environment uses full paths)
+    if (!pageModule && projectRoot && !pagePath.startsWith('/')) {
+      const fullPath = `${projectRoot}/${pagePath}`;
+      if(verbose) {
+        logger.info(`Trying full path: ${fullPath}`);
+      }
+      pageModule = await moduleGraph.getModuleByUrl(fullPath, true);
+    }
+    
+    // Also try with leading slash
+    if (!pageModule && !pagePath.startsWith('/')) {
+      const slashPath = `/${pagePath}`;
+      if(verbose) {
+        logger.info(`Trying slash path: ${slashPath}`);
+      }
+      pageModule = await moduleGraph.getModuleByUrl(slashPath, true);
+    }
+    
     if (!pageModule) {
+      if(verbose) {
+        logger.info(`No page module found for any path variant, skipping`);
+      }
       return { type: "skip" };
     }
 
+    if(verbose) {
+      logger.info(`Page module found, starting walk`);
+    }
+
     const seen = new Set<string>();
     const processing = new Set<string>();
 
@@ -106,8 +151,15 @@ export const collectViteModuleGraphCss: CollectViteModuleGraphCssFn =
       }
 
       processing.add(mod.id);
+      if(verbose) {
+        logger.info(`Processing module: ${mod.id}`);
+      }
+      
       // Processing module
       if (mod.id.endsWith(".css")) {
+          if(verbose) {
+          logger.info(`Loading CSS module: ${mod.id}?inline`);
+        }
         const string = await loader(`${mod.id}?inline`).then(
           (m) => m?.["default"] ?? ""
         );
@@ -120,6 +172,9 @@ export const collectViteModuleGraphCss: CollectViteModuleGraphCssFn =
             `CSS module ${mod.id}?inline returned an empty string`
           );
         }
+        if(verbose) {
+          logger.info(`CSS loaded successfully: ${mod.id}`);
+        }
         const cssContent = createCssProps({
           id: mod?.id,
           code: string,
@@ -139,12 +194,18 @@ export const collectViteModuleGraphCss: CollectViteModuleGraphCssFn =
       }
 
       if (mod.importedModules) {
+        if(verbose) {
+          logger.info(`Processing imports for module: ${mod.id}`);
+        }
         // Processing imports for module
         const importedModules = Array.from(
           mod.importedModules?.values() as Iterable<
             ModuleNode | EnvironmentModuleNode
           >
-        );
+        );  
+        if(verbose) {
+          logger.info(`Found ${importedModules.length} imported modules`);
+        }
         // Found imported modules
         for (const importedMod of importedModules) {
           if (typeof importedMod === "object" && importedMod != null) {
@@ -168,8 +229,17 @@ export const collectViteModuleGraphCss: CollectViteModuleGraphCssFn =
     };
 
     try {
+      if(verbose) {
+        logger.info(`Starting module walk`);
+      }
       await walkModule(pageModule);
+      if(verbose) {
+        logger.info(`Module walk completed successfully`);
+      }
     } catch (error) {
+      if(verbose) {
+        logger.error(`Error during module walk: ${(error as Error)?.message ?? 'no message'}`);
+      }
       return {
         type: "error",
         error: error as Error,
@@ -179,6 +249,10 @@ export const collectViteModuleGraphCss: CollectViteModuleGraphCssFn =
         },
       };
     }
+    
+    if(verbose) {
+      logger.info(`CSS collection completed, found ${cssFiles.size} CSS files`);
+    }
     return {
       type: "success",
       cssFiles,

package/plugin/helpers/createBufferedRscStream.ts

@@ -0,0 +1,194 @@
+/**
+ * createBufferedRscStream.ts
+ * 
+ * PURPOSE: Creates a buffered RSC stream factory that can generate multiple readable streams
+ * 
+ * PROBLEM: Node.js streams can only be consumed once, but in client-side static generation
+ * we need to consume the RSC stream twice:
+ * 1. Write RSC content to index.rsc file
+ * 2. Transform RSC content to HTML for index.html file
+ * 
+ * SOLUTION: Buffer all RSC chunks and create a factory that can generate multiple
+ * readable streams from the same buffered data.
+ * 
+ * USAGE:
+ * ```typescript
+ * const bufferedStreamFactory = createBufferedRscStream(rscStream, {
+ *   route: "/",
+ *   logger: myLogger,
+ *   verbose: true
+ * });
+ * 
+ * // Create separate streams for each consumer
+ * const rscStream = bufferedStreamFactory.createStream();
+ * const htmlStream = bufferedStreamFactory.createStream();
+ * 
+ * // Can be piped to different destinations
+ * rscStream.pipe(rscFileWriter);
+ * htmlStream.pipe(htmlTransform);
+ * ```
+ */
+
+import { Readable } from "node:stream";
+
+export interface BufferedRscStreamOptions {
+  route: string;
+  logger?: any;
+  verbose?: boolean;
+}
+
+export interface BufferedRscStreamFactory {
+  createStream(): Readable;
+  getBufferInfo(): { chunks: number; bytes: number };
+}
+
+/**
+ * Creates a buffered RSC stream factory that can generate multiple readable streams
+ * 
+ * @param rscStream - The original RSC stream from the worker
+ * @param options - Configuration options
+ * @returns A factory that can create multiple readable streams from the same buffered data
+ */
+export function createBufferedRscStream(
+  rscStream: Readable,
+  options: BufferedRscStreamOptions
+): BufferedRscStreamFactory {
+  const { route, logger, verbose = false } = options;
+  
+  if (verbose) {
+    logger?.info(
+      `[createBufferedRscStream:${route}] Creating buffered RSC stream factory for dual consumption`
+    );
+  }
+
+  // Buffer to store all RSC chunks
+  const rscBuffer: Buffer[] = [];
+  let totalBytes = 0;
+  let isStreamEnded = false;
+  let hasError = false;
+  let error: Error | null = null;
+  const consumers: Readable[] = [];
+
+  // Collect all RSC chunks into buffer
+  rscStream.on("data", (chunk: Buffer) => {
+    if (hasError) return; // Don't buffer if there was an error
+    
+    rscBuffer.push(chunk);
+    totalBytes += chunk.length;
+    
+    if (verbose) {
+      logger?.info(
+        `[createBufferedRscStream:${route}] Buffered chunk: ${chunk.length} bytes, total: ${totalBytes} bytes`
+      );
+    }
+
+    // Push the chunk to all existing consumers immediately
+    for (const consumer of consumers) {
+      if (!consumer.destroyed) {
+        consumer.push(chunk);
+      }
+    }
+  });
+
+  rscStream.on("end", () => {
+    isStreamEnded = true;
+    if (verbose) {
+      logger?.info(
+        `[createBufferedRscStream:${route}] RSC stream ended, buffered ${rscBuffer.length} chunks (${totalBytes} bytes)`
+      );
+    }
+
+    // End all consumers
+    for (const consumer of consumers) {
+      if (!consumer.destroyed) {
+        consumer.push(null);
+      }
+    }
+  });
+
+  rscStream.on("error", (streamError: Error) => {
+    hasError = true;
+    error = streamError;
+    if (verbose) {
+      logger?.error(
+        `[createBufferedRscStream:${route}] RSC stream error: ${streamError.message}`
+      );
+    }
+
+    // Emit error on all consumers
+    for (const consumer of consumers) {
+      if (!consumer.destroyed) {
+        consumer.emit("error", streamError);
+      }
+    }
+  });
+
+  return {
+    createStream(): Readable {
+      if (hasError && error) {
+        // If there was an error, create a stream that immediately emits the error
+        const errorStream = new Readable();
+        setImmediate(() => {
+          errorStream.emit("error", error);
+        });
+        return errorStream;
+      }
+
+      const consumer = new Readable({
+        read() {
+          if (verbose) {
+            logger?.info(
+              `[createBufferedRscStream:${route}] Read requested, buffered chunks: ${rscBuffer.length}, isStreamEnded: ${isStreamEnded}`
+            );
+          }
+
+          // If the stream has already ended, push all remaining buffered content
+          if (isStreamEnded) {
+            // Push all buffered content that hasn't been pushed yet
+            for (const chunk of rscBuffer) {
+              this.push(chunk);
+            }
+            
+            // End the stream
+            this.push(null);
+            
+            if (verbose) {
+              logger?.info(
+                `[createBufferedRscStream:${route}] Pushed ${rscBuffer.length} chunks, ending stream`
+              );
+            }
+          }
+          // If the stream hasn't ended yet, we'll push chunks as they arrive via the 'data' event
+        }
+      });
+
+      // Add this consumer to the list
+      consumers.push(consumer);
+
+      // If the stream has already ended, push all buffered content immediately
+      if (isStreamEnded) {
+        for (const chunk of rscBuffer) {
+          consumer.push(chunk);
+        }
+        consumer.push(null);
+      }
+
+      // Clean up when the consumer is destroyed
+      consumer.on("close", () => {
+        const index = consumers.indexOf(consumer);
+        if (index > -1) {
+          consumers.splice(index, 1);
+        }
+      });
+
+      return consumer;
+    },
+
+    getBufferInfo() {
+      return {
+        chunks: rscBuffer.length,
+        bytes: totalBytes
+      };
+    }
+  };
+}

package/plugin/helpers/createCssProps.tsx

@@ -46,7 +46,7 @@ export const createCssProps = ({
   let inline =
     css?.inlineCss !== false &&
     typeof code === "string" &&
-    code.length > (css?.inlineThreshold ?? DEFAULT_CONFIG.CSS.inlineThreshold);
+    (css?.inlineThreshold === 0 || code.length <= (css?.inlineThreshold ?? DEFAULT_CONFIG.CSS.inlineThreshold));
   // Normalize the ID to be relative to src/
   const [, value] = userOptions.normalizer(id);
   const moduleID = userOptions?.moduleID?.(value) ?? value;
@@ -78,7 +78,25 @@ export const createCssProps = ({
         : {}),
     } as CssContent<boolean>;
   }
-  
+  const normalModuleBaseURL = !moduleID.startsWith(userOptions.moduleBaseURL)
+    ? userOptions.moduleBaseURL +
+      moduleID.slice(
+        Number(
+          moduleID.startsWith("/") && userOptions.moduleBaseURL.endsWith("/")
+        )
+      )
+    : moduleID;
+  const normalOrigin = !userOptions.moduleBaseURL.startsWith(
+    userOptions.publicOrigin
+  )
+    ? userOptions.publicOrigin +
+      userOptions.moduleBaseURL.slice(
+        Number(
+          userOptions.publicOrigin.endsWith("/") &&
+            userOptions.moduleBaseURL.startsWith("/")
+        )
+      )
+    : userOptions.moduleBaseURL;
   // Default case
   return {
     id: moduleID,
@@ -86,23 +104,8 @@ export const createCssProps = ({
     rel: "stylesheet",
     href:
       userOptions.publicOrigin !== ""
-        ? new URL(
-            userOptions.moduleBaseURL +
-              moduleID.slice(
-                Number(
-                  moduleID.startsWith("/") &&
-                    userOptions.moduleBaseURL.endsWith("/")
-                )
-              ),
-            userOptions.publicOrigin +
-              userOptions.moduleBaseURL.slice(
-                Number(
-                  userOptions.publicOrigin.endsWith("/") &&
-                    userOptions.moduleBaseURL.startsWith("/")
-                )
-              )
-          ).href
-        : moduleID,
+        ? new URL(normalModuleBaseURL, normalOrigin).href
+        : normalModuleBaseURL,
     precedence: "high",
   } as CssContent<boolean>;
 };

package/plugin/helpers/createElementWithReact.tsx

@@ -0,0 +1,121 @@
+import { createLogger } from "vite";
+import type { CreateHandlerOptions } from "../types.js";
+
+export type CreateElementWithReactOptions = Pick<
+  CreateHandlerOptions,
+  | "HtmlComponent"
+  | "PageComponent"
+  | "RootComponent"
+  | "pageProps"
+  | "moduleBase"
+  | "moduleRootPath"
+  | "moduleBasePath"
+  | "moduleBaseURL"
+  | "cssFiles"
+  | "globalCss"
+  | "route"
+  | "manifest"
+  | "projectRoot"
+  | "url"
+  | "as"
+> &
+  Partial<Pick<CreateHandlerOptions, "verbose" | "logger">>;
+
+export type CreateElementWithReactFN = <
+  R extends {
+    Fragment: any;
+    use: any;
+    isValidElement: (element: any) => boolean;
+  },
+  ReturnType = React.ReactElement,
+  Opt extends CreateElementWithReactOptions = CreateElementWithReactOptions
+>(
+  React: R,
+  options: Opt
+) => ReturnType;
+
+export const createElementWithReact: CreateElementWithReactFN =
+  function _createElementWithReact(
+    React,
+    {
+      HtmlComponent,
+      PageComponent,
+      RootComponent,
+      pageProps,
+      moduleBase,
+      moduleBaseURL,
+      moduleBasePath,
+      moduleRootPath,
+      cssFiles = new Map(),
+      globalCss = new Map(),
+      route,
+      manifest,
+      projectRoot,
+      url,
+      as = "div",
+      verbose = false,
+      logger = createLogger("info", {
+        prefix: "vite:plugin-react-server/helpers/createElementWithReact",
+      }),
+    }
+  ) {
+    // Add debug logging
+    if (verbose) {
+      logger?.info(
+        `[createElementWithReact] Creating element for route: ${route}`
+      );
+      logger?.info(
+        `[createElementWithReact] CSS files: ${cssFiles?.size || 0} files`
+      );
+      logger?.info(
+        `[createElementWithReact] Global CSS: ${globalCss?.size || 0} files`
+      );
+    }
+
+    if (
+      HtmlComponent != null &&
+      HtmlComponent !== React.Fragment &&
+      HtmlComponent !== undefined
+    ) {
+      if (verbose) {
+        logger?.info(`[createElementWithReact] Returning Full HTML structure`);
+      }
+      return (
+        <HtmlComponent
+          moduleBase={moduleBase}
+          moduleBaseURL={moduleBaseURL}
+          moduleBasePath={moduleBasePath}
+          moduleRootPath={moduleRootPath}
+          projectRoot={projectRoot}
+          url={url || ""}
+          route={route}
+          pageProps={pageProps}
+          cssFiles={cssFiles}
+          globalCss={globalCss}
+          Root={RootComponent ? RootComponent : React.Fragment}
+          manifest={manifest}
+          Page={PageComponent ? PageComponent : React.Fragment}
+          as={as}
+        />
+      ) as never;
+    } else if (RootComponent != null && RootComponent !== React.Fragment) {
+      if (verbose) {
+        logger?.info(`[createElementWithReact] Returning Root only`);
+      }
+      return (
+        <RootComponent
+          key={route}
+          as={React.Fragment}
+          cssFiles={cssFiles}
+          pageProps={pageProps}
+          Page={PageComponent ? PageComponent : React.Fragment}
+        />
+      ) as never;
+    } else if (PageComponent != null && PageComponent !== React.Fragment) {
+      if (verbose) {
+        logger?.info(`[createElementWithReact] Returning Page only`);
+      }
+      return (<PageComponent {...pageProps} />) as never;
+    }
+    return null as never;
+  };