@rangojs/router 0.0.0-experimental.88a3b2f7 → 0.0.0-experimental.8bcfea43

package/src/vite/router-discovery.ts

@@ -10,7 +10,7 @@ import type { Plugin } from "vite";
 import { createServer as createViteServer } from "vite";
 import { resolve } from "node:path";
 import { readFileSync } from "node:fs";
-import { createRequire } from "node:module";
+import { createRequire, register } from "node:module";
 import { pathToFileURL } from "node:url";
 import {
   formatNestedRouterConflictError,
@@ -19,6 +19,10 @@ import {
 } from "../build/generate-route-types.js";
 import { createVersionPlugin } from "./plugins/version-plugin.js";
 import { createVirtualStubPlugin } from "./plugins/virtual-stub-plugin.js";
+import {
+  BUILD_ENV_GLOBAL_KEY,
+  createCloudflareProtocolStubPlugin,
+} from "./plugins/cloudflare-protocol-stub.js";
 import {
   exposeInternalIds,
   exposeRouterId,
@@ -44,9 +48,56 @@ import {
 } from "./discovery/virtual-module-codegen.js";
 import { postprocessBundle } from "./discovery/bundle-postprocess.js";
 import { resetStagedBuildAssets } from "./utils/prerender-utils.js";
+import { createRangoDebugger, timed } from "./debug.js";
+
+const debugDiscovery = createRangoDebugger("rango:discovery");
+const debugRoutes = createRangoDebugger("rango:routes");
 
 export { VIRTUAL_ROUTES_MANIFEST_ID };
 
+// ============================================================================
+// Node ESM Loader Hook Registration
+// ============================================================================
+
+/**
+ * Registers a Node ESM loader hook that resolves `cloudflare:*` specifiers
+ * to a data: URL stub. Defense-in-depth alongside the Vite transform in
+ * `cloudflare-protocol-stub.ts`:
+ *
+ * - The Vite transform catches `cloudflare:*` imports in modules that flow
+ *   through Vite's plugin pipeline. That's the vast majority of cases.
+ * - The Node loader catches imports in modules that Vite/Rollup externalize
+ *   (e.g. the `partyserver` package, which has a top-level
+ *   `import { DurableObject, env } from "cloudflare:workers"` and ships
+ *   shapes plugin-rsc marks as external). Externalized modules are loaded
+ *   via Node's native ESM loader, which rejects URL schemes.
+ *
+ * Registration is process-global and one-shot. The hook only intercepts
+ * `cloudflare:*` specifiers; everything else passes through via
+ * `nextResolve()`. It runs in a separate worker thread (Node ESM loader
+ * architecture), so it can't read the `globalThis[BUILD_ENV_GLOBAL_KEY]`
+ * bridge that the Vite transform uses — the stubs served here always
+ * return `env = {}`. That's fine because externalized libraries don't
+ * typically access `env` at module top level; user source (where real
+ * `env` matters at build time) flows through the Vite transform.
+ */
+let loaderHookRegistered = false;
+function ensureCloudflareProtocolLoaderRegistered(): void {
+  if (loaderHookRegistered) return;
+  loaderHookRegistered = true;
+  try {
+    register(
+      new URL("./plugins/cloudflare-protocol-loader-hook.mjs", import.meta.url),
+    );
+  } catch (err: any) {
+    // register() requires Node 18.19+ / 20.6+. Older Node still has the
+    // Vite transform as primary defense.
+    console.warn(
+      `[rsc-router] Could not register Node ESM loader hook for cloudflare:* imports (${err?.message ?? err}). Falling back to Vite transform only.`,
+    );
+  }
+}
+
 // ============================================================================
 // Temp Server Factory
 // ============================================================================
@@ -66,6 +117,11 @@ async function createTempRscServer(
   state: DiscoveryState,
   options: { forceBuild?: boolean; cacheDir?: string } = {},
 ) {
+  // Install the Node ESM loader hook before any module evaluation so
+  // `cloudflare:*` specifiers in externalized/loader-delegated modules
+  // (e.g. packages plugin-rsc marks as external) resolve to stubs
+  // instead of crashing Node's native loader.
+  ensureCloudflareProtocolLoaderRegistered();
   const { default: rsc } = await import("@vitejs/plugin-rsc");
   return createViteServer({
     root: state.projectRoot,
@@ -88,6 +144,7 @@ async function createTempRscServer(
       ...(options.forceBuild ? [hashClientRefs(state.projectRoot)] : []),
       createVersionPlugin(),
       createVirtualStubPlugin(),
+      createCloudflareProtocolStubPlugin(),
       // Dev prerender must use dev-mode IDs (path-based) to match the workerd
       // runtime. forceBuild produces hashed IDs for production bundle consistency.
       exposeInternalIds(options.forceBuild ? { forceBuild: true } : undefined),
@@ -177,6 +234,11 @@ async function acquireBuildEnv(
 
   s.resolvedBuildEnv = result.env;
   s.buildEnvDispose = result.dispose ?? null;
+  // Bridge the resolved env into `cloudflare:workers`'s stubbed `env`
+  // export so user code that does `import { env } from "cloudflare:workers"`
+  // sees the real bindings proxy during discovery + prerender instead of
+  // an empty object. The stub reads this global at module-evaluation time.
+  (globalThis as Record<string, unknown>)[BUILD_ENV_GLOBAL_KEY] = result.env;
   return true;
 }
 
@@ -193,6 +255,7 @@ async function releaseBuildEnv(s: DiscoveryState): Promise<void> {
     s.buildEnvDispose = null;
   }
   s.resolvedBuildEnv = undefined;
+  delete (globalThis as Record<string, unknown>)[BUILD_ENV_GLOBAL_KEY];
 }
 
 /**
@@ -344,23 +407,35 @@ export function createRouterDiscoveryPlugin(
       }
 
       const discover = async () => {
+        const discoverStart = performance.now();
         const rscEnv = (server.environments as any)?.rsc;
         if (!rscEnv?.runner) {
           // Cloudflare dev: no module runner available (workerd-based RSC env).
           // Set devServerOrigin so the virtual module can inject __PRERENDER_DEV_URL
           // for on-demand prerender via the /__rsc_prerender endpoint.
+          debugDiscovery?.("dev: no rsc runner (cloudflare path)");
           s.devServerOrigin = getDevServerOrigin();
 
           // Create a temp Node.js server to run runtime discovery and generate
           // named route types (static parser can't resolve factory calls).
           try {
             // Acquire build-time env bindings for dev prerender
-            await acquireBuildEnv(s, viteCommand, viteMode);
+            await timed(debugDiscovery, "acquireBuildEnv", () =>
+              acquireBuildEnv(s, viteCommand, viteMode),
+            );
 
-            const tempRscEnv = await getOrCreateTempServer();
+            const tempRscEnv = await timed(
+              debugDiscovery,
+              "getOrCreateTempServer",
+              () => getOrCreateTempServer(),
+            );
             if (tempRscEnv) {
-              await discoverRouters(s, tempRscEnv);
-              writeRouteTypesFiles(s);
+              await timed(debugDiscovery, "discoverRouters (cloudflare)", () =>
+                discoverRouters(s, tempRscEnv),
+              );
+              timed(debugDiscovery, "writeRouteTypesFiles", () =>
+                writeRouteTypesFiles(s),
+              );
             }
           } catch (err: any) {
             console.warn(
@@ -368,24 +443,35 @@ export function createRouterDiscoveryPlugin(
             );
           }
 
+          debugDiscovery?.(
+            "dev discovery done (%sms)",
+            (performance.now() - discoverStart).toFixed(1),
+          );
           resolveDiscovery!();
           return;
         }
 
         try {
           // Acquire build-time env bindings for dev prerender (Node.js path)
-          await acquireBuildEnv(s, viteCommand, viteMode);
+          debugDiscovery?.("dev: node path start");
+          await timed(debugDiscovery, "acquireBuildEnv", () =>
+            acquireBuildEnv(s, viteCommand, viteMode),
+          );
 
           // Set the readiness gate BEFORE discovery so early requests
           // block until manifest is populated
-          const serverMod = await rscEnv.runner.import(
-            "@rangojs/router/server",
+          const serverMod = await timed(
+            debugDiscovery,
+            "import @rangojs/router/server",
+            () => rscEnv.runner.import("@rangojs/router/server"),
           );
           if (serverMod?.setManifestReadyPromise) {
             serverMod.setManifestReadyPromise(discoveryPromise);
           }
 
-          await discoverRouters(s, rscEnv);
+          await timed(debugDiscovery, "discoverRouters", () =>
+            discoverRouters(s, rscEnv),
+          );
 
           // Store server origin for dev prerender endpoint (virtual module injection)
           s.devServerOrigin = getDevServerOrigin();
@@ -395,15 +481,23 @@ export function createRouterDiscoveryPlugin(
           // routes (e.g. Array.from loops) that the static parser cannot see.
           // writeRouteTypesFiles() only writes when content changes, so this
           // won't cause unnecessary HMR triggers.
-          writeRouteTypesFiles(s);
+          timed(debugDiscovery, "writeRouteTypesFiles", () =>
+            writeRouteTypesFiles(s),
+          );
 
           // Populate the route map and per-router data in the RSC env
-          await propagateDiscoveryState(rscEnv);
+          await timed(debugDiscovery, "propagateDiscoveryState", () =>
+            propagateDiscoveryState(rscEnv),
+          );
         } catch (err: any) {
           console.warn(
             `[rsc-router] Router discovery failed: ${err.message}\n${err.stack}`,
           );
         } finally {
+          debugDiscovery?.(
+            "dev discovery done (%sms)",
+            (performance.now() - discoverStart).toFixed(1),
+          );
           resolveDiscovery!();
         }
       };
@@ -480,9 +574,31 @@ export function createRouterDiscoveryPlugin(
           return;
         }
 
-        // Prefer the main server's registry (Node.js preset: module runner available).
-        // Fall back to a temp server for Cloudflare where the main RSC env uses workerd.
-        let registry = mainRegistry;
+        // Import the user's entry module to force re-evaluation of any
+        // HMR-invalidated modules in the chain (entry → router → urls → handlers).
+        // This ensures createRouter() re-runs with updated handler code before
+        // we read RouterRegistry. Without this, edits to prerender handler files
+        // produce stale content because the old router instance remains registered.
+        const rscEnv = (server.environments as any)?.rsc;
+        let registry: Map<string, any> | null = null;
+        if (rscEnv?.runner && s.resolvedEntryPath) {
+          try {
+            await rscEnv.runner.import(s.resolvedEntryPath);
+            const serverMod = await rscEnv.runner.import(
+              "@rangojs/router/server",
+            );
+            registry = serverMod.RouterRegistry ?? null;
+          } catch (err: any) {
+            console.warn(
+              `[rsc-router] Dev prerender module refresh failed: ${err.message}`,
+            );
+            res.statusCode = 500;
+            res.end(`Prerender handler error: ${err.message}`);
+            return;
+          }
+        } else {
+          registry = mainRegistry;
+        }
 
         if (!registry) {
           // No main registry: the RSC env has no module runner (Cloudflare dev).
@@ -591,15 +707,26 @@ export function createRouterDiscoveryPlugin(
           const rscEnv = (server.environments as any)?.rsc;
           if (!rscEnv?.runner || runtimeRediscoveryInProgress) return;
           runtimeRediscoveryInProgress = true;
+          const hmrStart = performance.now();
           try {
-            await discoverRouters(s, rscEnv);
-            writeRouteTypesFiles(s);
-            await propagateDiscoveryState(rscEnv);
+            await timed(debugDiscovery, "hmr discoverRouters", () =>
+              discoverRouters(s, rscEnv),
+            );
+            timed(debugDiscovery, "hmr writeRouteTypesFiles", () =>
+              writeRouteTypesFiles(s),
+            );
+            await timed(debugDiscovery, "hmr propagateDiscoveryState", () =>
+              propagateDiscoveryState(rscEnv),
+            );
           } catch (err: any) {
             console.warn(
               `[rsc-router] Runtime re-discovery failed: ${err.message}`,
             );
           } finally {
+            debugDiscovery?.(
+              "hmr re-discovery done (%sms)",
+              (performance.now() - hmrStart).toFixed(1),
+            );
             runtimeRediscoveryInProgress = false;
           }
         };
@@ -697,12 +824,16 @@ export function createRouterDiscoveryPlugin(
       if (!s.isBuildMode) return;
       // Only run once across environment builds
       if (s.mergedRouteManifest !== null) return;
+      const buildStartTime = performance.now();
+      debugDiscovery?.("build: start");
       resetStagedBuildAssets(s.projectRoot);
       s.prerenderManifestEntries = null;
       s.staticManifestEntries = null;
 
       // Acquire build-time env bindings if configured
-      await acquireBuildEnv(s, viteCommand, viteMode);
+      await timed(debugDiscovery, "build acquireBuildEnv", () =>
+        acquireBuildEnv(s, viteCommand, viteMode),
+      );
 
       let tempServer: any = null;
       // Signal to user-space code (e.g. reverse.ts) that build-time discovery
@@ -711,7 +842,11 @@ export function createRouterDiscoveryPlugin(
       // between the vite plugin and user code loaded via runner.import().
       (globalThis as any).__rscRouterDiscoveryActive = true;
       try {
-        tempServer = await createTempRscServer(s, { forceBuild: true });
+        tempServer = await timed(
+          debugDiscovery,
+          "build createTempRscServer",
+          () => createTempRscServer(s, { forceBuild: true }),
+        );
 
         const rscEnv = (tempServer.environments as any)?.rsc;
         if (!rscEnv?.runner) {
@@ -731,11 +866,15 @@ export function createRouterDiscoveryPlugin(
           s.resolvedStaticModules = tempIdsPlugin.api.staticHandlerModules;
         }
 
-        await discoverRouters(s, rscEnv);
+        await timed(debugDiscovery, "build discoverRouters", () =>
+          discoverRouters(s, rscEnv),
+        );
         // Update named-routes.gen.ts from runtime discovery.
         // The runtime manifest includes dynamically generated routes
         // that the static parser cannot extract from source code.
-        writeRouteTypesFiles(s);
+        timed(debugDiscovery, "build writeRouteTypesFiles", () =>
+          writeRouteTypesFiles(s),
+        );
       } catch (err: any) {
         // Extract the user source file from the stack trace (skip internal frames)
         const sourceFile = err.stack
@@ -760,9 +899,15 @@ export function createRouterDiscoveryPlugin(
       } finally {
         delete (globalThis as any).__rscRouterDiscoveryActive;
         if (tempServer) {
-          await tempServer.close();
+          await timed(debugDiscovery, "build tempServer.close", () =>
+            tempServer.close(),
+          );
         }
         await releaseBuildEnv(s);
+        debugDiscovery?.(
+          "build discovery done (%sms)",
+          (performance.now() - buildStartTime).toFixed(1),
+        );
       }
     },
 
@@ -786,19 +931,34 @@ export function createRouterDiscoveryPlugin(
         // This is critical for Cloudflare dev where the worker runs in a separate
         // Miniflare process and can only receive manifest data via the virtual module.
         if (s.discoveryDone) {
-          await s.discoveryDone;
+          await timed(debugRoutes, "await discoveryDone (manifest)", () =>
+            Promise.resolve(s.discoveryDone),
+          );
         }
-        return generateRoutesManifestModule(s);
+        const code = await timed(
+          debugRoutes,
+          "generateRoutesManifestModule",
+          () => generateRoutesManifestModule(s),
+        );
+        debugRoutes?.("manifest module emitted (%d bytes)", code?.length ?? 0);
+        return code;
       }
       // Per-router virtual modules: pure data exports (no side effects).
       // ensureRouterManifest() imports the module and stores the data.
       const perRouterPrefix = "\0" + VIRTUAL_ROUTES_MANIFEST_ID + "/";
       if (id.startsWith(perRouterPrefix)) {
         if (s.discoveryDone) {
-          await s.discoveryDone;
+          await timed(debugRoutes, "await discoveryDone (per-router)", () =>
+            Promise.resolve(s.discoveryDone),
+          );
         }
         const routerId = id.slice(perRouterPrefix.length);
-        return generatePerRouterModule(s, routerId);
+        const code = await timed(
+          debugRoutes,
+          `generatePerRouterModule ${routerId}`,
+          () => generatePerRouterModule(s, routerId),
+        );
+        return code;
       }
       // virtual:rsc-router/prerender-paths load handler removed
       return null;

package/src/vite/utils/banner.ts

@@ -1,4 +1,4 @@
-import packageJson from "../../../package.json" with { type: "json" };
+import packageJson from "../../../package.json";
 
 export const rangoVersion: string = packageJson.version;
 

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

@@ -6,8 +6,11 @@
  */
 
 import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
 import { resolve } from "node:path";
-import packageJson from "../../../package.json" with { type: "json" };
+import packageJson from "../../../package.json";
+
+const require = createRequire(import.meta.url);
 
 /**
  * The canonical name used in virtual entries (without scope)
@@ -119,3 +122,40 @@ export function getPackageAliases(): Record<string, string> {
 
   return aliases;
 }
+
+/**
+ * Plugin-rsc pushes bare specs like
+ * `@vitejs/plugin-rsc/vendor/react-server-dom/client.edge` into
+ * `optimizeDeps.include` for the ssr and rsc environments. In strict pnpm
+ * consumer apps, `@vitejs/plugin-rsc` is only reachable from @rangojs/router's
+ * node_modules, so Vite's optimizer — which resolves from the project root —
+ * can't find them and emits "Failed to resolve dependency" warnings.
+ *
+ * We resolve those specs from this plugin's location (where plugin-rsc is
+ * guaranteed to be installed as our dep) and expose them as `resolve.alias`
+ * entries. The optimizer's resolver honors aliases, so the bare specs map to
+ * absolute paths and resolve cleanly.
+ */
+export function getVendorAliases(): Record<string, string> {
+  // client.browser is intentionally NOT aliased. plugin-rsc injects it into
+  // the client env's optimizeDeps.include; Vite's manual-include path resolves
+  // and pre-bundles regardless of optimizeDeps.exclude, so aliasing would
+  // trigger esbuild pre-bundling of the CJS vendor file and bypass the
+  // cjs-to-esm transform that patches `require('react'|'react-dom')` into
+  // real ESM imports. The consumer may still see a single "Failed to resolve"
+  // warning for client.browser; runtime resolution from plugin-rsc's own
+  // importer works because Vite resolves relative to the importer (not root).
+  const specs = [
+    "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge",
+    "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge",
+  ];
+  const aliases: Record<string, string> = {};
+  for (const spec of specs) {
+    try {
+      aliases[spec] = require.resolve(spec);
+    } catch {
+      // Spec unresolvable (unexpected but non-fatal — Vite will warn as before).
+    }
+  }
+  return aliases;
+}

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

@@ -41,14 +41,28 @@ export function substituteRouteParams(
   let result = pattern;
   let hadOmittedOptional = false;
 
-  // First pass: substitute provided params
+  // First pass: substitute provided params.
+  // Empty string on an optional placeholder is treated as omitted (the trie
+  // matcher fills unmatched optionals with "" — letting the second pass
+  // strip them keeps slash cleanup consistent). Empty string on required
+  // `:key` or wildcard `*key` still substitutes, matching prior behaviour.
   for (const [key, value] of Object.entries(params)) {
     const escaped = escapeRegExp(key);
-    result = result.replace(
-      new RegExp(`:${escaped}(\\([^)]*\\))?\\??`),
-      encode(value),
-    );
-    result = result.replace(`*${key}`, encode(value));
+    if (value === "") {
+      // Only replace required placeholders (negative lookahead for `?`);
+      // leave `:key?` for the second pass.
+      result = result.replace(
+        new RegExp(`:${escaped}(\\([^)]*\\))?(?!\\?)`),
+        "",
+      );
+      result = result.replace(`*${key}`, "");
+    } else {
+      result = result.replace(
+        new RegExp(`:${escaped}(\\([^)]*\\))?\\??`),
+        encode(value),
+      );
+      result = result.replace(`*${key}`, encode(value));
+    }
   }
 
   // Second pass: strip remaining optional param placeholders not in params