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

package/plugin/worker/rsc/README.md

@@ -2,12 +2,17 @@
 
 The RSC worker is used by the client plugin to handle React Server Components when the main thread is running without the `react-server` condition. It provides the server-condition capabilities that the client plugin needs but can't access directly.
 
+> **Part of**: [Vite React Server Plugin](../../../README.md)  
+> **Documentation**: [Plugin Architecture Overview](../../../docs/README.md#plugin-architecture-documentation)
+
 ## Purpose
 
 The RSC worker serves several key functions:
 
 1. **Server Condition Access**: Enables RSC processing in a client-focused environment
 2. **Message-Based Communication**: Handles RSC streaming through a message passing interface
+3. **Context Isolation**: Provides a clean environment for server-side React processing
+4. **Streaming Support**: Handles RSC chunk processing and streaming responses
 
 ## Implementation Details
 
@@ -16,6 +21,22 @@ The worker comes in two variants:
 - `rsc-worker.development.ts`: Full implementation with detailed logging and error handling
 - `rsc-worker.production.ts`: Optimized implementation for production builds
 
+### Message Types
+
+The worker handles several message types:
+
+- `RSC_RENDER`: Renders React Server Components
+- `SERVER_ACTION`: Executes server actions
+- `CLEANUP`: Cleans up worker resources
+
+### State Management
+
+The worker maintains state for:
+- Active render requests
+- Server action handlers
+- Streaming connections
+- Error boundaries
+
 ## Extending the Worker
 
 Users can create their own RSC workers for application-level use. This allows for:
@@ -42,6 +63,130 @@ if (typeof WorkerGlobalScope !== 'undefined') {
 }
 ```
 
+## ⚠️ Advanced Configuration: Custom Loader Paths
+
+> **Warning**: These are escape hatches for advanced users. Most users should NOT use these options as they can break React Server Components, CSS processing, or environment handling, during the rsc-worker development workflow.
+
+The RSC worker supports custom loader paths that allow you to completely replace the core loading mechanisms:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from "vite";
+import { vitePluginReactServer } from "vite-plugin-react-server";
+
+export default defineConfig({
+  plugins: [
+    vitePluginReactServer({
+      // ⚠️ EXPERIMENTAL: Custom loader paths
+      reactLoaderPath: "./custom-loaders/my-react-loader.js",  // Replaces React loading
+      cssLoaderPath: "./custom-loaders/my-css-loader.js",      // Replaces CSS processing  
+      envLoaderPath: "./custom-loaders/my-env-loader.js",      // Replaces environment handling
+      
+      // Legacy general loader path (discouraged)
+      loaderPath: "./custom-loaders/react-loader.js",
+    }),
+  ],
+});
+```
+
+### Custom React Loader Example
+
+```js
+// custom-loaders/my-react-loader.js
+/**
+ * ⚠️ ADVANCED: Custom React loader
+ * This replaces the entire React loading mechanism
+ * Use at your own risk - may break RSC functionality!
+ */
+
+export function load(url, context, nextLoad) {
+  if (url === 'react' || url.startsWith('react/')) {
+    console.log('🚨 Intercepting React import:', url);
+    // Could redirect to different React build, but likely to break RSC
+    // return nextLoad('react@experimental', context);
+  }
+  
+  return nextLoad(url, context);
+}
+```
+
+### Custom CSS Loader Example
+
+```js
+// custom-loaders/my-css-loader.js
+/**
+ * ⚠️ ADVANCED: Custom CSS processing
+ * This replaces the built-in CSS handling
+ */
+
+export async function load(url, context, nextLoad) {
+  if (url.endsWith('.css')) {
+    console.log('🎨 Custom CSS processing:', url);
+    
+    const source = await fetch(url).then(r => r.text());
+    const processed = await customCssProcessor(source);
+    
+    return {
+      format: 'module',
+      source: `export default ${JSON.stringify(processed)}`,
+      shortCircuit: true
+    };
+  }
+  
+  return nextLoad(url, context);
+}
+
+async function customCssProcessor(css) {
+  // Your custom CSS processing logic
+  return css.replace(/\/\*.*?\*\//g, ''); // Remove comments
+}
+```
+
+### Why These May Not Work As Expected
+
+These custom loader paths:
+
+1. **Break RSC Integration**: The plugin expects specific loader behavior for React Server Components to work correctly
+2. **Bypass Safety Checks**: Built-in loaders handle React conditions, serialization, and worker communication
+3. **Can Cause Compatibility Issues**: Different React builds or processing might break streaming and component registration
+4. **Are Undocumented Internal APIs**: These APIs may change without notice and could destabilize the plugin
+
+### Safer Alternatives
+
+Instead of completely replacing loaders, consider these safer customization options:
+
+```typescript
+// vite.config.ts - Safer customization
+export default defineConfig({
+  plugins: [
+    vitePluginReactServer({
+      // Customize loader behavior safely
+      loader: {
+        importServerPath: "my-server-imports",
+        importClientPath: "my-client-imports", 
+        registerServerReferenceName: "myRegisterServer",
+        registerClientReferenceName: "myRegisterClient",
+      },
+      
+      // Custom CSS processing
+      css: {
+        inlineCss: true,
+        inlineThreshold: 1024,
+      },
+      
+      // Event hooks for monitoring/customization
+      onEvent: (event) => {
+        if (event.type === 'css.process') {
+          console.log('CSS processed:', event.data);
+        }
+      },
+    }),
+  ],
+});
+```
+
+These safer alternatives provide customization without replacing core functionality.
+
 ## Future Possibilities
 
 The RSC worker architecture is designed to be extensible. Future enhancements could include:
@@ -55,4 +200,61 @@ The RSC worker architecture is designed to be extensible. Future enhancements co
 
 - The worker must be initialized with appropriate Node conditions
 - Message handling must account for streaming data
-- Consider memory usage when processing large RSC payloads 
+- Consider memory usage when processing large RSC payloads 
+
+### Example: Restoring Default React Server Components Loader
+
+Here's how you can restore the default `@react-server-dom-esm-node-loader.production.js` behavior as a custom hook:
+
+```javascript
+// custom-react-loader.js
+import { transformSource } from 'react-server-dom-esm/node-loader';
+
+/**
+ * Custom React loader that restores default RSC behavior
+ * Just delegates to the official React Server Components loader
+ */
+export const load = async (url, context, defaultLoad) => {
+  // First load the file using the default loader
+  const result = await defaultLoad(url, context);
+  
+  // If it's not a module or source isn't a string, return as-is
+  if (result.format !== 'module' || typeof result.source !== 'string') {
+    return result;
+  }
+
+  // Use the official React Server Components transformSource function
+  const transformed = await transformSource(result.source, context, (source, ctx) => ({ source }));
+  
+  return {
+    format: "module",
+    source: transformed.source,
+    shortCircuit: true
+  };
+};
+```
+
+**Usage:**
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  plugins: [
+    react(),
+    reactServer({
+      reactLoaderPath: './custom-react-loader.js'
+    })
+  ]
+})
+```
+
+This custom loader:
+1. **Accepts string source code** (as you mentioned)
+2. **Parses for "use client"/"use server" directives**
+3. **Transforms client modules** to register client references  
+4. **Transforms server modules** to register server references
+5. **Maintains the same behavior** as the default React loader
+
+The key requirement you mentioned is correct - the source must be a string, and this loader handles that properly while replicating the core RSC transformation logic.
+
+// ... existing code ... 

package/plugin/worker/rsc/handleRender.ts

@@ -1,27 +1,36 @@
-import { resolvePageAndProps } from "../../helpers/resolvePageAndProps.js";
-import type { RscRenderMessage, StreamHandlers } from "../types.js";
+import { resolveComponents } from "../../helpers/resolveComponents.js";
+import type { RscRenderMessage } from "./types.js";
+import type { StreamHandlers } from "../types.js";
 import { activeStreams, cssFiles } from "./state.js";
 import { createRscStream } from "../../helpers/createRscStream.js";
-import { CssCollector } from "../../components/css-collector.js";
 import { PassThrough } from "node:stream";
 import { join } from "node:path";
 import { workerData } from "node:worker_threads";
-import { React } from "../../vendor/vendor.server.js";
 import { hmrState } from "./state.js";
 import { performance } from "node:perf_hooks";
-import type { PagePropOpt } from "../../types.js";
+import type { BuildModuleLoader, ResolvedUserOptions } from "../../types.js";
+import React from "react";
+import { routeToURL } from "../../utils/routeToURL.js";
+import { createLogger, type Logger} from "vite";
 
-export async function handleRender<
-  T extends PagePropOpt = PagePropOpt
->(
-  msg: RscRenderMessage<T>,
-  handlers: StreamHandlers
+export type HandleRenderFn = <Msg extends RscRenderMessage = RscRenderMessage>(
+  msg: Msg,
+  handlers: StreamHandlers,
+  logger: Logger
+) => Promise<void>;
+
+export const handleRender: HandleRenderFn = async function _handleRender(
+  msg,
+  handlers,
+  logger = createLogger()
 ) {
-  let {
-    id = workerData.id,
-    route = workerData.route,
-    pagePath = workerData.pagePath,
-    propsPath = workerData.propsPath,
+  const {
+    id,
+    route,
+    pagePath,
+    propsPath,
+    rootPath,
+    htmlPath,
     pageExportName = workerData.userOptions.pageExportName,
     propsExportName = workerData.userOptions.propsExportName,
     projectRoot = workerData.userOptions.projectRoot,
@@ -31,41 +40,58 @@ export async function handleRender<
     moduleBase = workerData.userOptions.moduleBase,
     pipeableStreamOptions = workerData.userOptions.pipeableStreamOptions,
     cssFiles: messageCssFiles,
-    globalCss = workerData.globalCss,
+    globalCss,
+    verbose = workerData.userOptions.verbose,
+    build = workerData.userOptions.build,
   } = msg;
   try {
-    // Load modules
-    const pageAndPropsResult = await resolvePageAndProps({
+    // Create loader function for module resolution
+    const loader = async (moduleID: string) => {
+      // Handle #Page/#props suffixes
+      const [id, exportName] = moduleID.split('#');
+      if (hmrState.get(id)?.invalidated) {
+        hmrState.delete(id);
+        const res = await import(join(projectRoot, id) + `?t=${Date.now()}`)
+        if(!exportName) return res;
+        if(exportName in res) return { [exportName]: res[exportName] };
+        return res;
+      }
+      const res = await import(join(projectRoot, id))
+      if(!exportName) return res;
+      if(exportName in res) return { [exportName]: res[exportName] };
+      return res;
+    };
+
+    // Load modules (page, props, and components together)
+    const componentsResult = await resolveComponents({
       pagePath,
       propsPath,
+      rootPath,
+      htmlPath,
       pageExportName,
       propsExportName,
+      rootExportName: workerData.userOptions.rootExportName,
+      htmlExportName: workerData.userOptions.htmlExportName,
       route,
-      loader: (id: string) => {
-        try {
-          if (hmrState.get(id)?.invalidated) {
-            // Clear the HMR state for this module
-            hmrState.delete(id);
-            return import(join(projectRoot, id) + `?t=${Date.now()}`);
-          }
-          return import(join(projectRoot, id));
-        } catch (error) {
-          return Promise.reject(error);
-        }
-      },
+      verbose: workerData.userOptions.verbose,
+      loader: loader as BuildModuleLoader<ResolvedUserOptions>,
+      // Use components override for headless RSC streams in development
+      HtmlComponent: React.Fragment,
+      moduleBaseURL,
+      build,
+      logger,
     });
-    if (pageAndPropsResult.type !== "success") {
-      const { error, ...rest } = pageAndPropsResult;
-      return handlers.onError(id, error, rest);
+    if (componentsResult.type !== "success") {
+      const { error, reason } = componentsResult;
+      handlers.onError(id, error, { reason });
+      return; // Don't propagate the error after handling it
     }
 
-    const { PageComponent, pageProps } = pageAndPropsResult;
+    const { PageComponent, pageProps, RootComponent } = componentsResult;
+
+    // Override HtmlComponent with React.Fragment for headless RSC streams in development
+    const finalHtmlComponent = React.Fragment;
 
-    const adaptedOnEvent = (event: "error" | "postpone", data: any) => {
-      if (event === "error") {
-        handlers.onError(id, data.error, data.errorInfo);
-      }
-    };
 
     if (messageCssFiles && messageCssFiles.size > 0) {
       // if any css is added to the message, add it to the cssFiles map
@@ -73,13 +99,16 @@ export async function handleRender<
         cssFiles.set(id, cssContent);
       }
     }
+    const url = routeToURL(route, moduleBaseURL, build.rscOutputPath);
+
 
     // Create stream
     const streamResult = createRscStream({
+      url: url,
       projectRoot: projectRoot,
-      Html: React.Fragment,
-      PageComponent,
-      CssCollector,
+      HtmlComponent: finalHtmlComponent,
+      PageComponent: PageComponent,
+      RootComponent: RootComponent,
       pageProps,
       moduleBase,
       moduleRootPath,
@@ -90,13 +119,14 @@ export async function handleRender<
       // this is a stateful object, which at this point we assume contains all the css files
       cssFiles,
       globalCss,
-      onEvent: adaptedOnEvent,
       pipeableStreamOptions: pipeableStreamOptions,
+      verbose,
+      logger,
     });
 
     if (streamResult.type !== "success") {
       handlers.onError(id, streamResult.error);
-      return;
+      return; // Already handled the error
     }
 
     const { stream, metrics } = streamResult;
@@ -133,6 +163,6 @@ export async function handleRender<
     });
   } catch (error) {
     handlers.onError(id, error as Error, { reason: `${id} render error` });
-    return Promise.reject(error);
+    return; // Don't propagate the error after handling it
   }
 }

package/plugin/worker/rsc/handlers.ts

@@ -1,4 +1,4 @@
-import { sendRscWorkerMessage } from "../sendMessage.js";
+import { sendRscWorkerMessage } from "./sendRscWorkerMessage.js";
 import type { StreamHandlers } from "../types.js";
 import { toError } from "../../error/toError.js";
 import { userOptions } from "./userOptions.js";
@@ -7,33 +7,39 @@ import { join } from "path";
 import { ReactDOMServer } from "../../vendor/vendor.server.js";
 import { PassThrough } from "node:stream";
 
+// Helper function to serialize errors for worker thread communication
+const serializeError = (error: unknown) => {
+  const err = toError(error);
+  return {
+    message: err.message,
+    name: err.name,
+    stack: err.stack,
+  };
+};
+
 export const handlers: Required<StreamHandlers> = {
   onError: (id, error, errorInfo) => {
     sendRscWorkerMessage({
       type: "ERROR",
       id: id,
       errorInfo,
-      error: toError(error),
-    });
-    sendRscWorkerMessage({
-      type: "RSC_END",
-      id: id,
+      error: serializeError(error),
     });
   },
-  onData: (id, data: any) => {
+  onData: (id, data) => {
     sendRscWorkerMessage({
       type: "RSC_CHUNK",
       id: id,
       chunk: data,
     });
   },
-  onEnd: (id: string) => {
+  onEnd: (id) => {
     sendRscWorkerMessage({
       type: "RSC_END",
       id: id,
     });
   },
-  onMetrics: (id: string, metrics: any) => {
+  onMetrics: (id, metrics) => {
     sendRscWorkerMessage({
       type: "RSC_METRICS",
       id: id,
@@ -65,17 +71,19 @@ export const handlers: Required<StreamHandlers> = {
   },
   onServerActionResponse: (id, result) => {
     const stream = ReactDOMServer.renderToPipeableStream(
-      {
-        type: "server-action-response",
-        returnValue: result
-      },
+      result && typeof result === "object" && "returnValue" in result
+        ? result
+        : {
+            type: "server-action-response",
+            returnValue: result,
+          },
       userOptions.moduleBasePath,
       {
         onError(error: Error) {
           sendRscWorkerMessage({
             type: "ERROR",
             id,
-            error: toError(error),
+            error: serializeError(error),
           });
         },
       }
@@ -103,7 +111,7 @@ export const handlers: Required<StreamHandlers> = {
       sendRscWorkerMessage({
         type: "ERROR",
         id,
-        error: toError(error),
+        error: serializeError(error),
       });
     });
   },
@@ -137,7 +145,7 @@ export const handlers: Required<StreamHandlers> = {
       const stream = ReactDOMServer.renderToPipeableStream(
         {
           type: "server-action-response",
-          returnValue: result
+          returnValue: result,
         },
         userOptions.moduleBasePath,
         {
@@ -145,7 +153,7 @@ export const handlers: Required<StreamHandlers> = {
             sendRscWorkerMessage({
               type: "ERROR",
               id,
-              error: toError(error),
+              error: serializeError(error),
             });
           },
         }
@@ -173,16 +181,16 @@ export const handlers: Required<StreamHandlers> = {
         sendRscWorkerMessage({
           type: "ERROR",
           id,
-          error: toError(error),
+          error: serializeError(error),
         });
       });
     } catch (error: unknown) {
-      const errorMessage = toError(error).message;
+      const errorMessage = serializeError(error).message;
       // Send error response using RSC stream
       const stream = ReactDOMServer.renderToPipeableStream(
         {
           type: "server-action-response",
-          returnValue: { success: false, error: errorMessage }
+          returnValue: { success: false, error: errorMessage },
         },
         userOptions.moduleBasePath,
         {
@@ -190,7 +198,7 @@ export const handlers: Required<StreamHandlers> = {
             sendRscWorkerMessage({
               type: "ERROR",
               id,
-              error: toError(error),
+              error: serializeError(error),
             });
           },
         }
@@ -218,7 +226,7 @@ export const handlers: Required<StreamHandlers> = {
         sendRscWorkerMessage({
           type: "ERROR",
           id,
-          error: toError(error),
+          error: serializeError(error),
         });
       });
     }

package/plugin/worker/rsc/index.ts

@@ -3,3 +3,5 @@ await(
     ? import("./rsc-worker.production.js")
     : import("./rsc-worker.development.js")
 );
+
+export * from './types.js';

package/plugin/worker/rsc/messageHandler.tsx

@@ -1,19 +1,20 @@
 import { parentPort } from "node:worker_threads";
-import {
-  activeStreams,
-  hmrState,
-} from "./state.js";
+import { activeStreams, hmrState } from "./state.js";
 import { handleRender } from "./handleRender.js";
-import type {
-  RscWorkerInputMessage,
-} from "../types.js";
+import type { RscWorkerInputMessage } from "./types.js";
 import { toError } from "../../error/toError.js";
 import { handlers } from "./handlers.js";
+import { join } from "node:path";
+import { workerData } from "node:worker_threads";
+import { sendMessage } from "../sendMessage.js";
+import { createLogger } from "vite";
+import { logError } from "../../error/logError.js";
 
 // In test mode, we want errors to propagate up immediately
 const isTestEnv = process.env["VITEST"] || process.env["NODE_ENV"] === "test";
 const isDevEnv = process.env["NODE_ENV"] !== "production";
 
+const logger = createLogger(workerData.resolvedConfig.logLevel ?? 'info');
 
 export async function messageHandler(
   msg: RscWorkerInputMessage,
@@ -25,7 +26,7 @@ export async function messageHandler(
     }
     switch (msg.type) {
       case "RSC_RENDER":
-        return await handleRender(msg, handlers);
+        return await handleRender(msg, handlers, logger);
       case "SERVER_ACTION":
         return handlers.onServerAction(msg.id, msg.args);
       case "INITIALIZED_REACT_LOADER":
@@ -54,6 +55,16 @@ export async function messageHandler(
       case "SERVER_MODULE":
         handlers.onServerModule(msg.id, msg.url, msg.source);
         return;
+      case "MODULE_REQUEST": {
+        const { id, path } = msg;
+        try {
+          const module = await import(join(workerData.userOptions.projectRoot, path));
+          handlers.onServerModule(id, path, module);
+        } catch (error) {
+          handlers.onError(id, toError(error));
+        }
+        return;
+      }
       case "SHUTDOWN": {
         // If id is "*", clean up all render states
         if (msg.id === "*") {
@@ -75,20 +86,19 @@ export async function messageHandler(
     }
   } catch (error) {
     const err = toError(error);
-    if (isDevEnv) {
-      console.error(err);
-    }
     // In dev mode, try to send error message before exiting
     if (parentPort) {
-      port?.postMessage({
+      sendMessage({
         type: "ERROR",
         id: "rsc-worker",
         error: err,
-      });
+      }, port);
     }
     if (!isDevEnv || isTestEnv) {
       // In test mode or production mode, just throw the error to fail fast
       throw err;
+    } else {
+      logError(err, logger);
     }
   }
 }