@rangojs/router 0.0.0-experimental.19 → 0.0.0-experimental.1db96a9e

package/src/vite/index.ts

@@ -1,15 +1,20 @@
 /**
  * Public API for @rangojs/router/vite
  *
- * Only the rango() plugin factory and its option types are part of the
- * public API. All other utilities are internal implementation details
- * consumed via direct imports within the package.
+ * Exports: rango() plugin factory, poke() dev utility plugin,
+ * and related option types. All other utilities are internal implementation
+ * details consumed via direct imports within the package.
  */
 
 export { rango } from "./rango.js";
+export { poke } from "./plugins/refresh-cmd.js";
 
 export type {
   RangoNodeOptions,
   RangoCloudflareOptions,
   RangoOptions,
+  BuildEnvOption,
+  BuildEnvFactory,
+  BuildEnvFactoryContext,
+  BuildEnvResult,
 } from "./plugin-types.js";

package/src/vite/plugin-types.ts

@@ -1,38 +1,53 @@
+// -- Build-time environment types -------------------------------------------
+
 /**
- * RSC plugin entry points configuration.
- * All entries use virtual modules by default. Specify a path to use a custom entry file.
+ * Context passed to a buildEnv factory function.
+ * Provides Vite config details for conditional env setup.
  */
-export interface RscEntries {
-  /**
-   * Path to a custom browser/client entry file.
-   * If not specified, a default virtual entry is used.
-   */
-  client?: string;
+export interface BuildEnvFactoryContext {
+  /** Vite project root directory. */
+  root: string;
+  /** Vite mode (e.g. "development", "production"). */
+  mode: string;
+  /** Vite command ("serve" for dev, "build" for production). */
+  command: "serve" | "build";
+  /** Router deployment preset. */
+  preset: "node" | "cloudflare";
+}
 
-  /**
-   * Path to a custom SSR entry file.
-   * If not specified, a default virtual entry is used.
-   */
-  ssr?: string;
+/**
+ * Factory function that creates build-time environment bindings.
+ * Called once at plugin startup. Return `dispose` to clean up resources.
+ */
+export type BuildEnvFactory = (
+  ctx: BuildEnvFactoryContext,
+) => Promise<BuildEnvResult> | BuildEnvResult;
 
-  /**
-   * Path to a custom RSC entry file.
-   * If not specified, a default virtual entry is used that imports the router from the `entry` option.
-   */
-  rsc?: string;
+/**
+ * Result of resolving build-time environment bindings.
+ */
+export interface BuildEnvResult {
+  /** Environment bindings available to Prerender/Static handlers via ctx.env. */
+  env: Record<string, unknown>;
+  /** Called after build completes to clean up resources (e.g., miniflare). */
+  dispose?: () => Promise<void> | void;
 }
 
 /**
- * Options for @vitejs/plugin-rsc integration
+ * Build-time environment configuration for Prerender and Static handlers.
+ *
+ * - `false` (default): no build-time env, `ctx.env` throws.
+ * - `"auto"`: calls `wrangler.getPlatformProxy()` (cloudflare preset only).
+ * - Object: used directly as `ctx.env` during build.
+ * - Factory: called once at startup, must return `{ env, dispose? }`.
  */
-export interface RscPluginOptions {
-  /**
-   * Entry points for client, ssr, and rsc environments.
-   * All entries use virtual modules by default.
-   * Specify paths only when you need custom entry files.
-   */
-  entries?: RscEntries;
-}
+export type BuildEnvOption =
+  | false
+  | "auto"
+  | Record<string, unknown>
+  | BuildEnvFactory;
+
+// -- Plugin options ---------------------------------------------------------
 
 /**
  * Base options shared by all presets
@@ -45,27 +60,16 @@ interface RangoBaseOptions {
   banner?: boolean;
 
   /**
-   * Generate named-routes.gen.ts by parsing url modules at startup.
-   * Provides type-safe Handler<"name"> and href() without executing router code.
-   * Set to `false` to disable (run `npx rango extract-names` manually instead).
-   * @default true
-   */
-  staticRouteTypesGeneration?: boolean;
-
-  /**
-   * Glob patterns for files to include in route type scanning.
-   * Only files matching at least one pattern will be scanned.
-   * Patterns are relative to the project root.
-   * When unset, all .ts/.tsx files are scanned.
-   */
-  include?: string[];
-
-  /**
-   * Glob patterns for files to exclude from route type scanning.
-   * Takes precedence over `include`. Patterns are relative to the project root.
-   * Defaults to common test/build directories.
+   * Environment bindings available to Prerender and Static handlers at build
+   * time via `ctx.env`. Applies to both production build and dev on-demand
+   * prerender (`/__rsc_prerender`).
+   *
+   * This is the build-time env supplied by the Vite plugin, not the live
+   * request env. It is shared across all prerender invocations for the build.
+   *
+   * @default false
    */
-  exclude?: string[];
+  buildEnv?: BuildEnvOption;
 }
 
 /**
@@ -76,38 +80,6 @@ export interface RangoNodeOptions extends RangoBaseOptions {
    * Deployment preset. Defaults to 'node' when not specified.
    */
   preset?: "node";
