@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.135c6902

package/src/vite/plugin-types.ts

@@ -0,0 +1,48 @@
+/**
+ * Base options shared by all presets
+ */
+interface RangoBaseOptions {
+  /**
+   * Show startup banner. Set to false to disable.
+   * @default true
+   */
+  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;
+}
+
+/**
+ * Options for Node.js deployment (default)
+ */
+export interface RangoNodeOptions extends RangoBaseOptions {
+  /**
+   * Deployment preset. Defaults to 'node' when not specified.
+   */
+  preset?: "node";
+}
+
+/**
+ * Options for Cloudflare Workers deployment
+ */
+export interface RangoCloudflareOptions extends RangoBaseOptions {
+  /**
+   * Deployment preset for Cloudflare Workers.
+   * When using cloudflare preset:
+   * - @vitejs/plugin-rsc is NOT added (cloudflare plugin adds it)
+   * - Your worker entry (e.g., worker.rsc.tsx) imports the router directly
+   * - Browser and SSR use virtual entries
+   * - Build-time manifest generation is auto-detected from the resolved RSC environment config
+   */
+  preset: "cloudflare";
+}
+
+/**
+ * Options for rango() Vite plugin
+ */
+export type RangoOptions = RangoNodeOptions | RangoCloudflareOptions;

package/src/vite/plugins/cjs-to-esm.ts

