@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.204030a9

package/src/vite/plugin-types.ts

@@ -0,0 +1,170 @@
+// -- Build-time environment types -------------------------------------------
+
+/**
+ * Context passed to a buildEnv factory function.
+ * Provides Vite config details for conditional env setup.
+ */
+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";
+}
+
+/**
+ * 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;
+
+/**
+ * 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;
+}
+
+/**
+ * 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 type BuildEnvOption =
+  | false
+  | "auto"
+  | Record<string, unknown>
+  | BuildEnvFactory;
+
+// -- Client chunking --------------------------------------------------------
+
+/**
+ * Metadata for one client ("use client") module, passed to a {@link ClientChunks}
+ * function. Mirrors the shape `@vitejs/plugin-rsc` passes to its own
+ * `clientChunks` option.
+ */
+export interface ClientChunkMeta {
+  /** Absolute module id of the "use client" file. */
+  id: string;
+  /** Normalized (posix) module id — convenient for path-based matching. */
+  normalizedId: string;
+  /**
+   * The RSC/server chunk that statically imports this client reference. This is
+   * the key used for the default grouping when no override is supplied: a single
+   * router that statically imports every route yields ONE `serverChunk`, hence
+   * one client chunk for all routes.
+   */
+  serverChunk: string;
+}
+
+/**
+ * Controls how client ("use client") components are grouped into browser
+ * chunks, i.e. per-route / per-feature code splitting of the client bundle.
+ *
+ * Without splitting, a single router ships ONE client chunk containing every
+ * route's client components (and their CSS) — navigating to one route downloads
+ * every other route's client code. (Host sub-apps loaded via a dynamic `import()`
+ * are the exception: each forms its own chunk.) This option controls how that
+ * monolith is split.
+ *
+ * Behavior branches:
+ * - `true` / omitted (**default**, pre-1.0): Rango's built-in **directory
+ *   strategy**. It splits app `"use client"` modules by **route id** — the segment
+ *   after a route-root directory (`routes`, `app`, `pages`, `features`, `handlers`,
+ *   …) — so `routes/dashboard/**` becomes `app-dashboard` at any nesting depth.
+ *   Where it finds NO route structure (a flat `src/components/`, or host sub-apps
+ *   already split by a dynamic `import()`), it inherits the default grouping
+ *   unchanged — so the shared `src/components` chunk stays shared and host apps do
+ *   not leak across each other. Shared runtime (React, the router, `node_modules`)
+ *   is never split.
+ * - `false`: opt out — inherit `@vitejs/plugin-rsc`'s default grouping everywhere
+ *   (one chunk per router / per host sub-app).
+ * - function: full override. Return a chunk group name, or `undefined` to fall
+ *   back to the default grouping for that one module. Forwarded directly to
+ *   `@vitejs/plugin-rsc`'s `clientChunks`.
+ *
+ * Every module maps to exactly one group, so there is no byte duplication: a
+ * component used by two routes lives in one group and is fetched whenever it
+ * renders. Put genuinely shared client components OUTSIDE route directories so
+ * they land in the shared group rather than one route's chunk.
+ *
+ * @default true
+ */
+export type ClientChunks =
+  | boolean
+  | ((meta: ClientChunkMeta) => string | undefined);
+
+// -- Plugin options ---------------------------------------------------------
+
+/**
+ * Base options shared by all presets
+ */
+interface RangoBaseOptions {
+  /**
+   * Show startup banner. Set to false to disable.
+   * @default true
+   */
+  banner?: boolean;
+
+  /**
+   * Group client ("use client") components into browser chunks for per-route /
+   * per-feature code splitting. On by default (pre-1.0); pass `false` to opt out.
+   * See {@link ClientChunks}.
+   *
+   * @default true
+   */
+  clientChunks?: ClientChunks;
+
+  /**
+   * 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
+   */
+  buildEnv?: BuildEnvOption;
+}
+
+/**
+ * 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,94 @@
+import type { Plugin } from "vite";
+import { createRangoDebugger, NS } from "../debug.js";
+
+const debug = createRangoDebugger(NS.transform);
+
+/**
+ * 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].replaceAll("\\", "/");
+
+      // Transform the client.browser.js entry point to re-export from CJS
+      if (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";
+
+        debug?.("cjs-to-esm entry redirect %s", id);
+        return {
+          code: `export * from "${cjsFile}";`,
+          map: null,
+        };
+      }
+
+      // Transform the actual CJS files to ESM
+      if (
+        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;
+
+        debug?.("cjs-to-esm body rewrite %s", id);
+        return {
+          code: transformed,
+          map: null,
+        };
+      }
+
+      return null;
+    },
+  };
+}

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

@@ -0,0 +1,131 @@
+import type { Plugin, ResolvedConfig } from "vite";
+import { createRangoDebugger, NS } from "../debug.js";
+
+const debug = createRangoDebugger(NS.transform);
+
+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[] = [];
+  const dedupedPackages = new Set<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 ?? [];
+    },
+
+    buildEnd() {
+      if (debug && dedupedPackages.size > 0) {
+        debug(
+          "client-ref-dedup: redirected %d package(s) (%s)",
+          dedupedPackages.size,
+          [...dedupedPackages].join(","),
+        );
+      }
+    },
+
+    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;
+
+      if (debug) dedupedPackages.add(packageName);
+
+      // 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,128 @@
+import type { Plugin } from "vite";
+import { relative } from "node:path";
+import { createHash } from "node:crypto";
+import { createRangoDebugger, createCounter, NS } from "../debug.js";
+
+const debug = createRangoDebugger(NS.transform);
+
+// 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).
+ */
+/**
+ * The production client-reference key hash: `sha256(relativeId).slice(0,12)`,
+ * matching @vitejs/plugin-rsc's `hashString`. Exported so the client-chunks
+ * strategy can hash a `clientChunks` callback's `meta.normalizedId` (already the
+ * project-root-relative id) and compare it against fallback hashes collected
+ * during discovery.
+ */
+export function hashRefKey(relativeId: string): string {
+  return createHash("sha256").update(relativeId).digest("hex").slice(0, 12);
+}
+
+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 hashRefKey(toHash);
+}
+
+// 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 {
+  const counter = createCounter(debug, "hash-client-refs");
+  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";
+    },
+    buildEnd() {
+      counter?.flush();
+    },
+    transform(code, id) {
+      const start = counter ? performance.now() : 0;
+      try {
+        const result = transformClientRefs(code, projectRoot);
+        if (result === null) return;
+        return { code: result, map: null };
+      } finally {
+        counter?.record(id, performance.now() - start);
+      }
+    },
+  };
+}

