@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.80daa23e

package/src/vite/inject-client-debug.ts

@@ -0,0 +1,88 @@
+import type { Connect } from "vite";
+
+/**
+ * Bake the resolved INTERNAL_RANGO_DEBUG value into the router's `internal-debug`
+ * module so the flag reaches the CLIENT debug logs by just setting the env var.
+ *
+ * internal-debug.ts normally reads the flag via `typeof __RANGO_DEBUG__`, a Vite
+ * define. That delivery is unreliable on the client: in dev Vite ships the define
+ * only as an injected global whose presence varies across consumer setups, so the
+ * module can fall through to `process.env` (undefined in the browser) and the FE
+ * debug flag silently stays false while the server logs work. A Vite `transform`
+ * runs on the module regardless of how (or whether) the define is delivered, in
+ * both dev and build and for every environment, so the discovery plugin uses this
+ * to replace the module with the resolved literal.
+ */
+
+/**
+ * Scope to the router's own internal-debug module: the published package
+ * (`/@rangojs/router/`, incl. pnpm's nested layout) or the monorepo workspace
+ * (`/packages/rangojs-router/`). The package-anchored path avoids matching a
+ * consumer file that merely sits under a directory named `rangojs-router`.
+ * Accepts module ids and dev-server URLs (`/@fs/...internal-debug.ts?v=abc`).
+ */
+export function isRouterInternalDebugId(id: string): boolean {
+  if (!id.includes("internal-debug")) return false;
+  const norm = id.replace(/\\/g, "/");
+  return (
+    /\/internal-debug\.[cm]?[jt]sx?(\?|$)/.test(norm) &&
+    (norm.includes("/@rangojs/router/") ||
+      norm.includes("/packages/rangojs-router/"))
+  );
+}
+
+/**
+ * Transform: replace the module with the resolved literal.
+ * Returns null for any module that is not the router's internal-debug module.
+ */
+export function injectClientDebugFlag(
+  id: string,
+): { code: string; map: null } | null {
+  // Cheap early-out: this hook runs on every module in every environment.
+  if (!isRouterInternalDebugId(id)) return null;
+  // Emit the whole module: internal-debug.ts has a single export, kept in sync.
+  return {
+    code: `export const INTERNAL_RANGO_DEBUG = ${!!process.env.INTERNAL_RANGO_DEBUG};\n`,
+    map: null,
+  };
+}
+
+/**
+ * Dev middleware companion: serve the internal-debug module `no-cache` so the
+ * browser revalidates it (etag) instead of trusting an immutable cache entry.
+ *
+ * Why: the transform bakes the flag into module CONTENT, but a published
+ * consumer resolves the module into node_modules, where dev serves it as
+ * `internal-debug.ts?v=<hash>` with `Cache-Control: max-age=31536000,immutable`.
+ * That `?v=` hash does not vary with env vars (verified on Vite 8: getConfigHash
+ * hashes NODE_ENV, resolve, plugin names, optimizeDeps -- not arbitrary env
+ * state), so toggling the flag changed the content under an unchanged immutable
+ * URL: a browser that ever loaded the app with the flag off kept the
+ * baked-`false` module across dev-server restarts, and INTERNAL_RANGO_DEBUG
+ * never reached the FE logs while the server logs worked. The monorepo was
+ * immune -- workspace source is outside node_modules and served no-cache --
+ * which is why this bit only npm consumers.
+ *
+ * internal-debug.ts is the ONLY flag-varying module in the graph (its importers
+ * are byte-identical across flag states), so forcing revalidation for this one
+ * tiny module is sufficient and costs one conditional request per session. The
+ * middleware is unconditional (not gated on the flag) so an already-poisoned
+ * cache heals in both directions. Alternatives that do not work: a plugin
+ * `resolveId` appending a flag query never fires in Vite 8 dev for
+ * fs-resolvable relative imports, and the pre-#621 `define` no longer rotates
+ * the optimizer hash (define contents are not part of getConfigHash).
+ */
+export function internalDebugNoCacheMiddleware(): Connect.NextHandleFunction {
+  return function rangoInternalDebugNoCache(req, res, next) {
+    if (req.url && isRouterInternalDebugId(req.url)) {
+      const setHeader = res.setHeader.bind(res);
+      res.setHeader = (name, value) => {
+        return setHeader(
+          name,
+          name.toLowerCase() === "cache-control" ? "no-cache" : value,
+        );
+      };
+    }
+    next();
+  };
+}

