@rangojs/router 0.0.0-experimental.138 → 0.0.0-experimental.139

package/src/vite/plugins/virtual-entries.ts

@@ -125,6 +125,78 @@ export default function handler(request, env) {
 `.trim();
 }
 
+export function getVirtualEntryRSCHost(hostEntryPath: string): string {
+  return `
+import * as __hostEntry from "${hostEntryPath}";
+import { isNoRouteMatchError } from "@rangojs/router/host";
+
+// Register every sub-app's fetchable loaders + route manifests at startup, same
+// as the single-router entry. Discovery's host fallback populates these for all
+// mounted sub-apps, so the aggregate manifests cover the whole host tree.
+import "virtual:rsc-router/loader-manifest";
+import "virtual:rsc-router/routes-manifest";
+
+// The host entry module must export the HostRouter instance (createHostRouter()),
+// as a default export or a named \`hostRouter\`/\`router\` export. A Cloudflare-style
+// \`export default { fetch }\` object is not a HostRouter and is rejected (on first
+// request; see the lazy resolution below).
+// We require BOTH .match() and .host(): a regular createRouter() also exposes
+// .match(), so matching on .match() alone would accept an ordinary router and then
+// return its MatchResult (not a Response) at runtime. .host() is unique to a
+// HostRouter, so it disambiguates a mistaken \`hostRouter\` path.
+// Exports are read dynamically (m[name]) so Rollup does not emit IMPORT_IS_UNDEFINED
+// warnings for the named exports a default-only host module legitimately omits.
+const __resolveHostRouter = (m) => {
+  for (const name of ["default", "hostRouter", "router"]) {
+    const candidate = m[name];
+    if (
+      candidate &&
+      typeof candidate.match === "function" &&
+      typeof candidate.host === "function"
+    )
+      return candidate;
+  }
+  return undefined;
+};
+
+// Resolve + validate the HostRouter lazily on first request, mirroring the
+// single-router entry's \`_handler\`. During HMR the host module can re-evaluate
+// before its createHostRouter() export has resolved; validating at module-
+// evaluation time would then throw a spurious "must export a HostRouter" error
+// overlay for a perfectly valid app. Resolving on first request lets the live
+// binding settle first.
+let _hostRouter;
+
+// input = { env, ctx } from the launcher / node server. The host router threads
+// it unchanged to each matched sub-app's handler and cache factory.
+// On node/vercel rango owns this entry, so there is no user worker to translate
+// an unmatched host into a response: catch NoRouteMatchError and return 404
+// (parity with the documented Cloudflare catch). Other errors propagate.
+export default async function handler(request, input) {
+  if (!_hostRouter) {
+    _hostRouter = __resolveHostRouter(__hostEntry);
+    if (!_hostRouter) {
+      throw new Error(
+        "[rango] The host entry (${hostEntryPath}) must export a HostRouter instance (createHostRouter()) for the node/vercel preset: a default export, or a named 'hostRouter'/'router' export. An ordinary createRouter() is not a host router (it has no .host()), and a Cloudflare-style 'export default { fetch }' object is not supported on this preset."
+      );
+    }
+  }
+  try {
+    return await _hostRouter.match(request, input);
+  } catch (err) {
+    // isNoRouteMatchError also matches by name: a workspace with a duplicated
+    // @rangojs/router copy can throw a NoRouteMatchError whose prototype differs
+    // from this module's import, so a bare instanceof would turn an
+    // unmatched-host 404 into a 500.
+    if (isNoRouteMatchError(err)) {
+      return new Response("Not Found", { status: 404 });
+    }
+    throw err;
+  }
+}
+`.trim();
+}
+
 export const VIRTUAL_IDS = {
   browser: "virtual:rsc-router/entry.browser.js",
   ssr: "virtual:rsc-router/entry.ssr.js",

package/src/vite/rango.ts

@@ -1,5 +1,5 @@
 import { type PluginOption } from "vite";
-import { readFileSync } from "node:fs";
+import { readFileSync, existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { exposeActionId } from "./plugins/expose-action-id.js";
 import {
@@ -15,11 +15,15 @@ import {
   getPublishedPackageName,
   getVendorAliases,
 } from "./utils/package-resolution.js";
-import { findRouterFiles } from "../build/generate-route-types.js";
+import {
+  findRouterFiles,
+  findHostRouterFiles,
+} from "../build/generate-route-types.js";
 import { createVersionPlugin } from "./plugins/version-plugin.js";
 import {
   sharedRolldownOptions,
   createVirtualEntriesPlugin,
+  normalizeHostRouterEntry,
   onwarn,
   getManualChunks,
 } from "./utils/shared-utils.js";
@@ -27,7 +31,12 @@ import {
   resolveClientChunks,
   type ClientChunkContext,
 } from "./utils/client-chunks.js";
-import type { RangoOptions } from "./plugin-types.js";
+import type {
+  RangoOptions,
+  RangoNodeOptions,
+  RangoVercelOptions,
+} from "./plugin-types.js";
+import { createVercelOutputPlugin } from "./plugins/vercel-output.js";
 import { printBanner, rangoVersion } from "./utils/banner.js";
 import { createVersionInjectorPlugin } from "./plugins/version-injector.js";
 import { createCjsToEsmPlugin } from "./plugins/cjs-to-esm.js";
@@ -110,10 +119,20 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
   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.
-  const routerRef: { path: string | undefined } = { path: undefined };
+  // Mutable ref for the served entry path (node/vercel presets only). Populated
+  // by the auto-discover config() hook using Vite's resolved root. `kind` selects
+  // the RSC entry template: "router" wraps a single createRouter() app in
+  // createRSCHandler; "host" wraps a createHostRouter() instance and serves it
+  // via hostRouter.match().
+  const routerRef: { path: string | undefined; kind: "router" | "host" } = {
+    path: undefined,
+    kind: "router",
+  };
+  // Explicit host-router entry (node/vercel `hostRouter` option), root-relative.
+  const explicitHostRouter =
+    preset !== "cloudflare"
+      ? (resolvedOptions as RangoNodeOptions | RangoVercelOptions).hostRouter
+      : undefined;
 
   // Build-time prerendering is enabled for both presets.
   // Collection runs in-process via the RSC dev environment runner during discoverRouters().
@@ -238,20 +257,65 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
         const root = userConfig.root
           ? resolve(process.cwd(), userConfig.root)
           : process.cwd();
+        const toRootRelative = (abs: string) =>
+          (abs.startsWith(root)
+            ? "./" + abs.slice(root.length + 1)
+            : abs
+          ).replaceAll("\\", "/");
+        const bulletList = (files: string[]) =>
+          files.map((f) => "  - " + toRootRelative(f)).join("\n");
+
+        // 1. Explicit host entry wins: serve the createHostRouter() instance.
+        if (explicitHostRouter) {
+          routerRef.path = normalizeHostRouterEntry(
+            explicitHostRouter,
+            root,
+            existsSync,
+          );
+          routerRef.kind = "host";
+          return;
+        }
+
+        // 2. A createHostRouter() file means this is a multi-app host deploy:
+        // serve it via the host entry. Checked BEFORE single-router discovery,
+        // because a host app may compose just one createRouter() sub-app plus
+        // host middleware / domain rules / inline .map() routes -- and a lone
+        // sub-app must not shadow the host entry (it would bypass
+        // hostRouter.match()).
+        const hostCandidates = findHostRouterFiles(root);
+        if (hostCandidates.length === 1) {
+          const hostPath = toRootRelative(hostCandidates[0]);
+          // Auto-detection preempts single-router discovery, so name the winning
+          // file: a stale prototype still containing `createHostRouter(` would
+          // otherwise silently become the served entry in place of the app.
+          // eslint-disable-next-line no-console
+          console.info(
+            `[rango] Serving host router entry ${hostPath} (auto-detected). ` +
+              `Set the \`hostRouter\` option to override.`,
+          );
+          routerRef.path = hostPath;
+          routerRef.kind = "host";
+          return;
+        }
+        if (hostCandidates.length > 1) {
+          throw new Error(
+            `[rango] Multiple host routers found:\n${bulletList(hostCandidates)}\n\n` +
+              `Set the \`hostRouter\` option to the entry to serve, e.g. rango({ preset: "${preset}", hostRouter: "./src/worker.rsc.tsx" }).`,
+          );
+        }
+
+        // 3. No host entry: single createRouter() app.
         const candidates = findRouterFiles(root);
         if (candidates.length === 1) {
-          const abs = candidates[0];
-          routerRef.path = (
-            abs.startsWith(root) ? "./" + abs.slice(root.length + 1) : abs
-          ).replaceAll("\\", "/");
-        } else if (candidates.length > 1) {
-          const list = candidates
-            .map(
-              (f) =>
-                "  - " + (f.startsWith(root) ? f.slice(root.length + 1) : f),
-            )
-            .join("\n");
-          throw new Error(`[rango] Multiple routers found:\n${list}`);
+          routerRef.path = toRootRelative(candidates[0]);
+          routerRef.kind = "router";
+          return;
+        }
+        if (candidates.length > 1) {
+          throw new Error(
+            `[rango] Multiple routers found:\n${bulletList(candidates)}\n\n` +
+              `If this is a multi-app host router, export a createHostRouter() instance and set the \`hostRouter\` option (e.g. rango({ preset: "${preset}", hostRouter: "./src/worker.rsc.tsx" })), or use preset: "cloudflare" where you own the worker entry.`,
+          );
         }
       },
     });
