@rangojs/router 0.0.0-experimental.eb0645d3 → 0.0.0-experimental.f1468e3c

package/src/vite/plugins/virtual-entries.ts

@@ -1,8 +1,3 @@
-/**
- * Default virtual entry file contents for rsc-router.
- * These are used when users don't provide their own entry files.
- */
-
 export const VIRTUAL_ENTRY_BROWSER: string = `
 import {
   createFromReadableStream,
@@ -14,7 +9,7 @@ import {
 import { createElement, StrictMode } from "react";
 import { hydrateRoot } from "react-dom/client";
 import { rscStream } from "@rangojs/router/internal/deps/html-stream-client";
-import { initBrowserApp, RSCRouter } from "@rangojs/router/browser";
+import { initBrowserApp, Rango } from "@rangojs/router/browser";
 
 async function initializeApp() {
   const deps = {
@@ -25,11 +20,16 @@ async function initializeApp() {
     createTemporaryReferenceSet,
   };
 
-  await initBrowserApp({ rscStream, deps });
+  // initBrowserApp resolves the initial payload and returns the browser app
+  // context, including strictMode (default true) from createRouter. StrictMode
+  // is the default; createRouter({ strictMode: false }) ships the opt-out in the
+  // payload metadata. StrictMode emits no DOM, so toggling never changes markup.
+  const { strictMode } = await initBrowserApp({ rscStream, deps });
 
+  const app = createElement(Rango);
   hydrateRoot(
     document,
-    createElement(StrictMode, null, createElement(RSCRouter))
+    strictMode === false ? app : createElement(StrictMode, null, app)
   );
 }
 
@@ -52,9 +52,31 @@ export const renderHTML = createSSRHandler({
 `.trim();
 
 /**
- * Generate the RSC entry content with the specified router path
+ * Virtual modules an RSC entry must import at startup to register the data the
+ * request handler needs before the first request arrives:
+ *
+ * - routes-manifest: the pre-generated route map so href()/matching work on a
+ *   cold start (full map in build, in-memory no-op in dev).
+ * - loader-manifest: setLoaderImports() for fetchable loaders. Critical for
+ *   serverless/multi-process deployments and for fetchable loaders reachable
+ *   only through a client component — without it those loaders are never
+ *   registered for the _rsc_loader endpoint and fail in production.
+ *
+ * Single source of truth: both the generated virtual RSC entry below and the
+ * custom-entry injector (version-injector) consume this list, so a new
+ * bootstrap manifest cannot be added to one path and forgotten on the other.
+ * That exact drift (loader-manifest present here but missing from the injector)
+ * is what left fetchable loaders unresolved on custom worker entries.
  */
+export const RSC_ENTRY_BOOTSTRAP_IMPORTS: readonly string[] = [
+  "virtual:rsc-router/routes-manifest",
+  "virtual:rsc-router/loader-manifest",
+];
+
 export function getVirtualEntryRSC(routerPath: string): string {
+  const bootstrapImports = RSC_ENTRY_BOOTSTRAP_IMPORTS.map(
+    (id) => `import "${id}";`,
+  ).join("\n");
   return `
 import {
   renderToReadableStream,
@@ -68,15 +90,9 @@ import { router } from "${routerPath}";
 import { createRSCHandler } from "@rangojs/router/internal/rsc-handler";
 import { VERSION } from "@rangojs/router:version";
 
-// Import loader manifest to ensure all fetchable loaders are registered at startup
-// This is critical for serverless/multi-process deployments where the loader module
-// might not be imported before a GET request arrives
-import "virtual:rsc-router/loader-manifest";
-
-// Import pre-generated route manifest so href() works immediately on cold start.
-// In build mode, this contains the full route map generated at build time.
-// In dev mode, this is a no-op (manifest is populated in-memory by the discovery plugin).
-import "virtual:rsc-router/routes-manifest";
+// Startup bootstrap imports (routes + loader manifests). See
+// RSC_ENTRY_BOOTSTRAP_IMPORTS — the same list the custom-entry injector uses.
+${bootstrapImports}
 
 // Lazily create the handler on first request so that ESM live bindings
 // have resolved by the time we read \`router\`. During HMR the module may
@@ -87,6 +103,11 @@ export default function handler(request, env) {
     _handler = createRSCHandler({
       router,
       version: VERSION,
+      // Forward the router's CSP nonce provider. createRSCHandler reads the
+      // provider only from options.nonce; without this, createRouter({ nonce })
+      // is silently dropped on the Node preset (the Cloudflare path wires it via
+      // router.fetch). router.nonce is undefined when unconfigured, a safe no-op.
+      nonce: router.nonce,
       deps: {
         renderToReadableStream,
         decodeReply,
@@ -104,9 +125,6 @@ export default function handler(request, env) {
 `.trim();
 }
 