package/src/vite/plugin-types.ts

@@ -0,0 +1,336 @@
+// -- 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" | "vercel";
+}
+
+/**
+ * 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 ---------------------------------------------------------
+
+/**
+ * Document script strategy. See {@link RangoBaseOptions.headScripts}.
+ */
+export type HeadScriptsOption = "preinit" | "preload";
+
+/**
+ * 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;
+
+  /**
+   * How the document ships its JavaScript.
+   *
+   * - `"preinit"` (**default**): client-reference chunks render as EXECUTING
+   *   `<script type="module" async>` tags hoisted into `<head>` (upgrading
+   *   plugin-rsc's modulepreload hints in place), and the browser entry ships
+   *   as Fizz `bootstrapModules` — a head `modulepreload fetchpriority=low`
+   *   hint plus the executing end-of-shell `id="_R_"` module script. Chunk
+   *   execution overlaps body streaming instead of waiting for the hydration
+   *   import walk; under PPR everything lands in the stored shell prelude.
+   * - `"preload"`: the previous behavior — `<link rel="modulepreload">` hints
+   *   only, entry as an inline `import()` script at end of shell. Chunks
+   *   fetch+compile early but execute only when hydration imports them.
+   *
+   * Build-only for the chunk half: plugin-rsc resolves no JS deps per client
+   * reference in dev, so dev documents carry no head chunk scripts in either
+   * mode (the bootstrap conversion does apply in dev). Trades and upstream
+   * limits are documented in src/ssr/preinit-client-references.ts.
+   *
+   * Wired in the generated virtual SSR entry
+   * (`src/ssr/preinit-client-references.ts` has the mechanism); apps with a
+   * custom SSR entry choose per-handler via `SSRDependencies.headScripts` and
+   * `installClientReferencePreinit`.
+   *
+   * @default "preinit"
+   */
+  headScripts?: HeadScriptsOption;
+
+  /**
+   * Filter which files route discovery scans, by glob. Paths are matched
+   * root-relative (e.g. `src/routes/**`). `include` restricts discovery to
+   * matching files; `exclude` removes matches (the defaults cover tests, dist,
+   * coverage, etc.). Mirrors the CLI's `--include`/`--exclude`.
+   *
+   * @example
+   * rango({ discovery: { include: ["src/routes/**"] } })
+   */
+  discovery?: {
+    include?: string[];
+    exclude?: string[];
+  };
+
+  /**
+   * What to do when a `Prerender` route's or `Static` handler's render throws at
+   * build time. Otherwise the route error boundary catches it and the rendered
+   * error page is baked as the artifact, then served as an HTTP 200 — a silent,
+   * user-visible breakage (issue #587). Independent of this setting, a render may
+   * `throw new Skip()` (from `@rangojs/router`) to skip a single URL/handler.
+   *
+   * - `"fail"` (**default**): fail the build, naming the URL/handler and the
+   *   original render error.
+   * - `"warn"`: log a warning and skip baking the artifact — it is never served as a
+   *   baked 200 error page. `"warn"` is a build-unblock, NOT a runtime contract for
+   *   the skipped entry: the route falls through to normal resolution, which may
+   *   render live (its handler is still bundled — e.g. when nothing else baked) or
+   *   404 (once prerender handler eviction has run for other baked entries), so the
+   *   outcome depends on the rest of the build, and a skipped `Static()` handler's
+   *   evicted code can surface as an error. For DEFINED runtime behavior use
+   *   `Passthrough()` (a live fallback) or `throw new Skip()` (an intentional skip);
+   *   otherwise prefer the default `"fail"`.
+   *
+   * @default "fail"
+   */
+  prerender?: {
+    onError?: "fail" | "warn";
+  };
+}
+
+/**
+ * Options for Node.js deployment (default)
+ */
+export interface RangoNodeOptions extends RangoBaseOptions {
+  /**
+   * Deployment preset. Defaults to 'node' when not specified.
+   */
+  preset?: "node";
+
+  /**
+   * Path to a host-router entry (a module that calls `createHostRouter()` and
+   * exports the instance) to serve instead of a single `createRouter()` app.
+   * Root-relative (e.g. `"./src/worker.rsc.tsx"`).
+   *
+   * Set this when the app is a multi-app host router: auto-discovery otherwise
+   * finds the sub-apps' multiple `createRouter()` files and cannot pick an entry.
+   * When omitted, rango auto-detects a single `createHostRouter()` file if the
+   * app has several `createRouter()` files. The host module must export the
+   * `HostRouter` instance (default export or a named `hostRouter`/`router`
+   * export), not a Cloudflare-style `{ fetch }` object.
+   */
+  hostRouter?: string;
+
+  /**
+   * Environment bindings available to Prerender and Static handlers at build
+   * time via `ctx.env`. Shared across all prerender invocations for the build.
+   *
+   * `"auto"` is Cloudflare-only (it resolves the wrangler platform proxy), so it
+   * is not accepted on the Node preset — pass an object or a factory instead.
+   *
+   * @default false
+   */
+  buildEnv?: Exclude<BuildEnvOption, "auto">;
+}
+
+/**
+ * Options for Cloudflare Workers deployment
+ */
+export interface RangoCloudflareOptions extends RangoBaseOptions {
+  /**
+   * Deployment preset for Cloudflare Workers.
+   * When using cloudflare preset:
+   * - @vitejs/plugin-rsc IS still added by rango(), but with `serverHandler: false`
+   *   (the cloudflare plugin owns the RSC worker/server entry); only `client` and
+   *   `ssr` virtual entries are configured, no rsc entry
+   * - 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";
+
+  /**
+   * Environment bindings available to Prerender and Static handlers at build
+   * time via `ctx.env`. Shared across all prerender invocations for the build.
+   *
+   * `"auto"` resolves the Cloudflare platform proxy via wrangler
+   * `getPlatformProxy()`.
+   *
+   * @default false
+   */
+  buildEnv?: BuildEnvOption;
+}
+
+/**
+ * Per-function knobs for the Vercel deployment, written into the generated
+ * `.vc-config.json` (and `config.json` for `functionName`).
+ */
+export interface VercelPresetOptions {
+  /** Node runtime for the function. @default "nodejs24.x" */
+  runtime?: string;
+  /** Max execution time in seconds. @default 30 */
+  maxDuration?: number;
+  /** Function memory in MB (platform default when omitted). */
+  memory?: number;
+  /** Regions to pin the function to (platform default when omitted). */
+  regions?: string[];
+  /**
+   * Function name — the `<name>.func` directory and the `config.json` route
+   * destination. @default "index"
+   */
+  functionName?: string;
+}
+
+/**
+ * Options for Vercel Functions deployment.
+ *
+ * Builds like the node preset (Vercel runs Node Functions, not Workers): rango
+ * owns the RSC entry, `process.env.NODE_ENV` is folded for the build, and after
+ * the build a `.vercel/output` directory (Build Output API v3) is assembled from
+ * `dist/` — a single streaming Node Function plus the static client assets. The
+ * app must install `@vercel/functions` (used by `VercelCacheStore` and the
+ * generated function launcher).
+ */
+export interface RangoVercelOptions extends RangoBaseOptions {
+  /**
+   * Deployment preset for Vercel Functions.
+   */
+  preset: "vercel";
+
+  /**
+   * Path to a host-router entry (a module that calls `createHostRouter()` and
+   * exports the instance) to serve instead of a single `createRouter()` app.
+   * Root-relative (e.g. `"./src/worker.rsc.tsx"`).
+   *
+   * Set this when the app is a multi-app host router: auto-discovery otherwise
+   * finds the sub-apps' multiple `createRouter()` files and cannot pick an entry.
+   * When omitted, rango auto-detects a single `createHostRouter()` file if the
+   * app has several `createRouter()` files. The host module must export the
+   * `HostRouter` instance (default export or a named `hostRouter`/`router`
+   * export), not a Cloudflare-style `{ fetch }` object. The Vercel function then
+   * runs `hostRouter.match()` for every request (single-function deploy).
+   */
+  hostRouter?: string;
+
+  /**
+   * Environment bindings available to Prerender and Static handlers at build
+   * time via `ctx.env`. `"auto"` is Cloudflare-only; pass an object or a factory.
+   *
+   * @default false
+   */
+  buildEnv?: Exclude<BuildEnvOption, "auto">;
+
+  /**
+   * Vercel function configuration written into the Build Output.
+   */
+  vercel?: VercelPresetOptions;
+}
+
+/**
+ * Options for rango() Vite plugin
+ */
+export type RangoOptions =
+  | RangoNodeOptions
+  | RangoCloudflareOptions
+  | RangoVercelOptions;

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

