@rangojs/router 0.0.0-experimental.e9c0b2f2 → 0.0.0-experimental.ea9f40f2

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/plugins/vercel-output.ts

@@ -46,7 +46,11 @@ import { existsSync } from "node:fs";
 import { resolve, join } from "node:path";
 import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
-import type { RangoVercelOptions } from "../plugin-types.js";
+import { escapeRegExp } from "../../regex-escape.js";
+import type {
+  RangoVercelOptions,
+  VercelPresetOptions,
+} from "../plugin-types.js";
 
 // Minimal structural types for the esbuild API we use, resolved dynamically from
 // the app so @rangojs/router does not depend on esbuild's type package.
@@ -100,14 +104,106 @@ export function assertVercelNodeRuntime(runtime: string | undefined): void {
   }
 }
 
+/**
+ * The function name becomes a `.func` directory segment and the config.json
+ * route `dest` (`/${functionName}`). An empty or space/slash-containing value
+ * would land raw in both, producing a broken function path, so restrict it to a
+ * safe single path segment and fail loudly rather than emit unroutable output.
+ */
+export function assertValidVercelFunctionName(functionName: string): void {
+  if (!/^[A-Za-z0-9._-]+$/.test(functionName)) {
+    throw new Error(
+      `[rango] preset "vercel": invalid functionName ${JSON.stringify(
+        functionName,
+      )}. Use letters, digits, ".", "_" or "-" only (it becomes the .func directory and the routing dest).`,
+    );
+  }
+}
+
+/** The `.vc-config.json` body: a Node serverless function with streaming. */
+export function buildVercelVcConfig(
+  vercel: VercelPresetOptions,
+): Record<string, unknown> {
+  const vcConfig: Record<string, unknown> = {
+    runtime: vercel.runtime ?? "nodejs22.x",
+    handler: "index.mjs",
+    launcherType: "Nodejs",
+    shouldAddHelpers: false,
+    supportsResponseStreaming: true,
+    maxDuration: vercel.maxDuration ?? 30,
+  };
+  if (vercel.memory != null) vcConfig.memory = vercel.memory;
+  if (vercel.regions != null) vcConfig.regions = vercel.regions;
+  return vcConfig;
+}
+
+/**
+ * The Build Output API v3 `config.json` body. Routes, in order: long-cache the
+ * content-hashed assets under `${assetsDir}/` (safe to serve `immutable`;
+ * without this Vercel serves them `max-age=0, must-revalidate` and browsers
+ * re-request every asset on each visit), then the filesystem handler, then
+ * everything to the function. The header route uses `continue: true` so it falls
+ * through to the filesystem handler that actually serves the file.
+ *
+ * Route `src` values are REGEXES on Vercel, so the prefix is regex-escaped
+ * (an unescaped `assetsDir: "static.v2"` would immutable-stamp any
+ * `/static?v2/...` path, including function-rendered pages). An empty
+ * assetsDir (assets at the outDir root) gets no header route at all: there is
+ * no prefix separating hashed from non-hashed files, so fall back to Vercel's
+ * safe default headers. Two accepted edges, matching what other framework
+ * adapters (Astro, SvelteKit) emit: files a user places in
+ * `public/${assetsDir}/` land under the same prefix and are also stamped
+ * immutable (assemble() warns about the collision), and a request for a
+ * MISSING asset falls through to the function whose 404 carries the header.
+ */
+export function buildVercelOutputConfig(
+  functionName: string,
+  assetsDir: string,
+): { version: number; routes: unknown[] } {
+  const assetsPrefix = assetsDir.replace(/^\/+|\/+$/g, "");
+  const assetHeaderRoute = assetsPrefix
+    ? [
+        {
+          src: `/${escapeRegExp(assetsPrefix)}/(.*)`,
+          headers: { "cache-control": "public, max-age=31536000, immutable" },
+          continue: true,
+        },
+      ]
+    : [];
+  return {
+    version: 3,
+    routes: [
+      ...assetHeaderRoute,
+      { handle: "filesystem" },
+      { src: "/(.*)", dest: `/${functionName}` },
+    ],
+  };
+}
+
 async function assemble(
   root: string,
   options: RangoVercelOptions,
+  assetsDir: string,
+  publicDir: string,
 ): Promise<void> {
   const vercel = options.vercel ?? {};
   // Validate config before touching the build output.
   assertVercelNodeRuntime(vercel.runtime);
 
+  // Files in public/<assetsDir>/ are copied into the same output prefix as the
+  // content-hashed build assets, so the immutable cache-control route stamps
+  // them too -- replacing such a file after a deploy never reaches returning
+  // visitors. Warn instead of silently pinning.
+  const assetsPrefix = assetsDir.replace(/^\/+|\/+$/g, "");
+  if (publicDir && assetsPrefix && existsSync(join(publicDir, assetsPrefix))) {
+    console.warn(
+      `[rango] preset "vercel": ${join(publicDir, assetsPrefix)} exists. ` +
+        `Files under public/${assetsPrefix}/ share the /${assetsPrefix}/ URL prefix ` +
+        `with hashed build assets and will be served with a one-year immutable ` +
+        `cache-control header. Move un-hashed public files out of "${assetsPrefix}/".`,
+    );
+  }
+
   const dist = join(root, "dist");
   for (const dir of ["client", "rsc", "ssr"]) {
     if (!existsSync(join(dist, dir))) {
@@ -117,6 +213,7 @@ async function assemble(
     }
   }
   const functionName = vercel.functionName ?? "index";
+  assertValidVercelFunctionName(functionName);
   const out = join(root, ".vercel", "output");
   const funcDir = join(out, "functions", `${functionName}.func`);
 
@@ -235,35 +332,16 @@ async function assemble(
   );
 
   // 4. Function config: Node serverless with response streaming.
-  const vcConfig: Record<string, unknown> = {
-    runtime: vercel.runtime ?? "nodejs22.x",
-    handler: "index.mjs",
-    launcherType: "Nodejs",
-    shouldAddHelpers: false,
-    supportsResponseStreaming: true,
-    maxDuration: vercel.maxDuration ?? 30,
-  };
-  if (vercel.memory != null) vcConfig.memory = vercel.memory;
-  if (vercel.regions != null) vcConfig.regions = vercel.regions;
   await writeFile(
     join(funcDir, ".vc-config.json"),
-    JSON.stringify(vcConfig, null, 2) + "\n",
+    JSON.stringify(buildVercelVcConfig(vercel), null, 2) + "\n",
   );
 
-  // 5. Routing: filesystem (static/) first, then everything to the function.
+  // 5. Routing config (immutable assets -> filesystem -> function).
   await writeFile(
     join(out, "config.json"),
-    JSON.stringify(
-      {
-        version: 3,
-        routes: [
-          { handle: "filesystem" },
-          { src: "/(.*)", dest: `/${functionName}` },
-        ],
-      },
-      null,
-      2,
-    ) + "\n",
+    JSON.stringify(buildVercelOutputConfig(functionName, assetsDir), null, 2) +
+      "\n",
   );
 
   console.log(
@@ -274,11 +352,22 @@ async function assemble(
 export function createVercelOutputPlugin(options: RangoVercelOptions): Plugin {
   let root = process.cwd();
   let isBuild = false;
+  // The client build's assetsDir (Vite default "assets"); used to scope the
+  // immutable cache-control route to the content-hashed asset output.
+  let assetsDir = "assets";
+  // Resolved publicDir ("" when disabled); used to warn when public/<assetsDir>
+  // exists, since its un-hashed files share the immutable-header prefix.
+  let publicDir = "";
   return {
     name: "@rangojs/router:vercel-output",
     configResolved(config) {
       root = resolve(config.root);
       isBuild = config.command === "build";
+      assetsDir =
+        config.environments?.client?.build?.assetsDir ??
+        config.build?.assetsDir ??
+        "assets";
+      publicDir = config.publicDir || "";
     },
     // buildApp runs once after the whole multi-environment build (rsc, client,
     // ssr), so dist/ is complete here. closeBundle is unusable for this: it
@@ -288,7 +377,7 @@ export function createVercelOutputPlugin(options: RangoVercelOptions): Plugin {
       order: "post",
       async handler() {
         if (!isBuild) return;
-        await assemble(root, options);
+        await assemble(root, options, assetsDir, publicDir);
       },
     },
   };

package/src/vite/plugins/version-injector.ts

@@ -2,12 +2,25 @@ import type { Plugin } from "vite";
 import { resolve } from "node:path";
 import * as Vite from "vite";
 import { resolveRscEntryFromConfig } from "../utils/shared-utils.js";
+import { RSC_ENTRY_BOOTSTRAP_IMPORTS } from "./virtual-entries.js";
 
 /**
- * Plugin that auto-injects VERSION and routes-manifest into custom entry.rsc files.
- * If a custom entry.rsc file uses createRSCHandler but doesn't pass version,
- * this transform adds the import and property automatically.
- * Also ensures the routes-manifest virtual module is always imported.
+ * Plugin that auto-injects VERSION, routes-manifest, and loader-manifest into
+ * custom entry.rsc files. If a custom entry.rsc file uses createRSCHandler but
+ * doesn't pass version, this transform adds the import and property
+ * automatically. It also ensures the routes-manifest and loader-manifest
+ * virtual modules are always imported.
+ *
+ * The loader-manifest import is what makes fetchable loaders resolvable on a
+ * custom worker entry. The virtual RSC entry (getVirtualEntryRSC) imports the
+ * loader manifest itself, but a hand-written entry (e.g. a Cloudflare
+ * worker.rsc.tsx) does not — so without this injection, setLoaderImports() is
+ * never bundled, lazyLoaderImports stays null at runtime, and a fetchable
+ * loader that is never imported by the server graph (not registered via
+ * loader(), reachable only through a client component) cannot be found by the
+ * _rsc_loader endpoint in production. Dev still works because it resolves
+ * loaders by parsing their id into a file path; only production relied on the
+ * manifest, hence the production-only failure this fixes.
  * @internal
  */
 export function createVersionInjectorPlugin(
@@ -36,9 +49,11 @@ export function createVersionInjectorPlugin(
         return null;
       }
 
-      const prepend: string[] = [
-        `import "virtual:rsc-router/routes-manifest";`,
-      ];
+      // Same startup bootstrap imports the generated virtual RSC entry uses,
+      // from the single shared list so the two paths cannot drift.
+      const prepend: string[] = RSC_ENTRY_BOOTSTRAP_IMPORTS.map(
+        (id) => `import "${id}";`,
+      );
 
       let newCode = code;
       const needsVersion =

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

@@ -38,9 +38,14 @@ initializeApp().catch(console.error);
 
 export const VIRTUAL_ENTRY_SSR: string = `
 import { createFromReadableStream } from "@rangojs/router/internal/deps/ssr";
-import { renderToReadableStream } from "react-dom/server.edge";
+import { renderToReadableStream, resume } from "react-dom/server.edge";
+import { prerender } from "react-dom/static.edge";
 import { injectRSCPayload } from "@rangojs/router/internal/deps/html-stream-server";
-import { createSSRHandler } from "@rangojs/router/ssr";
+import {
+  createSSRHandler,
+  createShellCaptureHandler,
+  createShellResumeHandler,
+} from "@rangojs/router/ssr";
 
 export const renderHTML = createSSRHandler({
   createFromReadableStream,
@@ -49,9 +54,54 @@ export const renderHTML = createSSRHandler({
   loadBootstrapScriptContent: () =>
     import.meta.viteRsc.loadBootstrapScriptContent("index"),
 });
+
+export const captureShellHTML = createShellCaptureHandler({
+  createFromReadableStream,
+  renderToReadableStream,
+  injectRSCPayload,
+  prerender,
+  resume,
+  loadBootstrapScriptContent: () =>
+    import.meta.viteRsc.loadBootstrapScriptContent("index"),
+});
+
+export const resumeShellHTML = createShellResumeHandler({
+  createFromReadableStream,
+  renderToReadableStream,
+  injectRSCPayload,
+  prerender,
+  resume,
+  loadBootstrapScriptContent: () =>
+    import.meta.viteRsc.loadBootstrapScriptContent("index"),
+});
 `.trim();
 
+/**
+ * Virtual modules an RSC entry must import at startup to register the data the
+ * request handler needs before the first request arrives:
+ *
+ * - routes-manifest: the pre-generated route map so href()/matching work on a
+ *   cold start (full map in build, in-memory no-op in dev).
+ * - loader-manifest: setLoaderImports() for fetchable loaders. Critical for
+ *   serverless/multi-process deployments and for fetchable loaders reachable
+ *   only through a client component — without it those loaders are never
+ *   registered for the _rsc_loader endpoint and fail in production.
+ *
+ * Single source of truth: both the generated virtual RSC entry below and the
+ * custom-entry injector (version-injector) consume this list, so a new
+ * bootstrap manifest cannot be added to one path and forgotten on the other.
+ * That exact drift (loader-manifest present here but missing from the injector)
+ * is what left fetchable loaders unresolved on custom worker entries.
+ */
+export const RSC_ENTRY_BOOTSTRAP_IMPORTS: readonly string[] = [
+  "virtual:rsc-router/routes-manifest",
+  "virtual:rsc-router/loader-manifest",
+];
+
 export function getVirtualEntryRSC(routerPath: string): string {
+  const bootstrapImports = RSC_ENTRY_BOOTSTRAP_IMPORTS.map(
+    (id) => `import "${id}";`,
+  ).join("\n");
   return `
 import {
   renderToReadableStream,
@@ -65,15 +115,9 @@ import { router } from "${routerPath}";
 import { createRSCHandler } from "@rangojs/router/internal/rsc-handler";
 import { VERSION } from "@rangojs/router:version";
 
-// Import loader manifest to ensure all fetchable loaders are registered at startup
-// This is critical for serverless/multi-process deployments where the loader module
-// might not be imported before a GET request arrives
-import "virtual:rsc-router/loader-manifest";
-
-// Import pre-generated route manifest so href() works immediately on cold start.
-// In build mode, this contains the full route map generated at build time.
-// In dev mode, this is a no-op (manifest is populated in-memory by the discovery plugin).
-import "virtual:rsc-router/routes-manifest";
+// Startup bootstrap imports (routes + loader manifests). See
+// RSC_ENTRY_BOOTSTRAP_IMPORTS — the same list the custom-entry injector uses.
+${bootstrapImports}
 
 // Lazily create the handler on first request so that ESM live bindings
 // have resolved by the time we read \`router\`. During HMR the module may
@@ -109,7 +153,7 @@ export default function handler(request, env) {
 export function getVirtualEntryRSCHost(hostEntryPath: string): string {
   return `
 import * as __hostEntry from "${hostEntryPath}";
-import { NoRouteMatchError } from "@rangojs/router/host";
+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
@@ -119,11 +163,12 @@ 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 here.
+// \`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 at build time.
+// 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) => {
@@ -138,13 +183,14 @@ const __resolveHostRouter = (m) => {
   }
   return undefined;
 };
-const 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."
-  );
-}
+// 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.
@@ -152,10 +198,22 @@ if (!hostRouter) {
 // 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);
+    return await _hostRouter.match(request, input);
   } catch (err) {
-    if (err instanceof NoRouteMatchError) {
+    // 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;

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 {
@@ -23,6 +23,7 @@ import { createVersionPlugin } from "./plugins/version-plugin.js";
 import {
   sharedRolldownOptions,
   createVirtualEntriesPlugin,
+  normalizeHostRouterEntry,
   onwarn,
   getManualChunks,
 } from "./utils/shared-utils.js";
@@ -266,7 +267,11 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
 
         // 1. Explicit host entry wins: serve the createHostRouter() instance.
         if (explicitHostRouter) {
-          routerRef.path = explicitHostRouter.replaceAll("\\", "/");
+          routerRef.path = normalizeHostRouterEntry(
+            explicitHostRouter,
+            root,
+            existsSync,
+          );
           routerRef.kind = "host";
           return;
         }
@@ -279,7 +284,16 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
         // hostRouter.match()).
         const hostCandidates = findHostRouterFiles(root);
         if (hostCandidates.length === 1) {
-          routerRef.path = toRootRelative(hostCandidates[0]);
+          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;
         }
@@ -335,21 +349,17 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
         // 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"
+          preset === "vercel" && configEnv.command === "build"
             ? { resolve: { noExternal: true as const } }
             : undefined;
-        // Dev only: @vercel/functions is a CJS package (consumed at its root for
-        // getCache/waitUntil) whose nested internal requires vite's RSC + SSR dev
-        // module runners cannot load directly, so a vercel app using
-        // VercelCacheStore crashes on `vite dev`. Pre-bundle it for the server
-        // environments (the production build bundles it via noExternal above, so
-        // this is serve-only). The preset already requires @vercel/functions at
-        // build time, so the unconditional include matches the existing contract.
-        const vercelServerInclude =
-          preset === "vercel" && configEnv.command === "serve"
-            ? ["@vercel/functions"]
-            : [];
         return {
           ...(vercelDefine ? { define: vercelDefine } : {}),
           optimizeDeps: {
@@ -407,7 +417,6 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
                   nested(
                     "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge",
                   ),
-                  ...vercelServerInclude,
                 ],
                 exclude: excludeDeps,
                 rolldownOptions: sharedRolldownOptions,
@@ -424,7 +433,6 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
                   nested(
                     "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge",
                   ),
-                  ...vercelServerInclude,
                 ],
                 // Vite 8 does not propagate the top-level optimizeDeps.exclude
                 // (set in config()) to non-client envs, so the rsc env must set
@@ -532,8 +540,10 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
   );
 
   // Vercel preset: assemble .vercel/output from dist/ after the build. Pushed
-  // last so its (ssr-gated) closeBundle runs after the discovery plugin's
-  // rsc-env postprocess and after every environment has been written.
+  // 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),