@rangojs/router 0.20.0 → 0.22.0

package/src/vite/router-discovery.ts

@@ -8,8 +8,8 @@
 
 import type { Plugin, ViteDevServer } from "vite";
 import { createServer as createViteServer } from "vite";
-import { resolve } from "node:path";
-import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
 import { createRequire, register } from "node:module";
 import { pathToFileURL } from "node:url";
 import {
@@ -34,6 +34,7 @@ import {
   internalDebugNoCacheMiddleware,
 } from "./inject-client-debug.js";
 import { createVersionPlugin } from "./plugins/version-plugin.js";
+import { uniformVersions } from "../router-versions.js";
 import { getVirtualEntrySSR, VIRTUAL_IDS } from "./plugins/virtual-entries.js";
 import { createVirtualStubPlugin } from "./plugins/virtual-stub-plugin.js";
 import {
@@ -64,6 +65,13 @@ import {
   refreshRecordedClientUrlProjections,
 } from "./discovery/client-urls-projection.js";
 import { runShellPrerenderPhase } from "./discovery/shell-prerender-phase.js";
+import { runRouterVersionsPhase } from "./discovery/router-versions-phase.js";
+import {
+  recordBundleFiles,
+  recordClientGraph,
+  recordServerGraph,
+  recordVersionModuleFiles,
+} from "./discovery/build-versions.js";
 import { describeDiscoveryFailure } from "./discovery/discovery-errors.js";
 import { findTransitionWhenError } from "../transition-when-ref.js";
 import { transitionWhenHoistPlugin } from "./plugins/transition-when-hoist.js";
@@ -320,11 +328,44 @@ import type {
   BuildEnvResult,
 } from "./plugin-types.js";
 
+const WRANGLER_CONFIG_NAMES: readonly string[] = [
+  "wrangler.json",
+  "wrangler.jsonc",
+  "wrangler.toml",
+];
+
+/**
+ * getPlatformProxy() looks for the wrangler config from process.cwd() and
+ * resolves its default persist path against cwd, so building from another
+ * directory dropped the app's bindings (#1037). Search upward from the Vite
+ * root with wrangler's own file names and order. Persisted state goes under
+ * the Vite root, where @cloudflare/vite-plugin reads it in dev and preview
+ * (its getPersistenceRoot), also when the config sits above the root. No
+ * config found: no options, wrangler's own lookup.
+ */
+function wranglerProxyOptions(
+  root: string,
+): Record<string, unknown> | undefined {
+  const viteRoot = resolve(root);
+  for (let dir = viteRoot; ; dir = dirname(dir)) {
+    for (const name of WRANGLER_CONFIG_NAMES) {
+      const configPath = join(dir, name);
+      if (existsSync(configPath)) {
+        return {
+          configPath,
+          persist: { path: join(viteRoot, ".wrangler", "state", "v3") },
+        };
+      }
+    }
+    if (dirname(dir) === dir) return undefined;
+  }
+}
+
 /**
  * Resolve the buildEnv option into a concrete { env, dispose? } result.
  * Handles all four input shapes: false, "auto", factory, plain object.
  */
-async function resolveBuildEnv(
+export async function resolveBuildEnv(
   option: BuildEnvOption | undefined,
   factoryCtx: BuildEnvFactoryContext,
 ): Promise<BuildEnvResult | null> {
@@ -348,7 +389,9 @@ async function resolveBuildEnv(
       )) as {
         getPlatformProxy: (opts?: any) => Promise<any>;
       };
-      const proxy = await getPlatformProxy();
+      const proxy = await getPlatformProxy(
+        wranglerProxyOptions(factoryCtx.root),
+      );
       return {
         env: proxy.env as Record<string, unknown>,
         dispose: proxy.dispose,
@@ -410,6 +453,7 @@ function resetPrerenderCollection(s: DiscoveryState): void {
   s.staticManifestEntries = null;
   s.shellCandidates = null;
   s.prerenderPayloadValues = null;
+  s.buildData = [];
 }
 
 /**
@@ -947,6 +991,14 @@ export function createRouterDiscoveryPlugin(
             (globalThis as any).__rscRouterDiscoveryActive ?? false,
           );
           s.devServerOrigin = getDevServerOrigin();
+          // The temp Node realm below shares this globalThis and runs the dev
+          // /__rsc_shell capture, which must replay the prerender store as
+          // the worker's HIT does: a capture that renders the Prerender
+          // handler live stores a doc record the HIT never reads, and the
+          // HIT loses the loader pushes its prelude rendered (#1057). That
+          // realm never evaluates the virtual module that sets this on the
+          // Node preset.
+          globalThis.__PRERENDER_DEV_URL = s.devServerOrigin;
 
           // Create a temp Node.js server to run runtime discovery and generate
           // named route types (static parser can't resolve factory calls).
@@ -1533,7 +1585,7 @@ export function createRouterDiscoveryPlugin(
               maxSnapshotBytes,
               captureTimeout,
               buildEnv: s.resolvedBuildEnv,
-              buildVersion: version,
+              versions: uniformVersions(version),
               captureShellHTML: ssrModule.captureShellHTML,
               debug: !!debugDiscovery,
             });
@@ -2261,18 +2313,27 @@ export function createRouterDiscoveryPlugin(
       }
     },
 
-    // Post-build PPR shell capture (producer B, #699): runs after EVERY
-    // environment bundle is written — the shell prelude embeds built client
-    // asset URLs (bootstrap entry), which do not exist at buildStart. The
-    // kept temp server and the buildEnv were deferred AS A PAIR in
-    // buildStart's finally; this finally is the pair's success-path owner
-    // (buildEnd below owns the aborted-build path) — the phase itself is a
-    // pure producer and tears down only the globals it installs.
+    // Post-build phases, after EVERY environment bundle is written.
+    //
+    // 1. Cache versions (discovery/router-versions-phase.ts): hashes the
+    //    server output as postprocessBundle left it and writes the per-router
+    //    table into the built version module. First, because phase 2 stamps
+    //    its entries with these versions and reads the same RSC out dir.
+    // 2. PPR shell capture (producer B, #699): the shell prelude embeds built
+    //    client asset URLs (bootstrap entry), which do not exist at
+    //    buildStart. The kept temp server and the buildEnv were deferred AS A
+    //    PAIR in buildStart's finally; this finally is the pair's success-path
+    //    owner (buildEnd below owns the aborted-build path) — the phase itself
+    //    is a pure producer and tears down only the globals it installs.
     buildApp: {
       order: "post",
       async handler(builder) {
         try {
-          await runShellPrerenderPhase(s, builder as any);
+          await runShellPrerenderPhase(
+            s,
+            builder as any,
+            runRouterVersionsPhase(s, builder as any),
+          );
         } finally {
           if (s.isBuildMode) {
             const tempServer = s.shellPhaseTempServer;
@@ -2387,6 +2448,22 @@ export function createRouterDiscoveryPlugin(
     // Record handler chunk metadata and RSC entry filename during RSC build.
     // Used by closeBundle for handler code eviction and prerender data injection.
     generateBundle(_options: any, bundle: any) {
+      // Inputs of the per-router cache versions (discovery/build-versions.ts).
+      // Each pass overwrites its slot: plugin-rsc runs the RSC and SSR builds
+      // twice, and the real pass comes last.
+      if (s.isBuildMode) {
+        const envName = this.environment?.name;
+        if (envName) {
+          s.versionModuleFiles.set(envName, recordVersionModuleFiles(bundle));
+        }
+        if (envName === "rsc") {
+          s.serverBuildGraph = recordServerGraph(this, bundle);
+        } else if (envName === "client") {
+          s.clientBuildGraph = recordClientGraph(this, bundle);
+        } else if (envName === "ssr") {
+          s.ssrBundle = recordBundleFiles(bundle);
+        }
+      }
       if (this.environment?.name !== "rsc") return;
       const genStart = debugBuild ? performance.now() : 0;
 
@@ -2428,6 +2505,12 @@ export function createRouterDiscoveryPlugin(
             s.resolvedPrerenderModules,
             "Prerender",
             false,
+            // Mark onDemand exports (retained, not evicted) from the
+            // discovery-derived $$id set — the same evaluated source that sets
+            // the runtime od trie flag, so retention and serve can never
+            // disagree. Populated by discoverRouters (buildStart), which runs
+            // before this generateBundle pass.
+            s.onDemandHandlerIds,
           );
           if (handlers.length > 0) {
             const existing = s.handlerChunkInfoMap.get(fileName);

package/src/vite/utils/bundle-analysis.ts

@@ -29,20 +29,40 @@ export function findMatchingParenInBundle(
 
 /**
  * Scan a bundled chunk for handler exports and extract their names + $$id values.
- * Optionally detects passthrough flag. @internal Exported for testing only.
+ * Optionally detects the passthrough flag by parsing the call body, and marks
+ * onDemand from the authoritative discovery-derived handlerId set.
+ * @internal Exported for testing only.
  */
 export function extractHandlerExportsFromChunk(
   chunkCode: string,
   handlerModules: Map<string, string[]>,
   fnName: string,
   detectPassthrough: boolean,
-): Array<{ name: string; handlerId: string; passthrough: boolean }> {
+  // handlerIds ($$id) of routes the evaluated source marks onDemand — the
+  // single source of truth shared with the runtime od trie flag. Keyed on the
+  // same $$id the chunk scan extracts, so any spelling of the option (literal,
+  // spread, imported const) retains the producer; a textual scan of the call
+  // body cannot see non-literal spellings and silently evicted them.
+  onDemandHandlerIds?: ReadonlyMap<string, string>,
+): Array<{
+  name: string;
+  handlerId: string;
+  passthrough: boolean;
+  onDemand: boolean;
+}> {
   const handlers: Array<{
     name: string;
     handlerId: string;
     passthrough: boolean;
+    onDemand: boolean;
   }> = [];
 
+  // Only parse a call body (an O(callBody) paren walk per export) when the whole
+  // chunk actually contains the marker we're detecting — the common case (no
+  // passthrough opt-in anywhere in the chunk) skips the walk entirely.
+  const scanPassthrough =
+    detectPassthrough && chunkCode.includes("passthrough");
+
   for (const [, handlerNames] of handlerModules) {
     for (const name of handlerNames) {
       const eName = escapeRegExp(name);
@@ -53,7 +73,7 @@ export function extractHandlerExportsFromChunk(
       if (!match) continue;
 
       let isPassthrough = false;
-      if (detectPassthrough) {
+      if (scanPassthrough) {
         const eFnName = escapeRegExp(fnName);
         const callStartRe = new RegExp(
           `(?:const|let|var)\\s+${eName}\\s*=\\s*${eFnName}\\s*(?:<[^>]*>)?\\s*\\(`,
@@ -68,7 +88,12 @@ export function extractHandlerExportsFromChunk(
           }
         }
       }
-      handlers.push({ name, handlerId: match[1], passthrough: isPassthrough });
+      handlers.push({
+        name,
+        handlerId: match[1],
+        passthrough: isPassthrough,
+        onDemand: onDemandHandlerIds?.has(match[1]) ?? false,
+      });
     }
   }
 
@@ -82,7 +107,12 @@ export function extractHandlerExportsFromChunk(
  */
 export function evictHandlerCode(
   code: string,
-  exports: Array<{ name: string; handlerId: string; passthrough?: boolean }>,
+  exports: Array<{
+    name: string;
+    handlerId: string;
+    passthrough?: boolean;
+    onDemand?: boolean;
+  }>,
   fnName: string,
   brand: string,
 ): { code: string; savedBytes: number } | null {
@@ -90,8 +120,10 @@ export function evictHandlerCode(
   let modified = code;
 
   const eFnName = escapeRegExp(fnName);
-  for (const { name, handlerId, passthrough } of exports) {
-    if (passthrough) continue;
+  for (const { name, handlerId, passthrough, onDemand } of exports) {
+    // Keep the producer body for passthrough (live fallback) and onDemand
+    // (router.prerender() must be able to invoke the retained producer).
+    if (passthrough || onDemand) continue;
 
     const eName = escapeRegExp(name);
     // Match const/let/var: Rolldown (Vite 8) emits top-level bindings in the

package/src/vite/utils/client-chunks.ts

@@ -206,8 +206,12 @@ export function resolveClientChunks(
   return option;
 }
 
+/** @vitejs/plugin-rsc's client-reference map; its group modules sit under it. */
+export const CLIENT_REFERENCES_MODULE_ID =
+  "\0virtual:vite-rsc/client-references";
+
 /** Module-id prefix of the per-group virtual module @vitejs/plugin-rsc emits. */
-const CLIENT_GROUP_PREFIX = "\0virtual:vite-rsc/client-references/group/";
+const CLIENT_GROUP_PREFIX = `${CLIENT_REFERENCES_MODULE_ID}/group/`;
 
 /**
  * Build-end group report under `DEBUG=rango:chunks`: one line per client

package/src/vite/utils/compare-strings.ts

@@ -0,0 +1,9 @@
+/**
+ * Code-unit order, the same on every machine. Generated modules and the cache
+ * version inputs are sorted with it: `localeCompare` depends on the build
+ * machine's ICU data, and build output has to be byte-identical across machines
+ * (discovery/build-versions.ts hashes it).
+ */
+export function compareStrings(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}

package/src/vite/utils/package-resolution.ts

@@ -72,11 +72,20 @@ export function getPackageAliases(): Record<string, string> {
   return aliases;
 }
 
+/**
+ * @vitejs/plugin-rsc puts these vendor specifiers in `optimizeDeps.include`,
+ * and Vite resolves them from the app root, where pnpm's strict layout does
+ * not link the plugin unless the app lists it (#1050). Aliased to the copy
+ * the router resolves, which therefore also wins over an app's own
+ * @vitejs/plugin-rsc. Must hold every vendor entry the plugin includes:
+ * optimize-deps-vendor-resolution.test.ts checks the resolved config.
+ */
 export function getVendorAliases(): Record<string, string> {
   const specs = [
     "@vitejs/plugin-rsc/vendor/react-server-dom/client.browser",
     "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge",
     "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge",
+    "@vitejs/plugin-rsc/vendor/react-server-dom/static.edge",
   ];
   const aliases: Record<string, string> = {};
   for (const spec of specs) {

package/src/vite/utils/prerender-utils.ts

@@ -199,8 +199,11 @@ export function resolvePrerenderError(
   throw error;
 }
 
+/** Build scratch space, relative to the project root. Never shipped. */
+export const RANGO_BUILD_DIR = "node_modules/.rangojs-router-build";
+
 function getStagedAssetDir(projectRoot: string): string {
-  return resolve(projectRoot, "node_modules/.rangojs-router-build/rsc-assets");
+  return resolve(projectRoot, RANGO_BUILD_DIR, "rsc-assets");
 }
 
 export function resetStagedBuildAssets(projectRoot: string): void {

package/src/vite/utils/shared-utils.ts

@@ -15,7 +15,7 @@ import type { HeadScriptsOption } from "../plugin-types.js";
 
 // Cloudflare preset: @cloudflare/vite-plugin sets optimizeDeps.entries (string
 // or array) on the rsc environment. Single source for both the discovery plugin
-// and the version injector so they target the same entry.
+// and the entry bootstrap injector so they target the same entry.
 export function resolveRscEntryFromConfig(
   config: ResolvedConfig,
 ): string | undefined {

package/dist/types/segment-content-promise.d.ts

@@ -1,13 +0,0 @@
-import type { ReactNode } from "react";
-/**
- * Return a stable Promise wrapping `component`, memoized on the component ref.
- *
- * A fresh `Promise.resolve(component)` each render would suspend for one
- * microtask and briefly commit the loading fallback inside Suspender — the
- * intercept / parallel-slot flicker this indirection prevents. Reusing the
- * same Promise ref keeps React's `use()` in "known fulfilled" state after
- * the first observation.
- *
- * @internal
- */
-export declare function getMemoizedContentPromise(component: ReactNode): Promise<ReactNode>;

package/src/segment-content-promise.ts

@@ -1,67 +0,0 @@
-import type { ReactNode } from "react";
-
-/**
- * Stable Promise wrappers keyed on the component itself. Objects (React
- * elements, functions, lazy payloads) land in a WeakMap so entries GC when
- * the underlying component is released; primitives (string, number, boolean,
- * null) land in a Map so memoization still applies to text-/null-backed
- * segments like those in partial-update flows. Keeping this cache outside
- * the segment eliminates preservation fields on ResolvedSegment — it survives
- * reconciliation naturally because the component ref is what's stable.
- *
- * Browser-only. On the server each SSR render needs a fresh pending promise
- * so Suspense can emit the loading fallback HTML before content streams. A
- * shared already-resolved promise has `.status === "fulfilled"` attached by
- * React on its first observation — subsequent `use()` calls return
- * synchronously without suspending, so the Suspense fallback never makes it
- * into the initial HTML. Route-definition components share refs across
- * requests, so a global cache would leak tracked state between renders.
- */
-const IS_BROWSER = typeof window !== "undefined";
-const objectContentCache = IS_BROWSER
-  ? new WeakMap<object, Promise<ReactNode>>()
-  : null;
-const primitiveContentCache = IS_BROWSER
-  ? new Map<unknown, Promise<ReactNode>>()
-  : null;
-
-/**
- * Return a stable Promise wrapping `component`, memoized on the component ref.
- *
- * A fresh `Promise.resolve(component)` each render would suspend for one
- * microtask and briefly commit the loading fallback inside Suspender — the
- * intercept / parallel-slot flicker this indirection prevents. Reusing the
- * same Promise ref keeps React's `use()` in "known fulfilled" state after
- * the first observation.
- *
- * @internal
- */
-export function getMemoizedContentPromise(
-  component: ReactNode,
-): Promise<ReactNode> {
-  if (component instanceof Promise) {
-    return component as Promise<ReactNode>;
-  }
-
-  if (!objectContentCache || !primitiveContentCache) {
-    return Promise.resolve(component);
-  }
-
-  if (component !== null && typeof component === "object") {
-    const cached = objectContentCache.get(component);
-    if (cached) {
-      return cached;
-    }
-    const promise = Promise.resolve(component);
-    objectContentCache.set(component, promise);
-    return promise;
-  }
-
-  const cached = primitiveContentCache.get(component);
-  if (cached) {
-    return cached;
-  }
-  const promise = Promise.resolve(component);
-  primitiveContentCache.set(component, promise);
-  return promise;
-}