@@ -0,0 +1,90 @@
+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 {
+  // Picked from Vite's resolved mode, not process.env.NODE_ENV, so the dev vs
+  // production vendor variant tracks the build mode the user actually ran.
+  let isProduction = false;
+
+  return {
+    name: "@rangojs/router:cjs-to-esm",
+    enforce: "pre",
+    configResolved(config) {
+      isProduction = config.isProduction;
+    },
+    transform(code, id) {
+      const cleanId = id.split("?")[0].replaceAll("\\", "/");
+
+      if (cleanId.includes("vendor/react-server-dom/client.browser.js")) {
+        const isProd = isProduction;
+        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,
+        };
+      }
+
+      if (
+        cleanId.includes("vendor/react-server-dom/cjs/") &&
+        cleanId.includes("client.browser")
+      ) {
+        let transformed = code;
+
+        const licenseMatch = transformed.match(/^\/\*\*[\s\S]*?\*\//);
+        const license = licenseMatch ? licenseMatch[0] : "";
+        if (license) {
+          transformed = transformed.slice(license.length);
+        }
+
+        transformed = transformed.replace(/^\s*["']use strict["'];\s*/, "");
+
+        transformed = transformed.replace(
+          /^\s*["']production["']\s*!==\s*process\.env\.NODE_ENV\s*&&\s*\(function\s*\(\)\s*\{/,
+          "",
+        );
+
+        transformed = transformed.replace(/\}\)\(\);?\s*$/, "");
+
+        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 ',
+        );
+
+        transformed = transformed.replace(
+          /var\s+ReactDOM\s*=\s*require\s*\(\s*["']react-dom["']\s*\)\s*,/g,
+          'import ReactDOM from "react-dom";\nvar ',
+        );
+
+        transformed = transformed.replace(
+          /exports\.(\w+)\s*=\s*function\s*\(/g,
+          "export function $1(",
+        );
+
+        transformed = transformed.replace(
+          /exports\.(\w+)\s*=/g,
+          "export const $1 =",
+        );
+
+        transformed = license + "\n" + transformed;
+
+        debug?.("cjs-to-esm body rewrite %s", id);
+        return {
+          code: transformed,
+          map: null,
+        };
+      }
+
+      return null;
+    },
+  };
+}