-/**
- * Virtual module IDs
- */
 export const VIRTUAL_IDS = {
   browser: "virtual:rsc-router/entry.browser.js",
   ssr: "virtual:rsc-router/entry.ssr.js",
@@ -114,10 +132,6 @@ export const VIRTUAL_IDS = {
   version: "@rangojs/router:version",
 } as const;
 
-/**
- * Virtual module content for version.
- * Exports VERSION - a timestamp that changes on server restart (dev) or at build time (production).
- */
 export function getVirtualVersionContent(version: string): string {
   return `export const VERSION = ${JSON.stringify(version)};`;
 }

package/src/vite/rango.ts

@@ -1,4 +1,4 @@
-import type { PluginOption } from "vite";
+import { type PluginOption } from "vite";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { exposeActionId } from "./plugins/expose-action-id.js";
@@ -12,21 +12,37 @@ import { VIRTUAL_IDS } from "./plugins/virtual-entries.js";
 import {
   getExcludeDeps,
   getPackageAliases,
+  getPublishedPackageName,
+  getVendorAliases,
 } from "./utils/package-resolution.js";
 import { findRouterFiles } from "../build/generate-route-types.js";
 import { createVersionPlugin } from "./plugins/version-plugin.js";
 import {
-  sharedEsbuildOptions,
+  sharedRolldownOptions,
   createVirtualEntriesPlugin,
   onwarn,
   getManualChunks,
 } from "./utils/shared-utils.js";
+import {
+  resolveClientChunks,
+  type ClientChunkContext,
+} from "./utils/client-chunks.js";
 import type { RangoOptions } from "./plugin-types.js";
 import { printBanner, rangoVersion } from "./utils/banner.js";
 import { createVersionInjectorPlugin } from "./plugins/version-injector.js";
 import { createCjsToEsmPlugin } from "./plugins/cjs-to-esm.js";
 import { createRouterDiscoveryPlugin } from "./router-discovery.js";
 import { performanceTracksPlugin } from "./plugins/performance-tracks.js";
+import { createRangoDebugger, NS } from "./debug.js";
+
+const debugConfig = createRangoDebugger(NS.config);
+
+// The leading-directive 'use client' sniff is shared with version-plugin's
+// getClientModuleSignature so the two cannot drift. Imported for local use by the
+// HMR transform below and re-exported because the E8 sniff test imports it from
+// this module.
+import { hasUseClientDirective } from "./utils/directive-prologue.js";
+export { hasUseClientDirective };
 
 /**
  * Vite plugin for @rangojs/router.
@@ -53,25 +69,47 @@ import { performanceTracksPlugin } from "./plugins/performance-tracks.js";
  * ```
  */
 export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
+  const rangoStart = performance.now();
   const resolvedOptions: RangoOptions = options ?? { preset: "node" };
   const preset = resolvedOptions.preset ?? "node";
   const showBanner = resolvedOptions.banner ?? true;
+  const clientChunksOption = resolvedOptions.clientChunks ?? true;
+  const useBuiltInClientChunks = clientChunksOption === true;
+  const clientChunkCtx: ClientChunkContext | undefined = useBuiltInClientChunks
+    ? { fallbackRefs: new Set<string>() }
+    : undefined;
+  const clientChunks = resolveClientChunks(clientChunksOption, clientChunkCtx);
+  debugConfig?.("rango(%s) setup start", preset);
 
   const plugins: PluginOption[] = [];
 
-  // Get package resolution info (workspace vs npm install)
-  const rangoAliases = getPackageAliases();
+  // Get package resolution info (workspace vs npm install).
+  // Vendor aliases redirect the bare plugin-rsc vendor specs (which plugin-rsc
+  // itself injects into optimizeDeps.include) to absolute paths resolved from
+  // this package — so strict-pnpm consumers don't hit "Failed to resolve
+  // dependency" warnings when those deps aren't hoisted to their app root.
+  const rangoAliases = { ...getPackageAliases(), ...getVendorAliases() };
   const excludeDeps = [
     ...getExcludeDeps(),
-    // The public browser entry re-exports the RSDW browser client.
-    // Excluding both keeps Vite from freezing the unpatched bundle into
-    // .vite/deps before our source transforms run.
+    // plugin-rsc itself injects these into the client env's
+    // optimizeDeps.include, which overrides exclude for the dep's own
+    // pre-bundle entry. What exclude still controls is how *other*
+    // pre-bundled deps treat imports of these specs (external vs inlined)
+    // via esbuildCjsExternalPlugin. The cjs-to-esm transform in
+    // plugins/cjs-to-esm.ts is the fallback for strict-pnpm consumers,
+    // where client.browser's bare include fails to resolve and Vite ends up
+    // serving the raw CJS file at dev-serve time.
     "@vitejs/plugin-rsc/browser",
-    // Keep the browser RSDW client out of Vite's dep optimizer so our
-    // cjs-to-esm transform can patch the real file.
     "@vitejs/plugin-rsc/vendor/react-server-dom/client.browser",
   ];
 
+  // Vite supports a nested `A > B` syntax in optimizeDeps.include that resolves
+  // B from A's location. We anchor transitive deps (rsc-html-stream,
+  // @vitejs/plugin-rsc/vendor/*) to @rangojs/router so pnpm consumers — where
+  // these aren't visible at the app root — can still pre-bundle them.
+  const pkg = getPublishedPackageName();
+  const nested = (spec: string) => `${pkg} > ${spec}`;
+
   // Mutable ref for router path (node preset only).
   // Set immediately when user-specified, or populated by the auto-discover
   // config() hook using Vite's resolved root.
@@ -82,14 +120,8 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
   const prerenderEnabled = true;
 
   if (preset === "cloudflare") {
-    // Cloudflare preset: configure entries for cloudflare worker setup
-    // Router is not needed here - worker.rsc.tsx imports it directly
-
-    // Dynamically import @vitejs/plugin-rsc
     const { default: rsc } = await import("@vitejs/plugin-rsc");
 
-    // Only client and ssr entries - rsc entry is handled by cloudflare plugin
-    // Always use virtual modules for cloudflare preset
     const finalEntries: { client: string; ssr: string } = {
       client: VIRTUAL_IDS.browser,
       ssr: VIRTUAL_IDS.ssr,
@@ -100,16 +132,21 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
       enforce: "pre",
 
       config() {
-        // Configure environments for cloudflare deployment
         return {
-          // Exclude rsc-router modules from optimization to prevent module duplication
-          // This ensures the same Context instance is used by both browser entry and RSC proxy modules
           optimizeDeps: {
             exclude: excludeDeps,
-            esbuildOptions: sharedEsbuildOptions,
+            rolldownOptions: sharedRolldownOptions,
           },
           resolve: {
             alias: rangoAliases,
+            // Force a single React/React-DOM copy across all three RSC
+            // environments. RSC requires exactly one react/react-dom instance
+            // per environment runtime; consumer install topologies (pnpm
+            // strict layout, experimental React pins, third-party "use client"
+            // packages) can otherwise resolve duplicate copies, causing
+            // "Invalid hook call" / lost context. Child environments inherit
+            // this root dedupe, and Vite merges it with any consumer dedupe.
+            dedupe: ["react", "react-dom"],
           },
           build: {
             rollupOptions: { onwarn },
@@ -118,30 +155,22 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
             client: {
               build: {
                 rollupOptions: {
+                  onwarn,
                   output: {
                     manualChunks: getManualChunks,
                   },
                 },
               },
-              // Pre-bundle rsc-html-stream to prevent discovery during first request
-              // Exclude rsc-router modules to ensure same Context instance
               optimizeDeps: {
-                include: ["rsc-html-stream/client"],
+                include: [nested("rsc-html-stream/client")],
                 exclude: excludeDeps,
-                esbuildOptions: sharedEsbuildOptions,
+                rolldownOptions: sharedRolldownOptions,
               },
             },
             ssr: {
-              // Build SSR inside RSC directory so wrangler can deploy self-contained dist/rsc
               build: {
                 outDir: "./dist/rsc/ssr",
               },
-              resolve: {
-                // Ensure single React instance in SSR child environment
-                dedupe: ["react", "react-dom"],
-              },
-              // Pre-bundle SSR entry and React for proper module linking with childEnvironments
-              // All deps must be listed to avoid late discovery triggering ERR_OUTDATED_OPTIMIZED_DEP
               optimizeDeps: {
                 entries: [finalEntries.ssr],
                 include: [
@@ -151,26 +180,27 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
                   "react-dom/static.edge",
                   "react/jsx-runtime",
                   "react/jsx-dev-runtime",
-                  "rsc-html-stream/server",
-                  "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge",
+                  nested("rsc-html-stream/server"),
+                  nested(
+                    "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge",
+                  ),
                 ],
                 exclude: excludeDeps,
-                esbuildOptions: sharedEsbuildOptions,
+                rolldownOptions: sharedRolldownOptions,
               },
             },
             rsc: {
-              // RSC environment needs exclude list and esbuild options
-              // Exclude rsc-router modules to prevent createContext in RSC environment
               optimizeDeps: {
-                // Pre-bundle all RSC deps to prevent late discovery triggering ERR_OUTDATED_OPTIMIZED_DEP
                 include: [
                   "react",
                   "react/jsx-runtime",
                   "react/jsx-dev-runtime",
-                  "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge",
+                  nested(
+                    "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge",
+                  ),
                 ],
                 exclude: excludeDeps,
-                esbuildOptions: sharedEsbuildOptions,
+                rolldownOptions: sharedRolldownOptions,
               },
             },
           },
@@ -191,26 +221,16 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
     });
 
     plugins.push(createVirtualEntriesPlugin(finalEntries));
-
-    // Dev-only: RSDW client patch for React Performance Tracks
     plugins.push(performanceTracksPlugin());
-
-    // Add RSC plugin with cloudflare-specific options
-    // Note: loadModuleDevProxy should NOT be used with childEnvironments
-    // since SSR runs in workerd alongside RSC
     plugins.push(
       rsc({
         entries: finalEntries,
         serverHandler: false,
+        clientChunks,
       }) as PluginOption,
     );
-
-    // Deduplicate client references from third-party packages in dev mode.
-    // Prevents module duplication when server components import "use client"
-    // packages that are also imported directly by client components.
     plugins.push(clientRefDedup());
   } else {
-    // Auto-discover router using Vite's resolved root (not process.cwd())
     plugins.push({
       name: "@rangojs/router:auto-discover",
       config(userConfig) {
@@ -231,20 +251,17 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
                 "  - " + (f.startsWith(root) ? f.slice(root.length + 1) : f),
             )
             .join("\n");
-          throw new Error(`[rsc-router] Multiple routers found:\n${list}`);
+          throw new Error(`[rango] Multiple routers found:\n${list}`);
         }
-        // 0 found: routerRef.path stays undefined, warn at startup via discovery plugin
       },
     });
 
-    // Always use virtual entries for client, ssr, and rsc
     const finalEntries = {
       client: VIRTUAL_IDS.browser,
       ssr: VIRTUAL_IDS.ssr,
       rsc: VIRTUAL_IDS.rsc,
     };
 
-    // Dynamically import @vitejs/plugin-rsc
     const { default: rsc } = await import("@vitejs/plugin-rsc");
 
     let hasWarnedDuplicate = false;
@@ -257,18 +274,27 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
         return {
           optimizeDeps: {
             exclude: excludeDeps,
-            esbuildOptions: sharedEsbuildOptions,
+            rolldownOptions: sharedRolldownOptions,
           },
           build: {
             rollupOptions: { onwarn },
           },
           resolve: {
             alias: rangoAliases,
+            // Force a single React/React-DOM copy across all three RSC
+            // environments. RSC requires exactly one react/react-dom instance
+            // per environment runtime; consumer install topologies (pnpm
+            // strict layout, experimental React pins, third-party "use client"
+            // packages) can otherwise resolve duplicate copies, causing
+            // "Invalid hook call" / lost context. Child environments inherit
+            // this root dedupe, and Vite merges it with any consumer dedupe.
+            dedupe: ["react", "react-dom"],
           },
           environments: {
             client: {
               build: {
                 rollupOptions: {
+                  onwarn,
                   output: {
                     manualChunks: getManualChunks,
                   },
@@ -280,10 +306,10 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
                   "react-dom",
                   "react/jsx-runtime",
                   "react/jsx-dev-runtime",
-                  "rsc-html-stream/client",
+                  nested("rsc-html-stream/client"),
                 ],
                 exclude: excludeDeps,
-                esbuildOptions: sharedEsbuildOptions,
+                rolldownOptions: sharedRolldownOptions,
                 entries: [VIRTUAL_IDS.browser],
               },
             },
@@ -297,10 +323,12 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
                   "react-dom/static.edge",
                   "react/jsx-runtime",
                   "react/jsx-dev-runtime",
-                  "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge",
+                  nested(
+                    "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge",
+                  ),
                 ],
                 exclude: excludeDeps,
-                esbuildOptions: sharedEsbuildOptions,
+                rolldownOptions: sharedRolldownOptions,
               },
             },
             rsc: {
@@ -310,9 +338,17 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
                   "react",
                   "react/jsx-runtime",
                   "react/jsx-dev-runtime",
-                  "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge",
+                  nested(
+                    "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge",
+                  ),
                 ],
