vite-plugin-react-server 1.0.2 → 1.1.0

package/plugin/types.ts

@@ -1,4 +1,8 @@
-import type { PreRenderedChunk } from "rollup";
+import type {
+  NormalizedOutputOptions,
+  OutputBundle,
+  PreRenderedChunk,
+} from "rollup";
 import type { PreRenderedAsset } from "rollup";
 import type {
   UserConfig,
@@ -7,14 +11,91 @@ import type {
   AliasOptions,
   Connect,
   ResolveOptions,
+  Manifest,
+  Logger,
 } from "vite";
-import type { PipeableStreamOptions } from "./worker/types.js";
+import type { ReactServerDomEsmOptions } from "./worker/types.js";
+import type React from "react";
+import type { PassThrough, Transform } from "stream";
+import type { MessagePort } from "node:worker_threads";
+import type { PropsWithChildren } from "react";
+import { Readable } from "node:stream";
+
+export type OnEvent = (event: PluginEvent) => void;
+
+export type Serializable =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | Serializable[]
+  | SerializableRecord;
+export type SerializableRecord = {
+  [key: string]: Serializable | SerializableRecord;
+};
+
+// Track HMR state
+export type HmrState = {
+  timestamp: number;
+  invalidated: boolean;
+  routes: string[];
+};
+
+export type RenderPageResult =
+  | {
+      type: "skip";
+    }
+  | {
+      type: "error";
+      error: Error;
+    }
+  | {
+      type: "success";
+      html: PassThrough;
+      rsc: PassThrough;
+      metrics: {
+        rscFull: StreamMetrics;
+        rscHeadless: StreamMetrics;
+      };
+    };
+
+export type AutoDiscoveredFiles = ResolvedBuildPages & {
+  workerPaths: Record<string, string>;
+  serverEntry: Record<string, string> | null;
+  clientEntry: Record<string, string>;
+  inputs: Record<string, string>;
+  staticManifest: Manifest;
+};
+export type FileWriterOptions = Pick<
+  CreateHandlerOptions,
+  "onEvent" | "route" | "build"
+>;
 
 // Input can be a string path, React component, tuple, or array
 export type NormalizerInput = unknown;
 
 export type InputNormalizer = (input: NormalizerInput) => [string, string];
 
+export interface HtmlContent {
+  raw: string;
+  transformed?: string;
+  assets?: string[];
+}
+
+export interface PartialPageData {
+  route: string;
+  html?: {
+    raw: string;
+    transformed?: string;
+    assets?: string[];
+  };
+  rsc?: {
+    modules: any[];
+    content: string;
+  };
+}
+
 export type InputNormalizerWorker = (
   input: NormalizerInput
 ) => Promise<[string, string]>;
@@ -23,7 +104,7 @@ export type ResolvedUserConfig = Required<
   Pick<UserConfig, "root" | "mode" | "build" | "resolve">
 > &
   Omit<UserConfig, "root" | "mode" | "build" | "resolve"> & {
-    resolve:  ResolveOptions;
+    resolve: ResolveOptions;
   } & {
     build: NonNullable<
       Required<
@@ -52,6 +133,10 @@ export type ResolvedUserConfig = Required<
       >;
   };
 
+export type SerializedUserConfig = Extract<
+  ResolvedUserConfig,
+  SerializableRecord
+>;
 // Client plugin options
 export interface StreamPluginOptionsClient {
   outDir?: string;
@@ -65,33 +150,42 @@ export interface StreamPluginOptionsClient {
   cssFiles?: AliasOptions;
 }
 
-export type ResolvedUserOptions<InlineCSS extends boolean = boolean> = Required<
+export type ResolvedUserOptions<
+  InlineCSS extends boolean | undefined = boolean | undefined
+> = Required<
   Pick<
     StreamPluginOptions,
     | "moduleBase"
     | "moduleBasePath"
     | "moduleBaseURL"
+    | "moduleRootPath"
     | "projectRoot"
     | "build"
     | "Page"
-    | "props"
     | "Html"
     | "CssCollector"
     | "pageExportName"
     | "propsExportName"
-    | "collectCss"
-    | "collectAssets"
-    | "inlineCss"
     | "htmlWorkerPath"
     | "rscWorkerPath"
     | "loaderPath"
     | "clientEntry"
     | "serverEntry"
     | "moduleBaseExceptions"
-    | "pipableStreamOptions"
+    | "pipeableStreamOptions"
+    | "onMetrics"
+    | "onEvent"
+    | "css"
+    | "normalizer"
   >
 > & {
+  props:
+    | undefined
+    | string
+    | ((url: string) => string)
+    | ((url: string) => Promise<string>);
   build: NonNullable<Required<StreamPluginOptions<InlineCSS>["build"]>>;
+  css: NonNullable<Required<StreamPluginOptions<InlineCSS>["css"]>>;
   autoDiscover: {
     modulePattern: (path: string) => boolean;
     cssPattern: (path: string) => boolean;
@@ -99,9 +193,14 @@ export type ResolvedUserOptions<InlineCSS extends boolean = boolean> = Required<
     clientComponents: (path: string) => boolean;
     propsPattern: (path: string) => boolean;
     pagePattern: (path: string) => boolean;
+    htmlPattern: (path: string) => boolean;
+    rscPattern: (path: string) => boolean;
     serverFunctions: (path: string) => boolean;
     cssModulePattern: (path: string) => boolean;
     vendorPattern: (path: string) => boolean;
+    nodeOnly: (path: string) => boolean;
+    dotFiles: (path: string) => boolean;
+    virtualPattern: (path: string) => boolean;
   };
 };
 
@@ -118,16 +217,141 @@ export type createBuildConfigFn<C extends "react-client" | "react-server"> =
     ? Promise<InlineConfig>
     : Promise<InlineConfig>;
 
-export interface StreamPluginOptions<InlineCSS extends boolean = boolean> {
+export interface StreamMetrics {
+  chunks: number;
+  bytes: number;
+  backpressureCount: number;
+  drainCount: number;
+  errorCount: number;
+  duration: number;
+  startTime: number;
+}
+
+export interface 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>;
+}
+
+export interface CssCollectorOptions {
+  inlineCss?: boolean;
+  purgeCss?: boolean;
+  inlineThreshold?: number;
+  inlinePatterns?: RegExp[];
+  linkPatterns?: RegExp[];
+}
+
+export type FileWriteEvent = {
+  type: "file.write";
+  data: {
+    path: string;
+    fileType: "html" | "rsc";
+    route: string;
+    stream: Readable;
+    onComplete: () => Promise<void>;
+  };
+};
+
+export type FileWriteDoneEvent = {
+  type: "file.write.done";
+  data: {
+    route: string;
+    fileType: "html" | "rsc";
+    content: string;
+  };
+};
+
+export type RouteProcessEvent = {
+  type: "route.process";
+  data: {
+    route: string;
+    pagePath: string;
+    propsPath?: string | undefined;
+  };
+};
+
+export type RouteErrorEvent = {
+  type: "route.error";
+  data: {
+    route: string;
+    error: any;
+  };
+};
+
+export type RoutePostponeEvent = {
+  type: "route.postpone";
+  data: {
+    route: string;
+    reason: string;
+  };
+};
+
+export type PropsLoadEvent = {
+  type: "props.load";
+  data: {
+    route: string;
+    propsPath: string;
+    props: any;
+  };
+};
+
+export type CssProcessEvent = {
+  type: "css.process";
+  data: CssContent;
+};
+
+export type BuildStartEvent = {
+  type: "build.start";
+  data: {
+    pages: string[];
+    files: AutoDiscoveredFiles;
+  };
+};
+
+export type BuildWriteBundleEvent = {
+  type: "build.writeBundle";
+  data: {
+    pages: string[];
+    options: NormalizedOutputOptions;
+    bundle: OutputBundle;
+    manifest: Manifest | undefined;
+  };
+};
+
+export type PluginEvent =
+  | FileWriteEvent
+  | FileWriteDoneEvent
+  | RouteProcessEvent
+  | RouteErrorEvent
+  | RoutePostponeEvent
+  | PropsLoadEvent
+  | CssProcessEvent
+  | BuildStartEvent
+  | BuildWriteBundleEvent;
+
+export type PluginEventType = PluginEvent["type"];
+
+export interface StreamPluginOptions<
+  InlineCSS extends boolean | undefined = boolean | undefined
+> {
   projectRoot?: string;
   moduleBase: string;
   moduleBasePath?: string;
   moduleBaseURL?: string;
+  moduleRootPath?: string;
   clientEntry?: string;
   serverEntry?: string;
   // Auto-discovery (zero-config)
   autoDiscover?:
     | {
+        moduleExtension?: RegExp;
         // default: /\.(m|c)?(j|t)sx?$/
         modulePattern?: string | RegExp | ((path: string) => boolean);
         // default: [Pp]age.tsx
@@ -148,56 +372,107 @@ export interface StreamPluginOptions<InlineCSS extends boolean = boolean> {
         cssModulePattern?: string | RegExp | ((path: string) => boolean);
         // default: /node_modules|(_virtual)/
         vendorPattern?: string | RegExp | ((path: string) => boolean);
+        // default: /\.node\.js$/
+        nodeOnly?: string | RegExp | ((path: string) => boolean);
+        // default: /\.node\.js$/
+        dotFiles?: string | RegExp | ((path: string) => boolean);
+        // default: /^\/_virtual\//
+        virtualPattern?: string | RegExp | ((path: string) => boolean);
+        // default: /\.rsc$/
+        rscPattern?: string | RegExp | ((path: string) => boolean);
       }
     | undefined;
   // Manual configuration
-  Page: string | ((url: string) => string);
-  props?: undefined | string | ((url: string) => string);
+  Page: string | ((url: string) => string) | ((url: string) => Promise<string>);
+  props?:
+    | undefined
+    | string
+    | ((url: string) => string)
+    | ((url: string) => Promise<string>);
   // Escape hatches
   htmlWorkerPath?: string;
   rscWorkerPath?: string;
   loaderPath?: string;
   pageExportName?: string;
   propsExportName?: string;
-  Html?: React.FC<{
-    manifest: import("vite").Manifest;
-    pageProps: any;
-    route: string;
-    url: string;
-    children: React.ReactNode;
-  }>;
-  CssCollector?: InlineCSS extends true ? React.FC<React.PropsWithChildren<InlineCssCollectorProps>> : React.FC<React.PropsWithChildren<CssCollectorProps>>;
-  collectCss?: boolean;
-  collectAssets?: boolean;
-  inlineCss?: InlineCSS;
+  Html?: React.FC<PropsWithChildren<HtmlProps>>;
+  CssCollector?: React.FC<
+    React.PropsWithChildren<CssCollectorProps<InlineCSS>>
+  >;
   build?: BuildConfig;
+  css?: CssCollectorOptions;
   moduleBaseExceptions?: string[];
-  pipableStreamOptions?: PipeableStreamOptions;
+  pipeableStreamOptions?: ReactServerDomEsmOptions;
+  onMetrics?: (metrics: RenderMetrics) => void;
+  onEvent?: (event: PluginEvent) => void;
+  normalizer?: InputNormalizer;
 }
 
-export interface CreateHandlerOptions<T = any, InlineCSS extends boolean = boolean> {
-  root: string;
-  url: string;
-  route: string;
-  getCss: (id: string) => Promise<Map<string, string | CssContent>> | Map<string, string | CssContent>;
-  loader: (id: string) => Promise<T>;
-  Html: NonNullable<StreamPluginOptions['Html']>
-  CssCollector: InlineCSS extends true ? React.FC<React.PropsWithChildren<InlineCssCollectorProps>> : React.FC<React.PropsWithChildren<CssCollectorProps>>;
-  inlineCss: InlineCSS;
+export type MultiPageHandlerOptions = Omit<
+  CreateHandlerOptions,
+  | "pagePath"
+  | "route"
+  | "cssFiles"
+  | "propsPath"
+  | "pageProps"
+  | "PageComponent"
+>;
+
+export type CreateHandlerOptions<
+  T = unknown,
+  C extends React.ComponentType<T> = React.ComponentType<T>,
+  InlineCSS extends boolean | undefined = undefined
+> = Pick<
+  ResolvedUserOptions<InlineCSS>,
+  | "autoDiscover"
+  | "css"
+  | "pageExportName"
+  | "propsExportName"
+  | "Html"
+  | "CssCollector"
+  | "moduleBase"
+  | "moduleRootPath"
+  | "moduleBasePath"
+  | "moduleBaseURL"
+  | "pipeableStreamOptions"
+  | "onEvent"
+  | "onMetrics"
+  | "projectRoot"
+> & {
+  logger: Logger;
+  loader: ModuleLoader;
+  pagePath: string;
   propsPath?: string;
-  pagePath?: string;
-  pageExportName: string
-  propsExportName: string
-  moduleBase: string
-  preserveModulesRoot?: boolean | undefined
-  moduleBasePath: string;
-  moduleRootPath: string;
-  moduleBaseURL: string;
-  cssFiles: (string | CssContent)[];
-  cssModules?: Map<string, string | CssContent> | undefined;
-  onCssFile?: (path: string, parentUrl: string) => void;
-  logger: import("vite").Logger;
-  pipableStreamOptions: PipeableStreamOptions;
+  pageProps?: T;
+  PageComponent?: C;
+  route: string;
+  manifest: Manifest;
+  worker?: any;
+  importedCss?: Set<string>;
+  cssFiles: Map<string, CssContent>;
+  globalCss: Map<string, CssContent>;
+  build: Pick<
+    ResolvedUserOptions["build"],
+    | "outDir"
+    | "pages"
+    | "server"
+    | "static"
+    | "client"
+    | "rscOutputPath"
+    | "htmlOutputPath"
+  >;
+};
+
+export interface ResolvePageOptions {
+  pagePath: string;
+  pageExportName: string;
+  url: string;
+}
+
+export interface ResolvePropsOptions {
+  propsPath: string;
+  propsExportName: string;
+  url: string;
 }
 
 export type ModuleLoader = (
@@ -225,19 +500,6 @@ export type StreamResult =
   | { type: "error"; error: unknown }
   | { type: "skip" };
 
-export interface RscStreamOptions {
-  Page: React.ComponentType;
-  props: any;
-  Html: any;
-  logger?: Console | import("vite").Logger;
-  cssFiles?: string[];
-  htmlProps: any;
-  route: string;
-  url: string;
-  pipableStreamOptions?: PipeableStreamOptions;
-  moduleBasePath: string;
-}
-
 export interface RouteConfig {
   path: string;
   // Define page/props paths using patterns
@@ -268,9 +530,11 @@ export interface BuildConfig {
   outDir?: string;
   hash?: string;
   preserveModulesRoot?: boolean;
-  entryFile?: (n: PreRenderedChunk) => string;
-  chunkFile?: (n: PreRenderedChunk) => string;
-  assetFile?: (n: PreRenderedAsset) => string;
+  rscOutputPath?: string; // defaults: `index.rsc`
+  htmlOutputPath?: string; // defaults: `index.html`
+  entryFile?: (n: PreRenderedChunk, ssr: boolean) => string;
+  chunkFile?: (n: PreRenderedChunk, ssr: boolean) => string;
+  assetFile?: (n: PreRenderedAsset, ssr: boolean) => string;
 }
 
 export interface RscResolver {
@@ -343,16 +607,17 @@ export interface BuildTiming {
   buildEnd?: number;
   renderStart?: number;
   renderEnd?: number;
+  closeBundle?: number;
+  render?: number;
   total?: number;
 }
 
-export type CheckFilesExistReturn = {
+export type ResolvedBuildPages = {
   propsMap: Map<string, string>;
-  propsSet: Set<string>;
   pageMap: Map<string, string>;
-  pageSet: Set<string>;
-  urlMap: Map<string, {props: string, page: string}>;
-  errors: string[];
+  routeMap: Map<string, string[]>;
+  urlMap: Map<string, { props?: string; page: string }>;
+  errors: Error[];
 };
 
 // Add strict type checking for worker messages
@@ -361,7 +626,11 @@ export type WorkerMessage =
   | { type: "ERROR"; error: string | Error }
   | { type: "RSC_CHUNK"; id: string; chunk: Buffer }
   | { type: "RSC_END"; id: string }
-  | { type: "SHUTDOWN" };
+  | { type: "SHUTDOWN"; id: string }
+  | { type: "SHUTDOWN_COMPLETE" }
+  | { type: "CHUNK_PROCESSED"; id: string; success: boolean }
+  | { type: "CHUNK_ERROR"; id: string; error: string }
+  | { type: "METRICS"; metrics: StreamMetrics };
 
 // Add branded types for safety
 export type ModuleId = string & { readonly __brand: unique symbol };
@@ -371,52 +640,194 @@ export type HtmlProps = {
   pageProps: any;
   route: string;
   url: string;
-  cssFiles: string[];
+  projectRoot: string;
+  moduleBase: string;
+  moduleBaseURL: string;
+  moduleBasePath: string;
+  moduleRootPath: string;
+  cssFiles: Map<string, CssContent>;
+  manifest: Manifest;
+  CssCollector: React.FC<React.PropsWithChildren<CssCollectorProps>>;
+  globalCss: Map<string, CssContent>;
 };
 
 export interface PageAsset {
-  type: 'css' | 'js';
+  type: "css" | "js";
   path: string;
   parentUrl: string;
 }
 
-export interface PageData {
-  route: string;
-  clientComponents?: string[];
-  html?: {
-    raw: string;
-    transformed?: string;
-    assets: PageAsset[];
-  };
-  rsc?: {
-    content: string;
-    modules: Array<[string, string]>; // [modulePath, exportName]
-  };
-}
+type BaseCssProps = {
+  as: string;
+  id: string;
+};
+
+type CssProps = BaseCssProps & {
+  as: "link";
+  type?: never;
+  children?: InlineCssProps extends false ? never : React.ReactNode;
+  id: string;
+  href: string;
+  rel: "stylesheet";
+  precedence?: string;
+};
+type InlineCssProps = BaseCssProps & {
+  as: "style";
+  type: "text/css";
+  children?: React.ReactNode;
+  precedence?: never;
+  rel?: never;
+  href?: never;
+};
+
+export type CssContent<InlineCSS extends boolean | undefined = undefined> =
+  InlineCSS extends true
+    ? InlineCssProps
+    : InlineCSS extends false
+    ? CssProps
+    : CssProps | InlineCssProps;
 
-export interface CssContent {
+export interface JsContent {
   type?: string;
   content: string;
   key?: string;
   path: string;
+  id?: string;
 }
 
+export type CssCollectorProps<
+  InlineCSS extends boolean | undefined = undefined
+> = {
+  // to render the head tag or not
+  as?: React.ElementType;
+  children?: React.ReactNode;
+  /** A map containing all the css files imported by the route and their proxy values
+   * - when inlineCss is true, will contain the `content` property
+   * - when prugeCss is true, will contain the module proxy which includes a `userClasses`
+   * @example ```tsx
+   * import styles from './styles.module.css';
+   * export const Page = () => {
+   *  return <div className={styles.userClass}>Hello World</div>
+   * }
+   * ```
+   * then the module will basically contain whatever `styles` exported here. But how does it track css class usages
+   * during streaming?
+   *
+   * const tags = Array.from(importedCss?.values() ?? []).map(cssFile => {
+   *  return <link rel="stylesheet" href={cssFile.path} />
+   * })
+   * ```
+   *
+   *
+   * */
+
+  cssFiles?: Map<string, CssContent<InlineCSS>>;
+} & React.HTMLAttributes<HTMLElement>;
+
 export interface InlineCssCollectorProps {
-  cssFiles: CssContent[];
-  root: string;
+  cssFiles: Map<string, CssContent>;
   moduleBaseURL: string;
-  moduleBasePath: string;
   moduleRootPath: string;
-  route: string;
+  moduleBasePath: string;
+  route?: string;
+  purgeCss?: boolean;
   children?: React.ReactNode;
 }
 
-export interface CssCollectorProps {
-  cssFiles: CssContent[];
-  root: string;
-  moduleBaseURL: string;
-  moduleBasePath: string;
-  moduleRootPath: string;
-  route: string;
-  children?: React.ReactNode;
-}
+export interface HtmlRenderState {
+  id: string;
+  rscStream: PassThrough;
+  htmlStream: PassThrough;
+  progressStream: PassThrough;
+  errorTransform: Transform;
+  htmlChunks: string[];
+  pipeableStreamOptions: Omit<
+    ReactServerDomEsmOptions,
+    "onError" | "onPostpone"
+  >;
+  streamState: StreamMetrics;
+}
+
+export type RenderPagesResult =
+  | {
+      type: "error";
+      error: Error;
+      failedRoutes: Set<string>;
+      completedRoutes: Set<string>;
+      htmlSizes: Map<string, number>;
+      rscSizes: Map<string, number>;
+      streamMetrics: StreamMetrics;
+      results: Map<
+        string,
+        {
+          html: PassThrough;
+          rsc: PassThrough;
+          metrics: {
+            rscFull: StreamMetrics;
+            rscHeadless: StreamMetrics;
+          };
+        }
+      >;
+    }
+  | {
+      type: "success";
+      completedRoutes: Set<string>;
+      failedRoutes?: never;
+      htmlSizes: Map<string, number>;
+      rscSizes: Map<string, number>;
+      streamMetrics: StreamMetrics;
+      results: Map<
+        string,
+        {
+          html: PassThrough;
+          rsc: PassThrough;
+          metrics: {
+            rscFull: StreamMetrics;
+            rscHeadless: StreamMetrics;
+          };
+        }
+      >;
+    };
+
+export type HandlerAssets = {
+  css: CssContent[];
+  js: string[];
+  bootstrapModules: string[];
+};
+
+export type CreateHandlerResult =
+  | {
+      type: "success";
+      controller: AbortController;
+      stream: any;
+      assets: {
+        css: CssContent[];
+        js: string[];
+        bootstrapModules: string[];
+      };
+      route: string;
+      metrics: StreamMetrics;
+    }
+  | { type: "error"; error: Error }
+  | { type: "skip" };
+
+export type ReactStaticEvent =
+  | FileWriteEvent
+  | {
+      type: "build.start";
+      data: {
+        pages: string[];
+        files: Array<[string, { page: string; props?: string }]>;
+      };
+    };
+
+// Define LoaderContext interface locally
+export interface LoaderContext {
+  data?: { port?: MessagePort };
+}
+// Add type declaration for import.meta.cssModules
+declare global {
+  interface ImportMeta {
+    cssModules?: Record<string, Record<string, string>>;
+  }
+}