package/src/vite/plugins/cloudflare-protocol-loader-hook.d.mts

@@ -0,0 +1,23 @@
+export interface LoaderResolveContext {
+  parentURL?: string;
+  conditions?: readonly string[];
+  importAttributes?: Record<string, string>;
+}
+
+export interface LoaderResolveResult {
+  shortCircuit?: boolean;
+  url: string;
+  format?: "module" | "commonjs" | "json" | "wasm" | null;
+  importAttributes?: Record<string, string>;
+}
+
+export type NextResolve = (
+  specifier: string,
+  context?: LoaderResolveContext,
+) => Promise<LoaderResolveResult>;
+
+export function resolve(
+  specifier: string,
+  context: LoaderResolveContext,
+  nextResolve: NextResolve,
+): Promise<LoaderResolveResult>;

package/src/vite/plugins/cloudflare-protocol-loader-hook.mjs

@@ -0,0 +1,76 @@
+// Node ESM loader hook that resolves `cloudflare:*` imports to the same
+// stub ESM the Vite transform produces for rewritten specifiers.
+//
+// Why both? The Vite transform (cloudflare-protocol-stub.ts) catches
+// imports in modules that flow through Vite's plugin pipeline — covers
+// user source and any node_modules package Vite fetches and transforms.
+// But Vite/Rollup externalize certain packages (e.g. `partyserver`,
+// which has `import { DurableObject, env } from "cloudflare:workers"`
+// at its top level, and similar "workerd-native" libraries). Externalized
+// modules bypass the transform: Rollup hands their resolution to Node's
+// native ESM loader, which rejects URL-scheme specifiers. This loader
+// hook registers via `module.register()` from `createTempRscServer` and
+// intercepts `cloudflare:*` at Node's resolve layer — before the default
+// loader throws ERR_UNSUPPORTED_ESM_URL_SCHEME.
+//
+// Lifecycle: the hook runs in a dedicated worker thread (Node ESM loader
+// architecture) with its own globalThis. It cannot see the main thread's
+// `__rango_build_env__` bridge, so the `env` export here is always `{}`.
+// That's fine in practice — externalized libraries don't typically touch
+// `env` at module top level; they read it at request time in workerd
+// where the real module exists. Build-time prerender handlers in user
+// source DO read `env`, but they flow through the Vite transform (which
+// does bridge `env` from `getPlatformProxy()`), not through this loader.
+//
+// Keep STUBS in sync with cloudflare-protocol-stub.ts — both paths need
+// to hand out the same base classes.
+
+const CF_PREFIX = "cloudflare:";
+
+const STUBS = {
+  "cloudflare:workers": `
+export class DurableObject { constructor(_ctx, _env) {} }
+export class WorkerEntrypoint { constructor(_ctx, _env) {} }
+export class WorkflowEntrypoint { constructor(_ctx, _env) {} }
+export class RpcTarget {}
+export const env = {};
+export default {};
+`,
+  "cloudflare:email": `
+export class EmailMessage { constructor(_from, _to, _raw) {} }
+export default {};
+`,
+  "cloudflare:sockets": `
+export function connect() { return {}; }
+export default {};
+`,
+  "cloudflare:workflows": `
+export class NonRetryableError extends Error {
+  constructor(message, name) { super(message); this.name = name ?? "NonRetryableError"; }
+}
+export default {};
+`,
+};
+
+// Policy: unknown `cloudflare:*` specifiers resolve permissively to an
+// empty default export rather than throwing. Same reasoning as
+// cloudflare-protocol-stub.ts's FALLBACK_STUB — we prioritize
+// dependency-graph resilience over strict validation, because third-party
+// packages can pull `cloudflare:*` modules we haven't curated.
+const FALLBACK_STUB = `export default {};\n`;
+
+function dataUrlFor(specifier) {
+  const body = STUBS[specifier] ?? FALLBACK_STUB;
+  return "data:text/javascript;base64," + Buffer.from(body).toString("base64");
+}
+
+export async function resolve(specifier, context, nextResolve) {
+  if (specifier.startsWith(CF_PREFIX)) {
+    return {
+      shortCircuit: true,
+      url: dataUrlFor(specifier),
+      format: "module",
+    };
+  }
+  return nextResolve(specifier, context);
+}