-                esbuildOptions: sharedEsbuildOptions,
+                // Vite 8 does not propagate the top-level optimizeDeps.exclude
+                // (set in config()) to non-client envs, so the rsc env must set
+                // it explicitly — mirroring the node ssr env and the cloudflare
+                // rsc env. Without it a strict-pnpm npm-installed app can try to
+                // pre-bundle the router's own subpath entries and fail.
+                exclude: excludeDeps,
+                rolldownOptions: sharedRolldownOptions,
               },
             },
           },
@@ -337,42 +373,24 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
         if (rscMinimalCount > 1 && !hasWarnedDuplicate) {
           hasWarnedDuplicate = true;
           console.warn(
-            "[rsc-router] Duplicate @vitejs/plugin-rsc detected. " +
+            "[rango] Duplicate @vitejs/plugin-rsc detected. " +
               "Remove rsc() from your vite config — rango() includes it automatically.",
           );
         }
       },
     });
 
-    // Add virtual entries plugin (RSC entry generated lazily from routerRef)
     plugins.push(createVirtualEntriesPlugin(finalEntries, routerRef));
-
-    // Dev-only: RSDW client patch for React Performance Tracks
     plugins.push(performanceTracksPlugin());
-
     plugins.push(
       rsc({
         entries: finalEntries,
+        clientChunks,
       }) as PluginOption,
     );
