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

package/plugin/loader/transformModule.ts

@@ -0,0 +1,54 @@
+/**
+ * # RSC Boundary Handling
+ *
+ * This file provides the core transformation logic for React Server Components (RSC) boundaries.
+ *
+ * ## Error Behavior
+ *
+ * - If a client component is imported on the server, the export is a function that throws a clear error.
+ * - If a server action is imported on the client, the export is a function that throws a clear error.
+ *
+ * This ensures that implementation details are never leaked across boundaries and errors are easy to debug.
+ */
+import type { ParseResult } from "./directives/types.js";
+import { transformServerModule } from "./transformServerModule.js";
+import { transformClientModule } from "./transformClientModule.js";
+import type { TransformFunction, TransformOptions, TransformResult } from "./types.js";
+
+/**
+ * Transforms a module for RSC boundaries, handling imports and registrations.
+ */
+export const transformModule: TransformFunction = async (
+  source: string,
+  moduleId: string,
+  parseResult: ParseResult,
+  options: TransformOptions
+): Promise<TransformResult> => {
+  if (parseResult.type !== 'success') {
+    if(options.verbose) {
+      console.log(`[transformModule] Parse error:`, parseResult.error);
+    }
+    return { code: '', map: null };
+  }
+
+  if (options.verbose) {
+    console.log(`[transformModule] Module: ${moduleId}`);
+    console.log(`[transformModule] Directives:`, parseResult.directiveInfo);
+    console.log(
+      `[transformModule] isServerFunction:`,
+      options.forceServerFunction,
+      `isClientComponent:`,
+      options.forceClientComponent
+    );
+  }
+
+  // Only apply transformation for server functions or client components
+  if (!(options.forceServerFunction || options.forceClientComponent)) {
+    return { code: source, map: null };
+  }
+
+  // Transform based on module type and return the result directly
+  return options.forceServerFunction
+    ? transformServerModule(source, moduleId, parseResult, options.loader, options.verbose)
+    : transformClientModule(source, moduleId, parseResult, options.loader, options.verbose);
+};

package/plugin/loader/transformModuleIfNeeded.ts

@@ -1,65 +1,65 @@
-import { getCondition } from "../config/getCondition.js";
-import { transformModuleWithPreservedFunctions } from "./transformModuleWithPreservedFunctions.js";
-import { parse } from "./parse.js";
-import { DEFAULT_CONFIG } from "../config/defaults.js";
+import { transformWithAcornLoose } from "./transformWithAcornLoose.js";
+import type { RawSourceMap } from "source-map";
+import type { TransformOptions } from "./types.js";
+
 
 // --- React RSC Directive Handling ---
 //
-// 1. 'use client' at file top:
+// 1. 'use client' at file top of NON-SERVER environment:
 //    - Pass through code as-is (after removing directive).
 //    - Do not transform or register anything.
-//    - Required for React client features to work.
+//    - Remove the directive.
 //    - See: https://react.dev/reference/rsc/use-client
-//
-// 2. 'use server' at file top:
-//    - Register all exported async functions as server actions.
+// 2.  'use client' at file top of SERVER environment:
+//    - Remove implementation of client components.
+//    - Import registerClientReference.
+//    - Register client components as error-throwing functions.
+//    - Always a export const ${registrationName} = registerClientReference(...)
+//    - See: https://react.dev/reference/rsc/use-client
+// 3. 'use server' at file top:
+//    - import registerServerReference.
+//    - Append registrations to bottom of file.
+//    - Register all exported functions as server actions.
+//    - Do not re-export, just append to bottom of file registerServerReference(...).
 //    - See: https://react.dev/reference/rsc/use-server
 //
 // 3. 'use server' at function top:
-//    - Register only that async function as a server action.
+//    - add import registerServerReference.
+//    - Register only that/those functions as a server action.
 //    - See: https://react.dev/reference/rsc/use-server
 //
-// 4. No directive:
-//    - Treat as a normal shared or server-only module.
+// 4. No directive or no exported boundary functions
+//    - Treat as server-only module.
+//    - Do not allow on client, only use client is allowed on client.
 //    - No special registration or transformation.
 