@@ -0,0 +1,93 @@
+import type { Plugin } from "vite";
+
+/**
+ * Transform CJS vendor files from @vitejs/plugin-rsc to ESM for browser compatibility.
+ * The react-server-dom vendor files are shipped as CJS which doesn't work in browsers.
+ */
+export function createCjsToEsmPlugin(): Plugin {
+  return {
+    name: "@rangojs/router:cjs-to-esm",
+    enforce: "pre",
+    transform(code, id) {
+      const cleanId = id.split("?")[0];
+
+      // Transform the client.browser.js entry point to re-export from CJS
+      if (
+        cleanId.includes("vendor/react-server-dom/client.browser.js") ||
+        cleanId.includes("vendor\\react-server-dom\\client.browser.js")
+      ) {
+        const isProd = process.env.NODE_ENV === "production";
+        const cjsFile = isProd
+          ? "./cjs/react-server-dom-webpack-client.browser.production.js"
+          : "./cjs/react-server-dom-webpack-client.browser.development.js";
+
+        return {
+          code: `export * from "${cjsFile}";`,
+          map: null,
+        };
+      }
+
+      // Transform the actual CJS files to ESM
+      if (
+        (cleanId.includes("vendor/react-server-dom/cjs/") ||
+          cleanId.includes("vendor\\react-server-dom\\cjs\\")) &&
+        cleanId.includes("client.browser")
+      ) {
+        let transformed = code;
+
+        // Extract the license comment to preserve it
+        const licenseMatch = transformed.match(/^\/\*\*[\s\S]*?\*\//);
+        const license = licenseMatch ? licenseMatch[0] : "";
+        if (license) {
+          transformed = transformed.slice(license.length);
+        }
+
+        // Remove "use strict" (both dev and prod have this)
+        transformed = transformed.replace(/^\s*["']use strict["'];\s*/, "");
+
+        // Remove the conditional IIFE wrapper (development only)
+        transformed = transformed.replace(
+          /^\s*["']production["']\s*!==\s*process\.env\.NODE_ENV\s*&&\s*\(function\s*\(\)\s*\{/,
+          "",
+        );
+
+        // Remove the closing of the conditional IIFE at the end (development only)
+        transformed = transformed.replace(/\}\)\(\);?\s*$/, "");
+
+        // Replace require('react') and require('react-dom') with imports (development)
+        transformed = transformed.replace(
+          /var\s+React\s*=\s*require\s*\(\s*["']react["']\s*\)\s*,[\s\n]+ReactDOM\s*=\s*require\s*\(\s*["']react-dom["']\s*\)\s*,/g,
+          'import React from "react";\nimport ReactDOM from "react-dom";\nvar ',
+        );
+
+        // Replace require('react-dom') only (production - doesn't import React)
+        transformed = transformed.replace(
+          /var\s+ReactDOM\s*=\s*require\s*\(\s*["']react-dom["']\s*\)\s*,/g,
+          'import ReactDOM from "react-dom";\nvar ',
+        );
+
+        // Transform exports.xyz = function() to export function xyz()
+        transformed = transformed.replace(
+          /exports\.(\w+)\s*=\s*function\s*\(/g,
+          "export function $1(",
+        );
+
+        // Transform exports.xyz = value to export const xyz = value
+        transformed = transformed.replace(
+          /exports\.(\w+)\s*=/g,
+          "export const $1 =",
+        );
+
+        // Reconstruct with license at the top
+        transformed = license + "\n" + transformed;
+
+        return {
+          code: transformed,
+          map: null,
+        };
+      }
+
+      return null;
+    },
+  };
+}

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/client-ref-hashing.ts

@@ -0,0 +1,105 @@
+import type { Plugin } from "vite";
+import { relative } from "node:path";
+import { createHash } from "node:crypto";
+
+// Dev-mode client-reference key prefixes emitted by @vitejs/plugin-rsc
+const CLIENT_PKG_PROXY_PREFIX =
+  "/@id/__x00__virtual:vite-rsc/client-package-proxy/";
+const CLIENT_IN_SERVER_PKG_PROXY_PREFIX =
+  "/@id/__x00__virtual:vite-rsc/client-in-server-package-proxy/";
+const FS_PREFIX = "/@fs/";
+
+/**
+ * Compute the production SHA-256 hash for a dev-mode client reference key.
+ * Mirrors the hashing logic in @vitejs/plugin-rsc's build mode:
+ *   - Local files: hashString(toRelativeId(id)) where toRelativeId = relative(root, id)
+ *   - Package proxies: hashString(packageSource)
+ *   - client-in-server-package proxies: hashString(relative(root, decodedAbsPath))
+ *
+ * Returns the input unchanged if it doesn't match a known dev-mode pattern
+ * (e.g., already a production hash).
+ */
+export function computeProductionHash(
+  projectRoot: string,
+  refKey: string,
+): string {
+  let toHash: string;
+
+  if (refKey.startsWith(CLIENT_PKG_PROXY_PREFIX)) {
+    // /@id/__x00__virtual:vite-rsc/client-package-proxy/<pkg> -> hash("<pkg>")
+    toHash = refKey.slice(CLIENT_PKG_PROXY_PREFIX.length);
+  } else if (refKey.startsWith(CLIENT_IN_SERVER_PKG_PROXY_PREFIX)) {
+    // /@id/__x00__virtual:vite-rsc/client-in-server-package-proxy/<encodedAbsPath>
+    const absPath = decodeURIComponent(
+      refKey.slice(CLIENT_IN_SERVER_PKG_PROXY_PREFIX.length),
+    );
+    toHash = relative(projectRoot, absPath).replaceAll("\\", "/");
+  } else if (refKey.startsWith(FS_PREFIX)) {
+    // /@fs/abs/path.tsx -> hash(relative(root, "/abs/path.tsx"))
+    const absPath = refKey.slice(FS_PREFIX.length - 1); // keep leading /
+    toHash = relative(projectRoot, absPath).replaceAll("\\", "/");
+  } else if (refKey.startsWith("/")) {
+    // /src/Button.tsx -> hash("src/Button.tsx")
+    toHash = refKey.slice(1);
+  } else {
+    // Already hashed or unknown format — return unchanged
+    return refKey;
+  }
+
+  return createHash("sha256").update(toHash).digest("hex").slice(0, 12);
+}
+
+// Regex to match registerClientReference() calls as emitted by @vitejs/plugin-rsc.
+// Captures the reference key (second argument) from the call.
+// Handles two proxy forms: parenthesized expression `(expr)` and arrow-throw `() => { ... }`.
+const REGISTER_CLIENT_REF_RE =
+  /registerClientReference\(\s*(?:(?:\([^)]*\))|(?:\(\)[\s\S]*?\}))\s*,\s*"([^"]+)"\s*,\s*"[^"]+"\s*\)/g;
+
+/**
+ * Transform source code by replacing dev-mode client reference keys with
+ * production hashes. Exported for testing; used internally by hashClientRefs.
+ * Returns null if no replacements were made.
+ */
+export function transformClientRefs(
+  code: string,
+  projectRoot: string,
+): string | null {
+  if (!code.includes("registerClientReference")) return null;
+
+  let hasReplacement = false;
+  const result = code.replace(
+    REGISTER_CLIENT_REF_RE,
+    (match, refKey: string) => {
+      const hash = computeProductionHash(projectRoot, refKey);
+      if (hash === refKey) return match;
+      hasReplacement = true;
+      return match.replace(`"${refKey}"`, `"${hash}"`);
+    },
+  );
+
+  return hasReplacement ? result : null;
+}
+
+/**
+ * Vite plugin that rewrites registerClientReference() calls in the RSC
+ * environment, replacing dev-mode reference keys with production hashes.
+ *
+ * This runs AFTER the RSC plugin's transform so the Flight serializer
+ * naturally emits production IDs, eliminating the need for post-build
+ * regex replacement of Flight payloads.
+ */
+export function hashClientRefs(projectRoot: string): Plugin {
+  return {
+    name: "@rangojs/router:hash-client-refs",
+    // Run after the RSC plugin's transform (default enforce is normal)
+    enforce: "post",
+    applyToEnvironment(env) {
+      return env.name === "rsc";
+    },
+    transform(code, _id) {
+      const result = transformClientRefs(code, projectRoot);
+      if (result === null) return;
+      return { code: result, map: null };
+    },
+  };
+}

package/src/vite/{expose-action-id.ts → plugins/expose-action-id.ts}

@@ -2,7 +2,7 @@ import type { Plugin, ResolvedConfig } from "vite";
 import MagicString from "magic-string";
 import path from "node:path";
 import fs from "node:fs";
-import { normalizePath } from "./expose-id-utils.ts";
+import { normalizePath } from "./expose-id-utils.js";
 
 /**
  * Type for the RSC plugin's manager API
@@ -35,12 +35,12 @@ function getRscPluginApi(config: ResolvedConfig): RscPluginApi | undefined {
     plugin = config.plugins.find(
       (p) =>
         (p.api as RscPluginApi | undefined)?.manager?.serverReferenceMetaMap !==
-        undefined
+        undefined,
     );
     if (plugin) {
       console.warn(
         `[rsc-router:expose-action-id] RSC plugin found by API structure (name: "${plugin.name}"). ` +
-          `Consider updating the name lookup if the plugin was renamed.`
+          `Consider updating the name lookup if the plugin was renamed.`,
       );
     }
   }
@@ -82,21 +82,27 @@ function isUseServerModule(filePath: string): boolean {
  * @param sourceId - The source file identifier (for sourcemap)
  * @param hashToFileMap - Optional mapping from hash to file path (for server bundles)
  */
-function transformServerReferences(
+/**
+ * Apply createServerReference wrapping to a MagicString instance.
+ * Returns true if any changes were made.
+ */
+function applyServerReferenceWrapping(
   code: string,
-  sourceId?: string,
-  hashToFileMap?: Map<string, string>
-): { code: string; map: ReturnType<MagicString["generateMap"]> } | null {
+  s: MagicString,
+  hashToFileMap?: Map<string, string>,
+): boolean {
   if (!code.includes("createServerReference(")) {
-    return null;
+    return false;
   }
 
   // Match: createServerReference("hash#actionName", ...) or $$ReactClient.createServerReference(...)
-  // The RSC plugin uses $$ReactClient namespace in transformed code
+  // The RSC plugin uses $$ReactClient namespace in transformed code.
+  // Note: [^)]* cannot handle nested parens in trailing args. This is safe in practice
+  // because the RSC plugin always generates simple variable references (e.g., callServer)
+  // as the second argument, never nested function calls.
   const pattern =
     /((?:\$\$\w+\.)?createServerReference)\(("[^"]+#[^"]+")([^)]*)\)/g;
 
-  const s = new MagicString(code);
   let hasChanges = false;
   let match: RegExpExecArray | null;
 
@@ -127,7 +133,16 @@ function transformServerReferences(
     s.overwrite(start, end, replacement);
   }
 
-  if (!hasChanges) {
+  return hasChanges;
+}
+
+function transformServerReferences(
+  code: string,
+  sourceId?: string,
+  hashToFileMap?: Map<string, string>,
+): { code: string; map: ReturnType<MagicString["generateMap"]> } | null {
+  const s = new MagicString(code);
+  if (!applyServerReferenceWrapping(code, s, hashToFileMap)) {
     return null;
   }
 
@@ -153,20 +168,27 @@ function transformServerReferences(
  * @param sourceId - The source file identifier (for sourcemap)
  * @param hashToFileMap - Mapping from hash to file path (only module-level "use server" files)
  */
-function transformRegisterServerReference(
+/**
+ * Apply registerServerReference wrapping to a MagicString instance.
+ * Returns true if any changes were made.
+ *
+ * Only actions from module-level "use server" files are transformed.
+ * Inline actions keep their hashed IDs for client security.
+ */
+function applyRegisterReferenceWrapping(
   code: string,
-  sourceId?: string,
-  hashToFileMap?: Map<string, string>
-): { code: string; map: ReturnType<MagicString["generateMap"]> } | null {
-  if (!hashToFileMap || !code.includes("registerServerReference(")) {
-    return null;
+  s: MagicString,
+  hashToFileMap: Map<string, string>,
+): boolean {
+  if (!code.includes("registerServerReference(")) {
+    return false;
   }
 
   // Match: registerServerReference(fn, "hash", "exportName")
   // The hash is the second argument, exportName is the third
-  const pattern = /registerServerReference\(([^,]+),\s*"([^"]+)",\s*"([^"]+)"\)/g;
+  const pattern =
+    /registerServerReference\(([^,]+),\s*"([^"]+)",\s*"([^"]+)"\)/g;
 
-  const s = new MagicString(code);
   let hasChanges = false;
   let match: RegExpExecArray | null;
 
@@ -190,7 +212,18 @@ function transformRegisterServerReference(
     }
   }
 
-  if (!hasChanges) {
+  return hasChanges;
+}
+
+function transformRegisterServerReference(
+  code: string,
+  sourceId?: string,
+  hashToFileMap?: Map<string, string>,
+): { code: string; map: ReturnType<MagicString["generateMap"]> } | null {
+  if (!hashToFileMap) return null;
+
+  const s = new MagicString(code);
+  if (!applyRegisterReferenceWrapping(code, s, hashToFileMap)) {
     return null;
   }
 
@@ -245,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().",
         );
       }
 
@@ -257,7 +288,7 @@ export function exposeActionId(): Plugin {
       const { serverReferenceMetaMap } = rscPluginApi.manager;
 
       for (const [absolutePath, meta] of Object.entries(
-        serverReferenceMetaMap
+        serverReferenceMetaMap,
       )) {
         // Only include module-level "use server" files
         // Inline actions (defined in RSC components) should keep hashed IDs for client security
@@ -266,7 +297,7 @@ export function exposeActionId(): Plugin {
         }
 
         const relativePath = normalizePath(
-          path.relative(config.root, absolutePath)
+          path.relative(config.root, absolutePath),
         );
 
         // The referenceKey in build mode is the hash
@@ -275,7 +306,6 @@ export function exposeActionId(): Plugin {
       }
     },
 
-
     // Dev mode only: transform hook runs after RSC plugin creates server references
     // In dev mode, IDs already contain file paths, not hashes
     transform(code, id) {
@@ -308,31 +338,26 @@ export function exposeActionId(): Plugin {
       // Only use file path mapping for RSC environment
       const effectiveMap = isRscEnv ? hashToFileMap : undefined;
 
-      // Transform createServerReference calls (client-side)
-      const result = transformServerReferences(
-        code,
-        chunk.fileName,
-        effectiveMap
-      );
-
-      // For RSC bundles, also transform registerServerReference calls
-      // This replaces hashed IDs with file paths so $id contains the actual path
+      // For RSC bundles, both createServerReference and registerServerReference
+      // may need transforming. Use a single MagicString for correct sourcemaps.
       if (isRscEnv && hashToFileMap) {
-        const codeToTransform = result ? result.code : code;
-        const registerResult = transformRegisterServerReference(
-          codeToTransform,
-          chunk.fileName,
-          hashToFileMap
-        );
-        if (registerResult) {
-          return { code: registerResult.code, map: registerResult.map };
+        const s = new MagicString(code);
+        const changed1 = applyServerReferenceWrapping(code, s, effectiveMap);
+        const changed2 = applyRegisterReferenceWrapping(code, s, hashToFileMap);
+        if (changed1 || changed2) {
+          return {
+            code: s.toString(),
+            map: s.generateMap({
+              source: chunk.fileName,
+              includeContent: true,
+            }),
+          };
         }
+        return null;
       }
 
-      if (result) {
-        return { code: result.code, map: result.map };
-      }
-      return null;
+      // Non-RSC environments: only transform createServerReference calls
+      return transformServerReferences(code, chunk.fileName, effectiveMap);
     },
   };
 }

package/src/vite/{expose-id-utils.ts → plugins/expose-id-utils.ts}

@@ -119,7 +119,10 @@ export function detectImports(code: string): DetectedImports {
     if (/\bcreateRouter\b/.test(imports)) result.router = true;
   }
 
-  // createRouter has a stricter check: only from "@rangojs/router" (not sub-paths)
+  // createRouter has a stricter check: only from "@rangojs/router" (not sub-paths).
+  // NOTE: This is intentional — detectImports is used as a fast pre-filter in
+  // exposeInternalIds (which does NOT handle router transforms). The separate
+  // exposeRouterId plugin handles createRouter and DOES accept the /server subpath.
   if (result.router) {
     result.router =
       /import\s*\{[^}]*\bcreateRouter\b[^}]*\}\s*from\s*["']@rangojs\/router["']/.test(
@@ -276,47 +279,9 @@ export function findStatementEnd(code: string, pos: number): number {
 }
 
 /**
- * Simple depth-counter paren matching. Does NOT skip strings/comments.
- * Used by loader and handle transforms where the simpler approach suffices.
- * Returns the index after the closing paren.
+ * Escape special regex characters in a string so it can be safely
+ * interpolated into a RegExp pattern.
  */
-export function findClosingParen(code: string, startPos: number): number {
-  let depth = 1;
-  let i = startPos;
-  while (i < code.length && depth > 0) {
-    if (code[i] === "(") depth++;
-    if (code[i] === ")") depth--;
-    i++;
-  }
-  return i;
-}
-
-/**
- * Count arguments using simple depth counting (no string/comment awareness).
- * Used by the loader transform where the original code used this simpler approach.
- */
-export function countArgsSimple(
-  code: string,
-  startPos: number,
-  endPos: number,
-): number {
-  let depth = 0;
-  let argCount = 0;
-  let hasContent = false;
-
-  for (let i = startPos; i < endPos; i++) {
-    const char = code[i];
-    if (char === "(" || char === "[" || char === "{") {
-      depth++;
-      hasContent = true;
-    } else if (char === ")" || char === "]" || char === "}") {
-      depth--;
-    } else if (char === "," && depth === 0) {
-      argCount++;
-    } else if (!/\s/.test(char)) {
-      hasContent = true;
-    }
-  }
-
-  return hasContent ? argCount + 1 : 0;
+export function escapeRegExp(input: string): string {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }