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

package/src/vite/plugins/expose-internal-ids.ts

@@ -2,7 +2,12 @@ import type { Plugin, ResolvedConfig } from "vite";
 import { parseAst } from "vite";
 import MagicString from "magic-string";
 import path from "node:path";
-import { normalizePath, hashId, detectImports } from "./expose-id-utils.js";
+import {
+  normalizePath,
+  hashId,
+  makeStubId,
+  detectImports,
+} from "./expose-id-utils.js";
 import {
   transformInlineHandlers,
   type VirtualHandlerEntry,
@@ -23,6 +28,7 @@ import {
   getImportedFnNames,
   collectCreateExportBindings,
   buildUnsupportedShapeWarning,
+  isExportOnlyFile,
 } from "./expose-ids/export-analysis.js";
 import {
   hasCreateLoaderImport,
@@ -34,6 +40,7 @@ import {
   transformLocationState,
   generateWholeFileStubs,
   generateExprStubs,
+  stubHandlerExprs,
   transformHandlerIds,
 } from "./expose-ids/handler-transform.js";
 
@@ -385,7 +392,9 @@ ${lazyImports.join(",\n")}
         if (stubResult) return stubResult;
       }
 
-      // --- PrerenderHandler: non-RSC stub replacement ---
+      // --- PrerenderHandler: non-RSC whole-file stub replacement ---
+      // When ALL exports are Prerender() calls, replace the entire file.
+      // Mixed-export files are handled in the unified pipeline below.
       if (hasPrerenderHandlerCode && !isRscEnv) {
         const fnNames = getFnNames(PRERENDER_CONFIG.fnName);
         const bindings = getBindings(code, fnNames);
@@ -397,16 +406,6 @@ ${lazyImports.join(",\n")}
           isBuild,
         );
         if (wholeFile) return wholeFile;
-
-        const exprStubs = generateExprStubs(
-          PRERENDER_CONFIG,
-          bindings,
-          code,
-          filePath,
-          id,
-          isBuild,
-        );
-        if (exprStubs) return exprStubs;
       }
 
       // --- PrerenderHandler: RSC build module tracking ---
@@ -467,7 +466,8 @@ ${lazyImports.join(",\n")}
         }
       }
 
-      // --- StaticHandler: non-RSC stub replacement ---
+      // --- StaticHandler: non-RSC whole-file stub replacement ---
+      // When ALL exports are Static() calls, replace the entire file.
       if (hasStaticHandlerCode && !isRscEnv) {
         const fnNames = getFnNames(STATIC_CONFIG.fnName);
         const bindings = getBindings(code, fnNames);
@@ -479,16 +479,212 @@ ${lazyImports.join(",\n")}
           isBuild,
         );
         if (wholeFile) return wholeFile;
+      }
 