-
-  /**
-   * Path to your router configuration file that exports the route tree.
-   * This file must export a `router` object created with `createRouter()`.
-   *
-   * When omitted, auto-discovers the router by scanning for files containing
-   * `createRouter`. If exactly one is found, it is used automatically.
-   * If multiple are found, an error is thrown with the list of candidates.
-   *
-   * @example
-   * ```ts
-   * rango({ router: './src/router.tsx' })
-   * // or simply:
-   * rango()
-   * ```
-   */
-  router?: string;
-
-  /**
-   * RSC plugin configuration. By default, rsc-router includes @vitejs/plugin-rsc
-   * with sensible defaults.
-   *
-   * Entry files (browser, ssr, rsc) are optional - if they don't exist,
-   * virtual defaults are used.
-   *
-   * - Omit or pass `true`/`{}` to use defaults (recommended)
-   * - Pass `{ entries: {...} }` to customize entry paths
-   * - Pass `false` to disable (for manual @vitejs/plugin-rsc configuration)
-   *
-   * @default true
-   */
-  rsc?: boolean | RscPluginOptions;
 }
 
 /**

package/src/vite/plugins/client-ref-dedup.ts

@@ -0,0 +1,115 @@
+import type { Plugin, ResolvedConfig } from "vite";
+
+const CLIENT_IN_SERVER_PROXY_PREFIX =
+  "virtual:vite-rsc/client-in-server-package-proxy/";
+
+/**
+ * Extract the bare package name from an absolute node_modules path.
+ * Handles scoped packages (@org/name) and nested node_modules.
+ * Returns null if the path doesn't contain a valid package reference.
+ *
+ * NOTE: This is a lossy transformation. It maps a specific submodule path
+ * (e.g., pkg/internal/context.js) to the package root (pkg). The load()
+ * hook then re-exports via the bare specifier, which resolves to the
+ * package entry point. This works for packages that barrel-export their
+ * "use client" symbols from the root, which covers the common case
+ * (component libraries like @mantine/core, @chakra-ui/react, etc.).
+ * Packages whose client symbols are only available from deep subpaths
+ * (not re-exported from the root) would lose those symbols after the
+ * rewrite. A more precise approach would resolve through the package's
+ * exports map to find the correct entry point, but that adds significant
+ * complexity for a rare edge case.
+ * See: https://github.com/cloudflare/vinext/pull/413
+ */
+export function extractPackageName(absolutePath: string): string | null {
+  // Find the last /node_modules/ segment (handles nested node_modules)
+  const marker = "/node_modules/";
+  const idx = absolutePath.lastIndexOf(marker);
+  if (idx === -1) return null;
+
+  const afterModules = absolutePath.slice(idx + marker.length);
+
+  if (afterModules.startsWith("@")) {
+    // Scoped package: @org/name
+    const parts = afterModules.split("/");
+    if (parts.length < 2 || !parts[1]) return null;
+    return `${parts[0]}/${parts[1]}`;
+  }
+
+  // Unscoped package: name
+  const name = afterModules.split("/")[0];
+  return name || null;
+}
+
+/**
+ * Vite plugin that deduplicates client references from third-party packages
+ * in dev mode.
+ *
+ * When @vitejs/plugin-rsc encounters a "use client" submodule inside a
+ * package imported from a server component, it creates a
+ * client-in-server-package-proxy virtual module that re-exports from the
+ * absolute file path. In the client environment, this absolute path bypasses
+ * Vite's pre-bundling, while direct client imports of the same package go
+ * through .vite/deps/. Two separate module instances are created, breaking
+ * React contexts (createContext runs twice, provider/consumer mismatch).
+ *
+ * This plugin intercepts absolute node_modules imports from proxy modules
+ * in the client environment and rewrites them to bare specifier imports
+ * that go through pre-bundling, ensuring a single module instance.
+ *
+ * Dev-only: production builds use the SSR manifest which handles module
+ * identity correctly.
+ */
+export function clientRefDedup(): Plugin {
+  let clientExclude: string[] = [];
+
+  return {
+    name: "@rangojs/router:client-ref-dedup",
+    enforce: "pre",
+    apply: "serve",
+
+    configResolved(config: ResolvedConfig) {
+      // Respect user's optimizeDeps.exclude — if a package is explicitly
+      // excluded from pre-bundling, we shouldn't redirect it there.
+      const clientEnv = config.environments?.["client"];
+      clientExclude =
+        clientEnv?.optimizeDeps?.exclude ?? config.optimizeDeps?.exclude ?? [];
+    },
+
+    resolveId(source, importer, options) {
+      // Only intercept in the client environment
+      if (this.environment?.name !== "client") return;
+
+      // Only handle imports from client-in-server-package-proxy virtual modules
+      if (!importer?.includes(CLIENT_IN_SERVER_PROXY_PREFIX)) return;
+
+      // Only handle absolute node_modules paths
+      if (!source.includes("/node_modules/")) return;
+
+      // Must have an importer
+      if (!importer) return;
+
+      const packageName = extractPackageName(source);
+      if (!packageName) return;
+
+      // Don't redirect packages that are excluded from optimization
+      if (clientExclude.includes(packageName)) return;
+
+      // Return a virtual module that re-exports via bare specifier
+      return `\0rango:dedup/${packageName}`;
+    },
+
+    load(id) {
+      if (!id.startsWith("\0rango:dedup/")) return;
+
+      const packageName = id.slice("\0rango:dedup/".length);
+
+      // Re-export via bare specifier so Vite routes through pre-bundling
+      return [
+        `export * from ${JSON.stringify(packageName)};`,
+        `import * as __all__ from ${JSON.stringify(packageName)};`,
+        `export default __all__.default;`,
+      ].join("\n");
+    },
+  };
+}