-
-    // Deduplicate client references from third-party packages in dev mode.
-    // Prevents module duplication when server components import "use client"
-    // packages that are also imported directly by client components.
     plugins.push(clientRefDedup());
   }
 
-  // Fix HMR for "use client" components.
-  //
-  // @vitejs/plugin-rsc's hotUpdate returns undefined for "use client" files
-  // in the RSC environment. Vite then tries to propagate through the RSC
-  // module graph, but the proxy module has no import.meta.hot.accept()
-  // boundary, causing a full page reload. The client env would handle it
-  // fine via React Refresh, but the RSC env's full-reload arrives first.
-  //
-  // Fix: in the RSC env, return [] for "use client" files to signal
-  // "handled, nothing to propagate". The client env is left alone so
-  // React Refresh processes the update normally.
   plugins.push({
     name: "@rangojs/router:client-component-hmr",
     hotUpdate(ctx) {
@@ -391,72 +409,45 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
 
       try {
         const source = readFileSync(file, "utf-8");
-        const trimmed = source.trimStart();
-        if (
-          trimmed.startsWith('"use client"') ||
-          trimmed.startsWith("'use client'")
-        ) {
-          // Consume the update in RSC/SSR envs. The proxy module was already
-          // re-transformed by the RSC plugin's hotUpdate. Without this, Vite
-          // tries to propagate through the RSC/SSR module graph where the proxy
-          // has no import.meta.hot.accept() boundary, triggering a full reload.
-          // The actual component update is handled by React Refresh in the
-          // client environment.
+        if (hasUseClientDirective(source)) {
           return [];
         }
-      } catch {
-        // File deleted/moved during HMR, let default handling proceed
-      }
+      } catch {}
     },
   });
 
   plugins.push(exposeActionId());