-        const exprStubs = generateExprStubs(
-          STATIC_CONFIG,
-          bindings,
-          code,
-          filePath,
-          id,
-          isBuild,
-        );
-        if (exprStubs) return exprStubs;
+      // --- Mixed-type whole-file stub replacement (non-RSC) ---
+      // When the individual whole-file checks above fail (each only checks
+      // one type), the file has mixed exports (e.g. createLoader + Prerender).
+      // Gather ALL stub-safe bindings and check if they cover every export.
+      // If yes, replace the entire file with stubs — this strips server-only
+      // imports (node:fs, DB clients, etc.) that would crash in the browser.
+      //
+      // Only applies when the file contains Prerender/Static (the handler
+      // types that bring server-only code). Files with only loaders, handles,
+      // or locationState are handled correctly by the unified pipeline below.
+      //
+      // Loader, Prerender, and Static exports become plain { __brand, $$id }
+      // stubs. createHandle and createLocationState need their create*()
+      // functions to execute (collect registration / __rsc_ls_key), so their
+      // call expressions are preserved with only a @rangojs/router import.
+      // This strips all server-only imports while keeping the correct
+      // client contract for every export type.
+      if (!isRscEnv && (hasPrerenderHandlerCode || hasStaticHandlerCode)) {
+        const prerenderFnNames = hasPrerenderHandlerCode
+          ? getFnNames(PRERENDER_CONFIG.fnName)
+          : [];
+        const staticFnNames = hasStaticHandlerCode
+          ? getFnNames(STATIC_CONFIG.fnName)
+          : [];
+        const loaderFnNames = hasLoaderCode ? getFnNames("createLoader") : [];
+        const handleFnNames = hasHandleCode ? getFnNames("createHandle") : [];
+        const lsFnNames = hasLocationStateCode
+          ? getFnNames("createLocationState")
+          : [];
+
+        // Collect ALL recognized bindings to check export coverage
+        const allBindings: CreateExportBinding[] = [];
+        for (const fnNames of [
+          prerenderFnNames,
+          staticFnNames,
+          loaderFnNames,
+          handleFnNames,
+          lsFnNames,
+        ]) {
+          if (fnNames.length > 0) {
+            allBindings.push(...getBindings(code, fnNames));
+          }
+        }
+
+        // Check if preserved createHandle/createLocationState calls
+        // reference non-exported locals (e.g. helper functions, constants).
+        // If so, the whole-file stub would strip those locals, breaking
+        // the call. Fall through to the unified pipeline instead.
+        let canStubWholeFile =
+          allBindings.length > 0 && isExportOnlyFile(code, allBindings);
+
+        if (
+          canStubWholeFile &&
+          (handleFnNames.length > 0 || lsFnNames.length > 0)
+        ) {
+          const exportedLocals = new Set(allBindings.map((b) => b.localName));
+          // Collect bindings that would be stripped by whole-file replacement:
+          // local declarations and imported bindings from non-@rangojs/router
+          // modules. This is a regex-based heuristic — it intentionally skips
+          // edge cases (class decls, destructured bindings, combined
+          // default+named imports) since those rarely appear in route files.
+          const strippedBindings: string[] = [];
+
+          // Skip React Fast Refresh temporaries (_c, _c2, ...) which are
+          // injected by @vitejs/plugin-react in the client environment and
+          // would falsely trigger the bailout.
+          const localDeclPattern =
+            /(?:^|;|\n)\s*(?:const|let|var|function)\s+(\w+)/g;
+          let declMatch: RegExpExecArray | null;
+          while ((declMatch = localDeclPattern.exec(code)) !== null) {
+            const name = declMatch[1];
+            if (!exportedLocals.has(name) && !/^_c\d*$/.test(name)) {
+              strippedBindings.push(name);
+            }
+          }
+
+          const importPattern =
+            /import\s*\{([^}]*)\}\s*from\s*["'](?!@rangojs\/router)[^"']*["']/g;
+          let importMatch: RegExpExecArray | null;
+          while ((importMatch = importPattern.exec(code)) !== null) {
+            for (const spec of importMatch[1].split(",")) {
+              const m = spec
+                .trim()
+                .match(/^[A-Za-z_$][\w$]*(?:\s+as\s+([A-Za-z_$][\w$]*))?$/);
+              if (m) strippedBindings.push(m[1] || m[0].trim().split(/\s/)[0]);
+            }
+          }
+          const defaultImportPattern =
+            /import\s+([A-Za-z_$][\w$]*)\s+from\s*["'](?!@rangojs\/router)[^"']*["']/g;
+          while ((importMatch = defaultImportPattern.exec(code)) !== null) {
+            strippedBindings.push(importMatch[1]);
+          }
+          const nsImportPattern =
+            /import\s+\*\s+as\s+([A-Za-z_$][\w$]*)\s+from\s*["'](?!@rangojs\/router)[^"']*["']/g;
+          while ((importMatch = nsImportPattern.exec(code)) !== null) {
+            strippedBindings.push(importMatch[1]);
+          }
+
+          if (strippedBindings.length > 0) {
+            const preservedBindings = allBindings.filter((b) => {
+              const fc = code.slice(b.callExprStart, b.callOpenParenPos + 1);
+              return (
+                handleFnNames.some((n) => fc.includes(n)) ||
+                lsFnNames.some((n) => fc.includes(n))
+              );
+            });
+            const strippedRe = new RegExp(
+              `\\b(?:${strippedBindings.join("|")})\\b`,
+            );
+            canStubWholeFile = !preservedBindings.some((b) => {
+              const expr = code.slice(b.callExprStart, b.callCloseParenPos + 1);
+              return strippedRe.test(expr);
+            });
+          }
+        }
+
+        if (canStubWholeFile) {
+          const lines: string[] = [];
+          const neededImports: string[] = [];
+          if (handleFnNames.length > 0) neededImports.push("createHandle");
+          if (lsFnNames.length > 0) neededImports.push("createLocationState");
+          if (neededImports.length > 0) {
+            lines.push(
+              `import { ${neededImports.join(", ")} } from "@rangojs/router";`,
+            );
+          }
+
+          for (const binding of allBindings) {
+            const fnCall = code.slice(
+              binding.callExprStart,
+              binding.callOpenParenPos + 1,
+            );
+            const isHandle = handleFnNames.some((n) => fnCall.includes(n));
+            const isLocationState = lsFnNames.some((n) => fnCall.includes(n));
+
+            // Aliases share the primary name's ID (matches server transforms).
+            const primaryName = binding.exportNames[0];
+            const stubId = makeStubId(filePath, primaryName, isBuild);
+
+            if (isHandle || isLocationState) {
+              // Rewrite alias to canonical name since the stub file only
+              // imports canonical names from @rangojs/router.
+              // Strip React Fast Refresh `_c = ` wrappers from args
+              // (e.g. `_c = (segments) => ...` → `(segments) => ...`)
+              const rawArgs = code
+                .slice(binding.callOpenParenPos + 1, binding.callCloseParenPos)
+                .replace(/\b_c\d*\s*=\s*/g, "");
+              const canonicalName = isHandle
+                ? "createHandle"
+                : "createLocationState";
+              const activeFnNames = isHandle ? handleFnNames : lsFnNames;
+
+              // Reconstruct the function name (handling aliases + generics)
+              let rawCallee = code.slice(
+                binding.callExprStart,
+                binding.callOpenParenPos,
+              );
+              for (const alias of activeFnNames) {
+                if (alias !== canonicalName && rawCallee.startsWith(alias)) {
+                  rawCallee = canonicalName + rawCallee.slice(alias.length);
+                  break;
+                }
+              }
+
+              if (isHandle) {
+                // createHandle checks __injectedId DURING the call, so $$id
+                // must be a parameter, not a post-call property assignment.
+                const idParam =
+                  binding.argCount === 0
+                    ? `undefined, "${stubId}"`
+                    : `, "${stubId}"`;
+                lines.push(
+                  `export const ${primaryName} = ${rawCallee}(${rawArgs}${idParam});`,
+                );
+                lines.push(`${primaryName}.$$id = "${stubId}";`);
+              } else {
+                lines.push(
+                  `export const ${primaryName} = ${rawCallee}(${rawArgs});`,
+                );
+                lines.push(
+                  `${primaryName}.__rsc_ls_key = "__rsc_ls_${stubId}";`,
+                );
+              }
+              for (const name of binding.exportNames.slice(1)) {
+                lines.push(`export const ${name} = ${primaryName};`);
+              }
+            } else {
+              let brand = "loader";
+              if (prerenderFnNames.some((n) => fnCall.includes(n))) {
+                brand = PRERENDER_CONFIG.brand;
+              } else if (staticFnNames.some((n) => fnCall.includes(n))) {
+                brand = STATIC_CONFIG.brand;
+              }
+              lines.push(
+                `export const ${primaryName} = { __brand: "${brand}", $$id: "${stubId}" };`,
+              );
+              for (const name of binding.exportNames.slice(1)) {
+                lines.push(`export const ${name} = ${primaryName};`);
+              }
+            }
+          }
+
+          return { code: lines.join("\n") + "\n", map: null };
+        }
       }
 
       // --- StaticHandler: RSC build module tracking ---