-export function transformModuleIfNeeded(
+/**
+ * Transforms a module and returns the transformed code with source map attached.
+ * This is used by the loader to transform modules and attach source maps.
+ * 
+ * @returns The transformed code with source map attached as a URL comment
+ */
+export async function transformModuleIfNeeded(
   source: string,
   moduleId: string,
-  isServerFunction: boolean | RegExpMatchArray | null = DEFAULT_CONFIG.AUTO_DISCOVER.isServerFunctionCode(source, moduleId),
-  isClientComponent: boolean | RegExpMatchArray | null = DEFAULT_CONFIG.AUTO_DISCOVER.isClientComponentCode(source, moduleId),
-  isServerEnvironment = getCondition() === "react-server"
-) {
-  // Handle environment-specific cases
-  if (isServerEnvironment) {
-    // In server environment:
-    // - Server functions need transformation
-    // - Client components need transformation
-    // - Other modules can pass through
-    if (!isServerFunction && !isClientComponent) {
-      return source;
-    }
-  } else {
-    // In client environment:
-    // - Only client components should pass through
-    // - Server functions should be transformed
-    if (isClientComponent) {
-      return source;
-    }
-  }
-
+  options: TransformOptions
+): Promise<{ code: string; map: RawSourceMap | null }> {
   try {
-    const result = transformModuleWithPreservedFunctions(
+    // Get transformed code and source map from acorn-loose transformer
+    const result = await transformWithAcornLoose(
       source,
       moduleId,
-      parse(source),
-      isServerFunction,
-      isClientComponent
+      options
     );
+
+    if(options.verbose) {
+      console.log("[transformModuleIfNeeded] Transformed module:", { code: result.code, map: result.map });
+    }
+    // Return the transformed code with source map attached as a URL comment
     return result;
   } catch (error) {
     // Log the error and rethrow
-    console.error(`Error transforming module ${moduleId}:`, error);
+    console.error(`[transformModuleIfNeeded] Error transforming module ${moduleId}:`, error);
     throw error;
   }
 }

package/plugin/loader/transformServerModule.ts

@@ -0,0 +1,136 @@
+import type { ParseResult, Program } from "./directives/types.js";
+import type {  ResolvedUserOptions } from "../types.js";
+import { createSourceMap } from "./sourceMap.js";
+import type { TransformResult } from "./types.js";
+import { removeDirectives } from "./removeDirectives.js";
+import * as acorn from "acorn";
+import { getNodeEnv } from "../getNodeEnv.js";
+import { DEFAULT_CONFIG } from "../config/defaults.js";
+import type { ArrowFunctionExpression, FunctionDeclaration, FunctionExpression } from "acorn";
+
+/**
+ * Transforms a server module by:
+ * 1. Parsing it to get exports and directives
+ * 2. Collecting function-level server directives
+ * 3. Registering server functions
+ */
+export async function transformServerModule(
+  source: string,
+  moduleId: string,
+  parseResult: ParseResult,
+  loader: Pick<
+    ResolvedUserOptions["loader"],
+    "registerServerReferenceName" | "importServerPath" 
+  > = DEFAULT_CONFIG.RSC_LOADER[getNodeEnv()],
+  verbose = false
+): Promise<TransformResult> {
+  if (!loader) {
+    loader = DEFAULT_CONFIG.RSC_LOADER[getNodeEnv()];
+  }
+  if (parseResult.type !== "success") {
+    return { code: "", map: null };
+  }
+
+  // Parse the source with Acorn to get accurate directive locations
+  const ast = acorn.parse(source, {
+    ecmaVersion: "latest",
+    sourceType: "module",
+    locations: true,
+    ranges: true,
+    allowAwaitOutsideFunction: true,
+    allowReturnOutsideFunction: true,
+  });
+
+  // Collect all directive ranges (file-level and function-level)
+  const rangesToRemove: { start: number; end: number }[] = [];
+
+  // File-level: top-level ExpressionStatement with directive
+  for (const node of ast.body) {
+    if (
+      node.type === "ExpressionStatement" &&
+      node.directive === "use server"
+    ) {
+      rangesToRemove.push({ start: node.start, end: node.end });
+    }
+    // Stop at first non-directive
+    if (node.type !== "ExpressionStatement" || !node.directive) break;
+  }
+
+  // Function-level: walk all functions and check first statement in body
+  function walkFunctionDirectives(node: FunctionDeclaration | FunctionExpression | ArrowFunctionExpression | Program) {
+    if (
+      (node.type === "FunctionDeclaration" ||
+        node.type === "FunctionExpression" ||
+        node.type === "ArrowFunctionExpression") &&
+      node.body &&
+      node.body.type === "BlockStatement" &&
+      node.body.body.length > 0
+    ) {
+      const first = node.body.body[0];
+      if (
+        first.type === "ExpressionStatement" &&
+        first.expression.type === "Literal" &&
+        first.expression.value === "use server"
+      ) {
+        rangesToRemove.push({ start: first.start, end: first.end });
+      }
+    }
+    // Recurse into child nodes
+    for (const key in node) {
+      const value = node[key as keyof typeof node];
+      if (Array.isArray(value)) {
+        value.forEach((item) => {
+          if (item && typeof item === 'object' && 'type' in item) {
+            walkFunctionDirectives(item as any);
+          }
+        });
+      } else if (value && typeof value === 'object' && 'type' in value) {
+        walkFunctionDirectives(value as any);
+      }
+    }
+  }
+  walkFunctionDirectives(ast);
+
+  if (verbose) {
+    console.log(`[transformServerModule] Ranges to remove:`, rangesToRemove);
+  }
+
+  // Remove directives from the source code using the shared utility
+  const transformedCode = removeDirectives(source, rangesToRemove);
+
+  // Register all exports as server references
+  const registrations = [];
+  for (const exp of parseResult.exports.exports.values()) {
+    // Check if any exports have server directives
+    const hasServerDirective = parseResult.directiveInfo.functionLevel.some(
+      (d) => d.type === "server" && d.name === exp.localName
+    );
+    // Register if it has its own server directive or if there's a file-level directive
+    if (
+      hasServerDirective ||
+      parseResult.directiveInfo.fileLevel?.type === "server"
+    ) {
+      // Use original module ID for re-exports, current module ID for local exports
+      const targetModuleId = exp.originalModuleId || moduleId;
+      registrations.push(
+        `${loader?.registerServerReferenceName}(${exp.localName}, "${targetModuleId}", "${exp.exportName}");`
+      );
+    }
+  }
+
+  // Only add the import and registrations if there are any registrations to make
+  const finalCode =
+    registrations.length > 0
+      ? `\n      import { ${loader?.registerServerReferenceName} } from "${
+          loader?.importServerPath
+        }";\n      ${transformedCode}\n      ${registrations.join("\n")}\n    `
+      : transformedCode;
+
+  // Create source map based on the final transformed code
+  const map = createSourceMap(finalCode, source, moduleId, []);
+
+  return {
+    code: finalCode,
+    map,
+  };
+}

package/plugin/loader/transformWithAcornLoose.ts

@@ -0,0 +1,27 @@
+import { createTransformer } from "./createTransformer.js";
+import type { RawSourceMap } from "source-map";
+import { parse } from "./parse.js";
+import type { TransformOptions } from "./types.js";
+
+export type TransformWithAcornLooseFn = (
+  source: string,
+  moduleId: string,
+  options: TransformOptions
+) => Promise<{ code: string; map: RawSourceMap | null }>;
+
+/**
+ * Transforms a module using acorn-loose for parsing.
+ * @returns Object containing the transformed code and its source map
+ */
+export const transformWithAcornLoose: TransformWithAcornLooseFn =
+  async function _transformWithAcornLoose(
+    source: string,
+    moduleId: string,
+    options: TransformOptions
+  ): Promise<{ code: string; map: RawSourceMap | null }> {
+    const transformer = createTransformer({
+      parseFn: parse,
+      options,
+    });
+    return transformer(source, moduleId);
+  };

package/plugin/loader/types.ts

@@ -1,18 +1,70 @@
-import type { Program as AcornProgram, Statement, Node as AcornNode } from "acorn";
+import type { RawSourceMap } from "source-map";
+import type { DirectiveWarning, ParseResult, Program, AllowedDirectives } from "./directives/types.js";
 
-// Directive is a special type in Acorn that extends ExpressionStatement
-export type Directive = Statement & {
-  directive: string;
+
+
+export type LoaderConfig = {
+  serverDirective: RegExp;
+  clientDirective: RegExp;
+  allowedDirectives: AllowedDirectives;
+  getDirectiveType: (
+    directive: string,
+    moduleId?: string
+  ) => "client" | "server" | undefined;
+  mode: "development" | "production" | "test";
+  importServerPath: string;
+  importClientPath: string;
+  registerClientReferenceName: string;
+  registerServerReferenceName: string;
+  isServerFunctionCode: (code: string, moduleId?: string) => boolean;
+  isClientComponentCode: (code: string, moduleId?: string) => boolean;
+  parse: (source: string) => Promise<{
+    ast: Program;
+    code: string;
+    map?: { url: string; start: number; end: number; lines: number } | null;
+  }>;
+};
+
+export type RscLoader = Pick<LoaderConfig, 'importServerPath' | 'importClientPath' | 'registerClientReferenceName' | 'registerServerReferenceName'>;
+
+export type TransformOptions = {
+  forceServerFunction?: boolean;
+  forceClientComponent?: boolean;
+  isServerEnvironment?: boolean;
+  loader?: LoaderConfig;
+  directiveWarnings?: DirectiveWarning[];
+  // based on warning, remove warning directive index to avoid warning in development
+  removeDirectives?: number[];
+  // based on warning, add warning directive index to avoid warning in development
+  addDirectives?: number[];
+  verbose?: boolean;
+  panicThreshold?: 'none' | 'critical_errors' | 'all_errors';
+  mode?: "development" | "production" | "test";
+};
+
+export type TransformResult = {
+  code: string;
+  map: RawSourceMap | null;
 };
 
-export type Node = AcornNode;
+export type TransformFunction = (
+  source: string,
+  moduleId: string,
+  parseResult: ParseResult,
+  options: TransformOptions
+) => Promise<TransformResult>;
 
-export interface ExportInfo {
-  name: string;
-  localName?: string;
-  type: "function" | "variable" | "class" | "unknown";
-  isServerAction?: boolean;
-  node?: Node;
-}
+export type TransformerFactory = (options: {
+  parseFn?: (source: string) => Promise<{ ast: Program; code: string; map?: {
+    url: string;
+    start: number;
+    end: number;
+    lines: number;
+  } | null }>;
+  options: Pick<TransformOptions, 'verbose' | 'loader' | 'panicThreshold'>;
+  forceServerFunction?: boolean | undefined;
+  forceClientComponent?: boolean | undefined;
+  isServerEnvironment?: boolean;
+}) => (source: string, moduleId: string) => Promise<TransformResult>;
 
-export type Program = AcornProgram;
+export type { Program };

package/plugin/metrics/collectStreamMetrics.ts

@@ -0,0 +1,38 @@
+import { Transform } from "node:stream";
+import type { PipeableStream } from "react-dom/server";
+import { createStreamMetrics } from "./createStreamMetrics.js";
+import type { StreamMetrics } from "./types.js";
+
+/**
+ * Creates a transform stream that collects metrics from the input stream
+ * @param stream The stream to collect metrics from
+ * @returns A promise that resolves with the metrics when the stream ends
+ */
+export function collectStreamMetrics(stream: PipeableStream | NodeJS.ReadableStream): Promise<StreamMetrics> {
+  const metrics = createStreamMetrics();
+  const startTime = performance.now()
+
+  return new Promise<StreamMetrics>((resolve, reject) => {
+    const transform = new Transform({
+      transform(chunk, _encoding, callback) {
+        metrics.chunks++;
+        metrics.bytes += chunk.length;
+        callback(null, chunk);
+      },
+      flush(callback) {
+        metrics.duration = Date.now() - startTime;
+        callback();
+      }
+    });
+
+    stream.pipe(transform);
+
+    transform.on("error", (error) => {
+      reject(error);
+    });
+
+    transform.on("end", () => {
+      resolve(metrics);
+    });
+  });
+} 

package/plugin/metrics/createRenderMetrics.ts

@@ -0,0 +1,17 @@
+import { createStreamMetrics } from "./createStreamMetrics.js";
+import type { RenderMetrics } from "./types.js";
+
+export function createRenderMetrics(route: string): RenderMetrics {
+  return {
+    route,
+    htmlSize: 0,
+    rscSize: 0,
+    processingTime: 0,
+    chunks: 0,
+    chunkRate: 0,
+    memoryUsage: process.memoryUsage(),
+    streamMetrics: createStreamMetrics(),
+    htmlSizes: new Map(),
+    rscSizes: new Map(),
+  };
+}

package/plugin/metrics/createStreamMetrics.ts

@@ -0,0 +1,14 @@
+import type { StreamMetrics } from "./types.js";
+
+export function createStreamMetrics(): StreamMetrics {
+    return {
+      chunks: 0,
+      bytes: 0,
+      backpressureCount: 0,
+      drainCount: 0,
+      errorCount: 0,
+      duration: 0,
+      startTime: performance.now()
+    };
+  }
+  

package/plugin/metrics/formatMetrics.ts

@@ -1,4 +1,4 @@
-import type { RenderMetrics } from "../types.js";
+import type { RenderMetrics } from "./types.js";
 
 export function formatMetrics(metrics: RenderMetrics): string {
   const {
@@ -41,8 +41,8 @@ export function metricWatcher({
 }: {
   maxTime?: number;
   warnOnly?: boolean;
-  warn?: (...args: any[]) => void;
-  info?: (...args: any[]) => void;
+  warn?: (...args: unknown[]) => void;
+  info?: (...args: unknown[]) => void;
 }) {
   return (metrics: RenderMetrics) => {
     if (metrics.processingTime > maxTime) {
@@ -60,3 +60,7 @@ export function metricWatcher({
     }
   };
 }
+
+export function logMetrics(metrics: RenderMetrics, logger: {info: (message: string) => void} = console) {
+  logger.info(formatMetrics(metrics));
+}

package/plugin/metrics/index.ts

@@ -1,2 +1,4 @@
 export * from "./formatMetrics.js";
-export type { RenderMetrics, StreamMetrics } from "../types.js";
+export * from "./collectStreamMetrics.js";
+export * from "./createRenderMetrics.js";
+export type { RenderMetrics, StreamMetrics } from "./types.js";

package/plugin/metrics/types.ts

@@ -0,0 +1,24 @@
+
+export type StreamMetrics = {
+  chunks: number;
+  bytes: number;
+  backpressureCount: number;
+  drainCount: number;
+  errorCount: number;
+  duration: number;
+  startTime: number;
+  route?: string;
+};
+
+export type RenderMetrics = {
+  route: string;
+  htmlSize: number;
+  rscSize: number;
+  processingTime: number;
+  chunks: number;
+  chunkRate: number;
+  memoryUsage: NodeJS.MemoryUsage;
+  streamMetrics: StreamMetrics;
+  htmlSizes: Map<string, number>;
+  rscSizes: Map<string, number>;
+};

package/plugin/plugin.client.ts

@@ -1,19 +1,43 @@
 import { reactPreservePlugin } from "./preserver/plugin.js";
-import type {
-  StreamPluginOptions,
-  InlineCssOpt,
-  PagePropOpt,
-} from "../types.js";
+import type { StreamPluginOptions } from "../types.js";
 import { reactClientPlugin } from "./react-client/plugin.js";
 import { envPlugin } from "./env/plugin.js";
+import type { Plugin } from "vite";
 
-export function vitePluginReactServer<
-  T extends PagePropOpt = PagePropOpt,
-  InlineCSS extends InlineCssOpt = InlineCssOpt
->(options = {} as StreamPluginOptions<T, InlineCSS>): import("vite").Plugin[] {
-  return [
-    envPlugin(),
-    reactClientPlugin(options),
-    reactPreservePlugin(options),
-  ];
-}
+export type VitePluginReactClientFn = <
+  Opt extends StreamPluginOptions = StreamPluginOptions
+>(
+  options: Opt
+) => Plugin[];
+
+/**
+ * Vite plugin for the React client, use same name to support dynamic import.
+ * Includes:
+ * - envPlugin
+ * - reactClientPlugin
+ * - reactPreservePlugin
+ * @param options
+ * @returns
+ */
+export const vitePluginReactServer: VitePluginReactClientFn =
+  function _vitePluginReactClient(options) {
+    if (options == null) {
+      throw new Error("options is required");
+    }
+    return [
+      envPlugin(),
+      reactClientPlugin(options),
+      reactPreservePlugin(options),
+    ];
+  };
+
+/**
+ * Vite plugin for the React client, use specific name to support static import (that doesn't conflict with vitePluginReactServer)
+ * Includes:
+ * - envPlugin
+ * - reactClientPlugin
+ * - reactPreservePlugin
+ * @param options
+ * @returns
+ */
+export const vitePluginReactClient = vitePluginReactServer;

package/plugin/plugin.server.ts

@@ -1,31 +1,52 @@
 import { reactPreservePlugin } from "./preserver/plugin.js";
 import { reactStaticPlugin } from "./react-static/plugin.js";
 import { reactTransformPlugin } from "./transformer/plugin.server.js";
-import type { StreamPluginOptions, PagePropOpt, InlineCssOpt } from "./types.js";
+import type {
+  StreamPluginOptions,
+} from "./types.js";
 import { reactServerPlugin } from "./react-server/plugin.js";
 import { envPlugin } from "./env/plugin.js";
+import type { Plugin } from "vite";
 
-
-export function vitePluginReactServer<
-  T extends PagePropOpt = PagePropOpt,
-  InlineCSS extends InlineCssOpt = InlineCssOpt
+export type VitePluginReactServerFn = <
+  Opt extends StreamPluginOptions = StreamPluginOptions
 >(
-  options = {} as StreamPluginOptions<T, InlineCSS>
-): import("vite").Plugin[] {
-  if(!options.build?.pages || (Array.isArray(options.build.pages) && options.build.pages.length === 0)) {
-    // in this case we do not need the static plugin at all
+  options: Opt
+) => Plugin[];
+
+/**
+ * Vite plugin for the React server, use same name to support dynamic import.
+ * Includes:
+ * - envPlugin
+ * - reactTransformPlugin
+ * - reactServerPlugin
+ * - reactStaticPlugin (if build.pages is not empty)
+ * - reactPreservePlugin 
+ */
+export const vitePluginReactServer: VitePluginReactServerFn =
+  function _vitePluginReactServer(
+    options
+  ) {
+    if(options == null) {
+      throw new Error("options is required");
+    }
+    if (
+      !options.build?.pages ||
+      (Array.isArray(options.build.pages) && options.build.pages.length === 0)
+    ) {
+      // in this case we do not need the static plugin at all
+      return [
+        envPlugin(),
+        reactTransformPlugin(options),
+        reactServerPlugin(options),
+        reactPreservePlugin(options),
+      ];
+    }
     return [
       envPlugin(),
       reactTransformPlugin(options),
       reactServerPlugin(options),
+      reactStaticPlugin(options),
       reactPreservePlugin(options),
     ];
-  }
-  return [
-    envPlugin(),
-    reactTransformPlugin(options),
-    reactServerPlugin(options),
-    reactStaticPlugin(options),
-    reactPreservePlugin(options),
-  ];
-}
+  };