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

package/src/host/errors.ts

@@ -64,6 +64,21 @@ export class NoRouteMatchError extends HostRouterError {
   }
 }
 
+/**
+ * True when `err` is a NoRouteMatchError — including one thrown by a
+ * DUPLICATED @rangojs/router copy in the module graph (a workspace pinning a
+ * second version), whose class identity differs so a bare `instanceof` misses
+ * it and an unmatched-host 404 becomes an opaque 500. Use this in worker
+ * catch blocks instead of `instanceof`; it also matches by the stable `name`
+ * the constructor stamps.
+ */
+export function isNoRouteMatchError(err: unknown): err is NoRouteMatchError {
+  return (
+    err instanceof NoRouteMatchError ||
+    (err instanceof Error && err.name === "NoRouteMatchError")
+  );
+}
+
 export class InvalidHandlerError extends HostRouterError {
   constructor(handler: unknown, options?: ErrorOptions) {
     super(`Invalid handler type: ${typeof handler}`, options);

package/src/host/index.ts

@@ -42,6 +42,7 @@ export {
   InvalidHostnameError,
   HostValidationError,
   NoRouteMatchError,
+  isNoRouteMatchError,
   InvalidHandlerError,
 } from "./errors.js";
 

package/src/vercel/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Vercel preset integration surface for @rangojs/router.
+ *
+ * Imported via `@rangojs/router/vercel`. Vercel-only helpers live here so
+ * Node/other-platform consumers never pull them in. The Vercel cache store
+ * (`VercelCacheStore`) is exported from `@rangojs/router/cache`, mirroring the
+ * Cloudflare split where the store lives in `/cache` and the tracing helper in
+ * the platform subpath.
+ */
+
+export { createVercelTracing, type VercelTracingOptions } from "./tracing.js";

package/src/vercel/tracing.ts

@@ -0,0 +1,88 @@
+/**
+ * Vercel OpenTelemetry tracing integration.
+ *
+ * Bridges the router's performance phases (request, middleware, action,
+ * loaders, handler, render, ssr) onto OpenTelemetry spans so they show up in
+ * Vercel's trace waterfall next to the platform's automatic spans, with correct
+ * nesting. Vercel exposes tracing through OpenTelemetry (not a native import-free
+ * API like Cloudflare), so this is a thin convenience over `createOTelTracing`:
+ * it reads the global OTel tracer that `@vercel/otel`'s `registerOTel()` installs.
+ *
+ * Usage (vercel preset). A Rango/Vite app does NOT auto-load `instrumentation.ts`
+ * the way Next.js does, so export the tracing config from there and import it —
+ * the import is what runs `registerOTel()`. A standalone `registerOTel()` that
+ * nothing imports is a silent no-op (the tracer never registers, spans drop):
+ *
+ *   // instrumentation.ts
+ *   import { registerOTel } from "@vercel/otel";
+ *   import { createVercelTracing } from "@rangojs/router/vercel";
+ *   registerOTel({ serviceName: "my-app" });
+ *   export const tracing = createVercelTracing();
+ *
+ *   // router.tsx — importing `tracing` runs instrumentation.ts (and registerOTel)
+ *   import { createRouter } from "@rangojs/router";
+ *   import { tracing } from "./instrumentation.js";
+ *   export const router = createRouter({ tracing });
+ *
+ * Two runtime caveats inherited from the platform:
+ *   - Node.js runtime only. Vercel custom spans are unsupported on the Edge
+ *     runtime; `startActiveSpan` also needs an AsyncLocalStorage context manager
+ *     (which @vercel/otel configures on Node) for spans to nest correctly.
+ *   - `registerOTel()` must run before the first request. Reading the tracer via
+ *     `trace.getTracer` here is safe even if it runs first — the API's proxy
+ *     tracer delegates to the provider once registered — but no provider means
+ *     every span is a no-op (the request behaves exactly as if tracing were off).
+ *
+ * Whether spans are actually exported is governed by your OTel setup / Vercel
+ * tracing destination, not by this adapter.
+ */
+
+import { trace } from "@opentelemetry/api";
+import {
+  createOTelTracing,
+  type OTelActiveSpanTracer,
+} from "../router/telemetry-otel.js";
+import type {
+  RouterTracingConfig,
+  TracePhaseToggles,
+} from "../router/tracing.js";
+
+/** Options for createVercelTracing. */
+export interface VercelTracingOptions {
+  /** Master switch. Defaults to true. */
+  enabled?: boolean;
+  /** Per-phase span toggles. Omitted phases default to enabled. */
+  spans?: TracePhaseToggles;
+  /**
+   * OTel instrumentation-scope name passed to `trace.getTracer()`. Defaults to
+   * `"rango"`. Ignored when `tracer` is provided.
+   */
+  tracerName?: string;
+  /**
+   * Explicit tracer override. Defaults to the global OTel tracer
+   * (`trace.getTracer(tracerName)`) — the provider `@vercel/otel`'s
+   * `registerOTel()` installs. Pass this to bridge onto a tracer you own.
+   */
+  tracer?: OTelActiveSpanTracer;
+}
+
+/**
+ * Create the tracing config for a Vercel router. Pass the result to
+ * `createRouter({ tracing })`. Spans are emitted for the request, middleware,
+ * action, loaders, handler, render, and ssr phases; pass `spans` to turn
+ * individual phases off.
+ *
+ * @see createOTelTracing (`@rangojs/router`) for the underlying adapter on any
+ *   platform with an OpenTelemetry SDK.
+ * @see createCloudflareTracing (`@rangojs/router/cloudflare`) for the same slot
+ *   using Cloudflare Workers native custom spans.
+ */
+export function createVercelTracing(
+  options: VercelTracingOptions = {},
+): RouterTracingConfig {
+  const { tracerName = "rango", tracer, enabled, spans } = options;
+  return createOTelTracing(tracer ?? trace.getTracer(tracerName), {
+    enabled,
+    spans,
+  });
+}

package/src/vite/discovery/state.ts

@@ -19,7 +19,7 @@ export interface PluginOptions {
   /** Build-time env option from rango() config. */
   buildEnv?: import("../plugin-types.js").BuildEnvOption;
   /** Deployment preset (needed for buildEnv "auto" resolution). */
-  preset?: "node" | "cloudflare";
+  preset?: "node" | "cloudflare" | "vercel";
   /**
    * Route-discovery scan filter (glob include/exclude) from rango() config.
    * Compiled into `DiscoveryState.scanFilter` once `projectRoot` is known.

package/src/vite/index.ts

@@ -12,6 +12,8 @@ export { poke } from "./plugins/refresh-cmd.js";
 export type {
   RangoNodeOptions,
   RangoCloudflareOptions,
+  RangoVercelOptions,
+  VercelPresetOptions,
   RangoOptions,
   ClientChunks,
   ClientChunkMeta,

package/src/vite/plugin-types.ts

@@ -12,7 +12,7 @@ export interface BuildEnvFactoryContext {
   /** Vite command ("serve" for dev, "build" for production). */
   command: "serve" | "build";
   /** Router deployment preset. */
-  preset: "node" | "cloudflare";
+  preset: "node" | "cloudflare" | "vercel";
 }
 
 /**
@@ -175,6 +175,20 @@ export interface RangoNodeOptions extends RangoBaseOptions {
    */
   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.
@@ -215,7 +229,75 @@ export interface RangoCloudflareOptions extends RangoBaseOptions {
   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 "nodejs22.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;
+export type RangoOptions =
+  | RangoNodeOptions
+  | RangoCloudflareOptions
+  | RangoVercelOptions;

package/src/vite/plugins/vercel-output.ts

@@ -0,0 +1,384 @@
+/**
+ * Vercel Build Output (Build Output API v3) emitter for `preset: "vercel"`.
+ *
+ * After the full app build, restructures dist/ into .vercel/output:
+ *
+ *   .vercel/output/
+ *     config.json                       routing: static first, else the function
+ *     static/                           dist/client (browser assets, served at /)
+ *     functions/<name>.func/
+ *       .vc-config.json                 Node serverless, response streaming
+ *       index.mjs                       bundled launcher (srvx + @vercel/functions)
+ *       rsc/                            dist/rsc (self-contained RSC server bundle)
+ *       ssr/                            dist/ssr (rsc imports ../ssr/index.js)
+ *
+ * A prebuilt .vercel/output gets no `npm install`, so everything the function
+ * imports must physically live inside the .func directory. This relies on two
+ * things the vercel preset arranges (each is a failure only a real deploy — or
+ * the isolated smoke test — catches, since a local in-place run is masked by the
+ * app's own package.json + node_modules up the tree):
+ *
+ *   1. The rsc/ssr builds are fully bundled (`resolve.noExternal`, set in
+ *      rango.ts for this preset). The node default externalizes node_modules
+ *      deps, which works under `vite preview` but leaves bare imports
+ *      (@vercel/functions, react-dom/server.edge, ...) that have no node_modules
+ *      to resolve against on Vercel.
+ *   2. A `package.json` with `"type": "module"` is written into the .func dir.
+ *      The rsc/ssr bundles are ESM but use a `.js` extension; without a
+ *      type:module in scope the deployed (isolated) function loads them as
+ *      CommonJS and fails on the first `import`.
+ *
+ * The launcher is bundled with srvx (the Web->Node streaming bridge, a
+ * @rangojs/router dependency) and @vercel/functions (resolved from the app)
+ * inlined, keeping the RSC bundle a runtime-relative external.
+ *
+ * Timing: this runs in the `buildApp` hook (order "post"), which fires once
+ * after every environment has built, so dist/{client,rsc,ssr} all exist.
+ * closeBundle is unusable here — it fires per environment, and twice for ssr
+ * (the server-reference scan and the real build), so it would run before
+ * dist/client exists. rango's own prerender/static emitters hardcode dist/rsc,
+ * so we build to dist/ and restructure here rather than retargeting outDir.
+ */
+
+import type { Plugin } from "vite";
+import { rm, mkdir, cp, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+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.
+interface EsbuildPluginBuild {
+  onResolve(
+    options: { filter: RegExp },
+    callback: () => { path: string; external: boolean },
+  ): void;
+}
+type EsbuildBuild = (options: Record<string, unknown>) => Promise<unknown>;
+interface EsbuildModule {
+  build?: EsbuildBuild;
+  default?: { build?: EsbuildBuild };
+}
+
+const LAUNCHER_SOURCE = `import { toNodeHandler } from "srvx/node";
+import { waitUntil } from "@vercel/functions";
+import rscHandler from "./rsc/index.js";
+
+// The Vercel Node launcher invokes a Node (req, res) handler, not a Web fetch
+// handler. srvx's toNodeHandler bridges the Rango Web fetch handler and pipes
+// the streamed Response to the Node response (set supportsResponseStreaming).
+const onVercel = Boolean(process.env.VERCEL);
+
+const fetchHandler = (request) =>
+  rscHandler(request, {
+    env: process.env,
+    // Forward Vercel's waitUntil so cache writes / revalidation run off the
+    // response path. Omitted off-platform so those writes settle inline.
+    ctx: onVercel ? { waitUntil } : undefined,
+  });
+
+export default toNodeHandler(fetchHandler);
+`;
+
+/**
+ * Reject a non-Node runtime for the vercel preset. The preset only emits a Node
+ * serverless function (launcherType "Nodejs", bundled Node APIs, response
+ * streaming). Vercel's Edge runtime needs a different Build Output primitive
+ * (EdgeFunction, a Web-handler entry, no node_modules) that this assembler does
+ * not produce, so a non-nodejs runtime would emit a config the platform rejects
+ * or mis-runs. Fail fast at build time instead of shipping a broken function.
+ */
+export function assertVercelNodeRuntime(runtime: string | undefined): void {
+  if (runtime != null && !runtime.startsWith("nodejs")) {
+    throw new Error(
+      `[rango] preset "vercel": runtime "${runtime}" is not supported. ` +
+        `This preset emits a Node serverless function; use a "nodejs*" runtime ` +
+        `(default "nodejs22.x"). The Edge runtime is not supported.`,
+    );
+  }
+}
+
+/**
+ * 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))) {
+      throw new Error(
+        `[rango] preset "vercel": missing dist/${dir}. Run the production build first.`,
+      );
+    }
+  }
+  const functionName = vercel.functionName ?? "index";
+  assertValidVercelFunctionName(functionName);
+  const out = join(root, ".vercel", "output");
+  const funcDir = join(out, "functions", `${functionName}.func`);
+
+  await rm(out, { recursive: true, force: true });
+  await mkdir(funcDir, { recursive: true });
+
+  // 1. Static client assets -> served from the CDN at the root.
+  await cp(join(dist, "client"), join(out, "static"), { recursive: true });
+
+  // 2. Server bundle into the function. Preserve the rsc -> ../ssr/index.js
+  //    relative import by mirroring the dist/{rsc,ssr} layout inside the func.
+  await cp(join(dist, "rsc"), join(funcDir, "rsc"), { recursive: true });
+  await cp(join(dist, "ssr"), join(funcDir, "ssr"), { recursive: true });
+
+  // Prerender/static payload manifests (present only when routes are prerendered).
+  if (existsSync(join(dist, "static"))) {
+    await cp(join(dist, "static"), join(funcDir, "static"), {
+      recursive: true,
+    });
+  }
+
+  // 3. Bundle the Node launcher. srvx (a @rangojs/router dependency) is aliased
+  //    to its resolved path; @vercel/functions resolves from the app; the RSC
+  //    server bundle stays a runtime-relative external.
+  const rangoRequire = createRequire(import.meta.url);
+  let srvxNodePath: string;
+  try {
+    srvxNodePath = rangoRequire.resolve("srvx/node");
+  } catch {
+    throw new Error(
+      '[rango] preset "vercel" requires "srvx" (a dependency of @rangojs/router). Reinstall dependencies.',
+    );
+  }
+
+  // esbuild ships with Vite, so we never add it as a @rangojs/router dependency.
+  // It is a DIRECT dependency of Vite but only a TRANSITIVE one from the app's
+  // view, so under strict pnpm it is NOT resolvable from the app root. Resolve it
+  // through Vite's module location (Vite is a direct app dependency, and esbuild
+  // is a direct dependency of Vite). Minimal structural types avoid coupling to
+  // esbuild's type package at compile time.
+  const appRequire = createRequire(join(root, "package.json"));
+  const resolveEsbuildPath = (): string => {
+    try {
+      const viteRequire = createRequire(appRequire.resolve("vite"));
+      return viteRequire.resolve("esbuild");
+    } catch {
+      // Intentionally empty: fall through to the app/rango fallbacks below.
+    }
+    try {
+      return appRequire.resolve("esbuild");
+    } catch {
+      // Intentionally empty: last resort is @rangojs/router's own resolver.
+    }
+    return rangoRequire.resolve("esbuild");
+  };
+  let esbuildModule: EsbuildModule;
+  try {
+    esbuildModule = (await import(
+      pathToFileURL(resolveEsbuildPath()).href
+    )) as EsbuildModule;
+  } catch {
+    throw new Error(
+      '[rango] preset "vercel" requires "esbuild" to bundle the function launcher. It ships with Vite; reinstall dependencies (or add esbuild to your app dependencies).',
+    );
+  }
+  const esbuildBuild = esbuildModule.build ?? esbuildModule.default?.build;
+  if (typeof esbuildBuild !== "function") {
+    throw new Error('[rango] preset "vercel": could not load esbuild.build.');
+  }
+
+  try {
+    await esbuildBuild({
+      stdin: {
+        contents: LAUNCHER_SOURCE,
+        resolveDir: root,
+        sourcefile: "func-entry.mjs",
+        loader: "js",
+      },
+      outfile: join(funcDir, "index.mjs"),
+      bundle: true,
+      format: "esm",
+      platform: "node",
+      target: "node18",
+      alias: { "srvx/node": srvxNodePath },
+      plugins: [
+        {
+          name: "external-rsc-entry",
+          setup(b: EsbuildPluginBuild) {
+            b.onResolve({ filter: /^\.\/rsc\/index\.js$/ }, () => ({
+              path: "./rsc/index.js",
+              external: true,
+            }));
+          },
+        },
+      ],
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/@vercel\/functions/.test(message)) {
+      throw new Error(
+        '[rango] preset "vercel": could not resolve "@vercel/functions". Add it to your app dependencies (it also backs VercelCacheStore).\n' +
+          message,
+      );
+    }
+    throw error;
+  }
+
+  // 3b. Mark the function as ESM. The rsc/ssr bundles are .js ESM files with no
+  //     package.json in scope on the deployed function (it is isolated at
+  //     /var/task), so Node would load them as CommonJS and fail on `import`.
+  //     Locally this is masked because the func inherits the app's
+  //     "type": "module" up the tree; the deployed func has nothing above it.
+  await writeFile(
+    join(funcDir, "package.json"),
+    JSON.stringify({ type: "module" }, null, 2) + "\n",
+  );
+
+  // 4. Function config: Node serverless with response streaming.
+  await writeFile(
+    join(funcDir, ".vc-config.json"),
+    JSON.stringify(buildVercelVcConfig(vercel), null, 2) + "\n",
+  );
+
+  // 5. Routing config (immutable assets -> filesystem -> function).
+  await writeFile(
+    join(out, "config.json"),
+    JSON.stringify(buildVercelOutputConfig(functionName, assetsDir), null, 2) +
+      "\n",
+  );
+
+  console.log(
+    `[rango] assembled .vercel/output (function: ${functionName}.func)`,
+  );
+}
+
+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
+    // fires per environment, and twice for ssr (the server-reference scan and
+    // the real build), so it would run before dist/client exists.
+    buildApp: {
+      order: "post",
+      async handler() {
+        if (!isBuild) return;
+        await assemble(root, options, assetsDir, publicDir);
+      },
+    },
+  };
+}