@@ -270,8 +334,34 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
       name: "@rangojs/router:rsc-integration",
       enforce: "pre",
 
-      config() {
+      config(_userConfig, configEnv) {
+        // Fold NODE_ENV for the vercel preset's build. The cloudflare plugin
+        // does this automatically and node apps do it themselves; vercel has no
+        // platform plugin, so without this React's CJS dev branch survives and
+        // doubles the SSR/RSC bundle (Bundle Hygiene rule #2). Only the exact
+        // `process.env.NODE_ENV` token is replaced.
+        const vercelDefine =
+          preset === "vercel" && configEnv.command === "build"
+            ? { "process.env.NODE_ENV": JSON.stringify("production") }
+            : undefined;
+        // The vercel preset's deployed function has no node_modules, so the
+        // server bundles must be fully self-contained. Bundle every dependency
+        // into the rsc + ssr builds instead of externalizing them (the node
+        // default, which only works because `vite preview` runs where
+        // node_modules exists). node: builtins stay external automatically.
+        //
+        // BUILD ONLY. In `vite dev` this must NOT apply: noExternal forces every
+        // server dependency through the RSC/SSR dev module runners, which cannot
+        // load many CJS packages (pg, mysql2, most SDKs, @vercel/functions) and
+        // crashes the dev server -- while the same app runs fine under
+        // preset: "node" and in the production build. Gating on `build` restores
+        // node-preset dev semantics (deps externalized to Node's require).
+        const vercelServerEnv =
+          preset === "vercel" && configEnv.command === "build"
+            ? { resolve: { noExternal: true as const } }
+            : undefined;
         return {
+          ...(vercelDefine ? { define: vercelDefine } : {}),
           optimizeDeps: {
             exclude: excludeDeps,
             rolldownOptions: sharedRolldownOptions,
@@ -314,6 +404,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
               },
             },
             ssr: {
+              ...(vercelServerEnv ?? {}),
               optimizeDeps: {
                 entries: [VIRTUAL_IDS.ssr],
                 include: [
@@ -332,6 +423,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
               },
             },
             rsc: {
+              ...(vercelServerEnv ?? {}),
               optimizeDeps: {
                 entries: [VIRTUAL_IDS.rsc],
                 include: [
@@ -363,7 +455,11 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
                 ? "preview"
                 : "dev"
               : "build";
-          printBanner(mode, "node", rangoVersion);
+          printBanner(
+            mode,
+            preset === "vercel" ? "vercel" : "node",
+            rangoVersion,
+          );
         }
 
         const rscMinimalCount = config.plugins.filter(
@@ -443,6 +539,17 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
     }),
   );
 
+  // Vercel preset: assemble .vercel/output from dist/ after the build. Pushed
+  // last so its buildApp (order "post") hook runs after the discovery plugin's
+  // rsc-env postprocess. buildApp fires once after the whole multi-environment
+  // build, so dist/ is complete (closeBundle is unusable here -- it fires per
+  // environment, twice for ssr; see the plugin's own note).
+  if (preset === "vercel") {
+    plugins.push(
+      createVercelOutputPlugin(resolvedOptions as RangoVercelOptions),
+    );
+  }
+
   debugConfig?.(
     "rango(%s) setup done: %d plugin(s) (%sms)",
     preset,

package/src/vite/utils/shared-utils.ts

@@ -1,11 +1,13 @@
 import type { Plugin, ResolvedConfig } from "vite";
 import * as Vite from "vite";
+import { isAbsolute, resolve } from "node:path";
 import { getPublishedPackageName } from "./package-resolution.js";
 import { performanceTracksOptimizeDepsPlugin } from "../plugins/performance-tracks.js";
 import {
   VIRTUAL_ENTRY_BROWSER,
   VIRTUAL_ENTRY_SSR,
   getVirtualEntryRSC,
+  getVirtualEntryRSCHost,
   getVirtualVersionContent,
   VIRTUAL_IDS,
 } from "../plugins/virtual-entries.js";
@@ -54,13 +56,59 @@ export const sharedRolldownOptions: {
   plugins: [versionRolldownPlugin, performanceTracksOptimizeDepsPlugin()],
 };
 
+/**
+ * Normalize an explicit `hostRouter` option into the specifier emitted as the
+ * host entry's `import ... from "<path>"`, and — for the forms that resolve
+ * unambiguously against the project root — verify the file exists (failing with
+ * a rango message instead of a downstream bundler "failed to resolve").
+ *
+ * Only a BARE specifier ("src/worker.rsc.tsx") that exists under the root is
+ * rewritten (to "./src/...") so it is not read as a package. A bare specifier
+ * that does NOT exist under the root is passed through VERBATIM: it may be a
+ * Vite alias ("@/worker.rsc.tsx"), an imports-map entry ("#app/worker"), or a
+ * workspace package the bundler resolves — rewriting or rejecting those was a
+ * regression (aliases worked before normalization existed). "./"/"../", a
+ * leading-slash (Vite root-relative), and a filesystem-absolute path are
+ * emitted unchanged — Vite resolves each. A leading-slash path and a
+ * filesystem-absolute path are indistinguishable on POSIX, so both are treated
+ * as "rooted": passed through WITHOUT an existence check (guessing between the
+ * two would wrongly reject a valid file — this was a regression the first time
+ * the check was added). Only the explicitly-relative forms, which resolve
+ * unambiguously against the root, fail fast with a rango message.
+ *
+ * `exists` is injected so the logic is unit-testable without a real filesystem.
+ */
+export function normalizeHostRouterEntry(
+  rawInput: string,
+  root: string,
+  exists: (absPath: string) => boolean,
+): string {
+  const raw = rawInput.replaceAll("\\", "/");
+  const isRelative = raw.startsWith("./") || raw.startsWith("../");
+  const isRooted = raw.startsWith("/") || isAbsolute(rawInput);
+  if (isRooted) return raw;
+  if (isRelative) {
+    if (!exists(resolve(root, raw))) {
+      throw new Error(
+        `[rango] hostRouter entry not found: "${rawInput}" (resolved under ` +
+          `${root}). Point it at your createHostRouter() module, e.g. ` +
+          `rango({ hostRouter: "./src/worker.rsc.tsx" }).`,
+      );
+    }
+    return raw;
+  }
+  // Bare specifier: an existing root-relative file gets the explicit "./";
+  // anything else (alias, imports-map, package) is the bundler's to resolve.
+  return exists(resolve(root, raw)) ? "./" + raw : raw;
+}
+
 /**
  * Create a virtual modules plugin for default entry files.
  * Provides virtual module content when entries use VIRTUAL_IDS (no custom entry configured).
  */
 export function createVirtualEntriesPlugin(
   entries: { client: string; ssr: string; rsc?: string },
-  routerPathRef?: { path?: string },
+  routerPathRef?: { path?: string; kind?: "router" | "host" },
 ): Plugin {
   // Build virtual modules map based on which entries use virtual IDs
   const virtualModules: Record<string, string> = {};
@@ -108,7 +156,9 @@ export function createVirtualEntriesPlugin(
             : routerPathRef.path;
           // Normalize backslashes for Windows (path.join/slice preserve native separators)
           const absoluteRouterPath = raw.replaceAll("\\", "/");
-          return getVirtualEntryRSC(absoluteRouterPath);
+          return routerPathRef.kind === "host"
+            ? getVirtualEntryRSCHost(absoluteRouterPath)
+            : getVirtualEntryRSC(absoluteRouterPath);
         }
       }
       return null;