-
-  // "use cache" directive transform (enforce: "post"):
-  // Wraps exports with registerCachedFunction() for function-level caching.
   plugins.push(useCacheTransform());
-
-  // Consolidated plugin for create* ID injection (enforce: "post"):
-  // loaders, handles, location state, and prerender handlers.
   plugins.push(exposeInternalIds());
-
-  // Router ID injection runs at normal priority (no enforce) to avoid
-  // changing Vite's dep optimization timing.
   plugins.push(exposeRouterId());
-
-  // Add version virtual module plugin for cache invalidation
   plugins.push(createVersionPlugin());
 
-  // Entry path for discovery: user-specified value (if any) or undefined.
-  // Auto-discovered path is passed separately via routerRef.
-  // Cloudflare preset: deferred to configResolved (read from resolved Vite env config).
   const discoveryEntryPath =
     preset !== "cloudflare" ? routerRef.path : undefined;
-  // Ref for deferred auto-discovery (node preset only, undefined for cloudflare)
   const discoveryRouterRef = preset !== "cloudflare" ? routerRef : undefined;
 
-  // Version injector: auto-injects VERSION and routes-manifest into the RSC entry.
-  // For cloudflare preset, the entry is resolved lazily in configResolved.
-  // For node preset, the virtual entry already includes these imports.
   if (preset === "cloudflare") {
     plugins.push(createVersionInjectorPlugin(undefined));
   }
 
-  // Transform CJS vendor files to ESM for browser compatibility
-  // optimizeDeps.include doesn't work because the file is loaded after initial optimization
   plugins.push(createCjsToEsmPlugin());
-
-  // Router discovery plugin for build-time manifest generation.
-  // For cloudflare, the entry is resolved lazily in configResolved from the RSC environment.
-  // For node, discoveryRouterRef provides the auto-discovered path when not user-specified.
   plugins.push(
     createRouterDiscoveryPlugin(discoveryEntryPath, {
       routerPathRef: discoveryRouterRef,
       enableBuildPrerender: prerenderEnabled,
       buildEnv: options?.buildEnv,
       preset,
+      prerenderOnError: options?.prerender?.onError,
+      discovery: options?.discovery,
+      clientChunkCtx,
     }),
   );
 
+  debugConfig?.(
+    "rango(%s) setup done: %d plugin(s) (%sms)",
+    preset,
+    plugins.length,
+    (performance.now() - rangoStart).toFixed(1),
+  );
   return plugins;
 }