package/src/vite/plugins/expose-action-id.ts

@@ -278,9 +278,7 @@ export function exposeActionId(): Plugin {
       if (!rscPluginApi) {
         throw new Error(
           "[rsc-router] Could not find @vitejs/plugin-rsc. " +
-            "@rangojs/router requires the Vite RSC plugin.\n" +
-            "The RSC plugin should be included automatically. If you disabled it with\n" +
-            "rango({ rsc: false }), add rsc() before rango() in your config.",
+            "@rangojs/router requires the Vite RSC plugin, which is included automatically by rango().",
         );
       }
 

package/src/vite/plugins/expose-ids/handler-transform.ts

@@ -138,6 +138,36 @@ export function generateExprStubs(
   };
 }
 
+/**
+ * Replace handler call expressions with lightweight stub objects on an
+ * existing MagicString. Unlike generateExprStubs (which creates its own
+ * MagicString and returns the full result), this integrates into the
+ * unified transform pipeline so all transforms share one sourcemap.
+ */
+export function stubHandlerExprs(
+  cfg: HandlerTransformConfig,
+  bindings: CreateExportBinding[],
+  s: MagicString,
+  filePath: string,
+  isBuild: boolean,
+): boolean {
+  let hasChanges = false;
+  for (const binding of bindings) {
+    const exportName = binding.exportNames[0];
+    const handlerId = isBuild
+      ? hashId(filePath, exportName)
+      : `${filePath}#${exportName}`;
+
+    s.overwrite(
+      binding.callExprStart,
+      binding.callCloseParenPos + 1,
+      `{ __brand: "${cfg.brand}", $$id: "${handlerId}" }`,
+    );
+    hasChanges = true;
+  }
+  return hasChanges;
+}
+
 /**
  * Inject $$id into export const handler calls in RSC environments.
  */

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