@@ -535,27 +731,48 @@ ${lazyImports.join(",\n")}
             isBuild,
           ) || changed;
       }
-      if (hasPrerenderHandlerCode && isRscEnv) {
+      if (hasPrerenderHandlerCode) {
         const fnNames = getFnNames(PRERENDER_CONFIG.fnName);
-        changed =
-          transformHandlerIds(
-            PRERENDER_CONFIG,
-            getBindings(code, fnNames),
-            s,
-            filePath,
-            isBuild,
-          ) || changed;
+        const bindings = getBindings(code, fnNames);
+        if (isRscEnv) {
+          changed =
+            transformHandlerIds(
+              PRERENDER_CONFIG,
+              bindings,
+              s,
+              filePath,
+              isBuild,
+            ) || changed;
+        } else {
+          // Non-RSC mixed-export file: replace Prerender() calls with stubs
+          // on the shared MagicString so sourcemaps stay accurate.
+          changed =
+            stubHandlerExprs(
+              PRERENDER_CONFIG,
+              bindings,
+              s,
+              filePath,
+              isBuild,
+            ) || changed;
+        }
       }
-      if (hasStaticHandlerCode && isRscEnv) {
+      if (hasStaticHandlerCode) {
         const fnNames = getFnNames(STATIC_CONFIG.fnName);
-        changed =
-          transformHandlerIds(
-            STATIC_CONFIG,
-            getBindings(code, fnNames),
-            s,
-            filePath,
-            isBuild,
-          ) || changed;
+        const bindings = getBindings(code, fnNames);
+        if (isRscEnv) {
+          changed =
+            transformHandlerIds(
+              STATIC_CONFIG,
+              bindings,
+              s,
+              filePath,
+              isBuild,
+            ) || changed;
+        } else {
+          changed =
+            stubHandlerExprs(STATIC_CONFIG, bindings, s, filePath, isBuild) ||
+            changed;
+        }
       }
 
       if (!changed) return;

package/src/vite/plugins/performance-tracks.ts

@@ -14,6 +14,9 @@
 
 import type { Plugin } from "vite";
 import { readFile } from "node:fs/promises";
+import { createRangoDebugger } from "../debug.js";
+
+const debug = createRangoDebugger("rango:transform");
 
 const RSDW_PATCH_RE =
   /((?:var|let|const)\s+\w+\s*=\s*root\._children\s*,\s*(\w+)\s*=\s*root\._debugInfo\s*[;,])/;
@@ -76,12 +79,7 @@ export function performanceTracksPlugin(): Plugin {
       if (!id.includes("react-server-dom") || !id.includes("client")) return;
       const patched = patchRsdwClientDebugInfoRecovery(code);
       if (!patched.debugInfoVar) return;
-      if (process.env.INTERNAL_RANGO_DEBUG)
-        console.log(
-          "[perf-tracks] patched RSDW client (var:",
-          patched.debugInfoVar,
-          ")",
-        );
+      debug?.("patched RSDW client (var: %s)", patched.debugInfoVar);
       return patched.code;
     },
   };

package/src/vite/rango.ts

@@ -12,6 +12,8 @@ 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";
@@ -27,6 +29,9 @@ 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 } from "./debug.js";
+
+const debugConfig = createRangoDebugger("rango:config");
 
 /**
  * Vite plugin for @rangojs/router.
@@ -53,25 +58,41 @@ 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;
+  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.
@@ -126,7 +147,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
               // 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,
               },
@@ -151,8 +172,10 @@ 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,
@@ -167,7 +190,9 @@ 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",
+                  ),
                 ],
                 exclude: excludeDeps,
                 esbuildOptions: sharedEsbuildOptions,
@@ -280,7 +305,7 @@ 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,
@@ -297,7 +322,9 @@ 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,
@@ -310,7 +337,9 @@ 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,
               },
@@ -458,5 +487,11 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
     }),
   );
 
+  debugConfig?.(
+    "rango(%s) setup done: %d plugin(s) (%sms)",
+    preset,
+    plugins.length,
+    (performance.now() - rangoStart).toFixed(1),
+  );
   return plugins;
 }