@@ -23,6 +23,7 @@ import {
   getImportedFnNames,
   collectCreateExportBindings,
   buildUnsupportedShapeWarning,
+  isExportOnlyFile,
 } from "./expose-ids/export-analysis.js";
 import {
   hasCreateLoaderImport,
@@ -34,6 +35,7 @@ import {
   transformLocationState,
   generateWholeFileStubs,
   generateExprStubs,
+  stubHandlerExprs,
   transformHandlerIds,
 } from "./expose-ids/handler-transform.js";
 
@@ -385,7 +387,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 +401,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 +461,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 +474,83 @@ ${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 recognized 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.
+      if (!isRscEnv && (hasPrerenderHandlerCode || hasStaticHandlerCode)) {
+        const allBindings: CreateExportBinding[] = [];
+        if (hasLoaderCode) {
+          allBindings.push(...getBindings(code, getFnNames("createLoader")));
+        }
+        if (hasHandleCode) {
+          allBindings.push(...getBindings(code, getFnNames("createHandle")));
+        }
+        if (hasLocationStateCode) {
+          allBindings.push(
+            ...getBindings(code, getFnNames("createLocationState")),
+          );
+        }
+        if (hasPrerenderHandlerCode) {
+          allBindings.push(
+            ...getBindings(code, getFnNames(PRERENDER_CONFIG.fnName)),
+          );
+        }
+        if (hasStaticHandlerCode) {
+          allBindings.push(
+            ...getBindings(code, getFnNames(STATIC_CONFIG.fnName)),
+          );
+        }
+        if (allBindings.length > 0 && isExportOnlyFile(code, allBindings)) {
+          const stubs: string[] = [];
+          for (const binding of allBindings) {
+            const name = binding.exportNames[0];
+            const stubId = isBuild
+              ? hashId(filePath, name)
+              : `${filePath}#${name}`;
+            // Determine brand from which type this binding belongs to
+            const fnCall = code.slice(
+              binding.callExprStart,
+              binding.callOpenParenPos + 1,
+            );
+            let brand = "loader";
+            if (
+              hasPrerenderHandlerCode &&
+              getFnNames(PRERENDER_CONFIG.fnName).some((n) =>
+                fnCall.includes(n),
+              )
+            ) {
+              brand = PRERENDER_CONFIG.brand;
+            } else if (
+              hasStaticHandlerCode &&
+              getFnNames(STATIC_CONFIG.fnName).some((n) => fnCall.includes(n))
+            ) {
+              brand = STATIC_CONFIG.brand;
+            } else if (
+              hasHandleCode &&
+              getFnNames("createHandle").some((n) => fnCall.includes(n))
+            ) {
+              brand = "handle";
+            } else if (
+              hasLocationStateCode &&
+              getFnNames("createLocationState").some((n) => fnCall.includes(n))
+            ) {
+              brand = "locationState";
+            }
+            stubs.push(
+              `export const ${name} = { __brand: "${brand}", $$id: "${stubId}" };`,
+            );
+          }
+          return { code: stubs.join("\n") + "\n", map: null };
+        }
       }
 
       // --- StaticHandler: RSC build module tracking ---
@@ -535,27 +597,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

@@ -0,0 +1,88 @@
+/**
+ * React Performance Tracks — RSDW client patch
+ *
+ * Patches the RSDW client so _debugInfo recovery works for plain-object
+ * payloads (our RscPayload shape). Without this, the Server Components
+ * track in Chrome DevTools stays empty.
+ *
+ * React's flushComponentPerformance uses splice(0) to empty _debugInfo
+ * after resolution, then recovers it from the resolved value — but only
+ * for arrays, async iterables, React elements, and lazy types. Since our
+ * RscPayload is a plain object, _debugInfo is lost. This patch relaxes
+ * the check so _debugInfo is recovered from any object.
+ */
+
+import type { Plugin } from "vite";
+import { readFile } from "node:fs/promises";
+
+const RSDW_PATCH_RE =
+  /((?:var|let|const)\s+\w+\s*=\s*root\._children\s*,\s*(\w+)\s*=\s*root\._debugInfo\s*[;,])/;
+
+function buildPatchReplacement(match: string, debugInfoVar: string): string {
+  return `${match}
+if (${debugInfoVar} && 0 === ${debugInfoVar}.length && "fulfilled" === root.status) {
+  var _resolved = "function" === typeof resolveLazy ? resolveLazy(root.value) : root.value;
+  if ("object" === typeof _resolved && null !== _resolved && isArrayImpl(_resolved._debugInfo)) {
+    ${debugInfoVar} = _resolved._debugInfo;
+  }
+}`;
+}
+
+export function patchRsdwClientDebugInfoRecovery(code: string): {
+  code: string;
+  debugInfoVar: string | null;
+} {
+  const match = code.match(RSDW_PATCH_RE);
+  if (!match) {
+    return { code, debugInfoVar: null };
+  }
+
+  return {
+    code: code.replace(match[1]!, buildPatchReplacement(match[1]!, match[2]!)),
+    debugInfoVar: match[2]!,
+  };
+}
+
+export function performanceTracksOptimizeDepsPlugin(): {
+  name: string;
+  setup(build: any): void;
+} {
+  return {
+    name: "@rangojs/router:performance-tracks-optimize-deps",
+    setup(build: any): void {
+      build.onLoad(
+        {
+          filter:
+            /react-server-dom-webpack-client\.browser\.(development|production)\.js$/,
+        },
+        async (args: { path: string }) => {
+          const code = await readFile(args.path, "utf8");
+          const patched = patchRsdwClientDebugInfoRecovery(code);
+          return {
+            contents: patched.code,
+            loader: "js",
+          };
+        },
+      );
+    },
+  };
+}
+
+export function performanceTracksPlugin(): Plugin {
+  return {
+    name: "@rangojs/router:performance-tracks",
+
+    transform(code, id) {
+      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,
+          ")",
+        );
+      return patched.code;
+    },
+  };
+}