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

package/skills/vercel/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: vercel
+description: Deploy a Rango app to Vercel Functions (Build Output API v3)
+argument-hint:
+---
+
+# Vercel deployment
+
+The `vercel` preset builds like the `node` preset (Vercel runs Node Functions, not Workers): rango owns the RSC entry, folds `process.env.NODE_ENV` for the SSR/RSC build, and after `vite build` assembles a `.vercel/output` directory (Build Output API v3) from `dist/` — a single streaming Node Function plus the static client assets.
+
+## Setup
+
+```bash
+npm install @vercel/functions
+```
+
+```typescript
+// vite.config.ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { rango } from "@rangojs/router/vite";
+
+export default defineConfig({
+  plugins: [react(), rango({ preset: "vercel" })],
+});
+```
+
+`@vercel/functions` is required: it backs the generated function launcher (`waitUntil`) and `VercelCacheStore`. The build fails with a clear error if it is missing.
+
+`vite build` produces `.vercel/output`; deploy with the Vercel CLI (`vercel deploy --prebuilt`) or via Git integration.
+
+## Function configuration
+
+Per-function knobs go under `vercel` and are written into `.vc-config.json`:
+
+```typescript
+rango({
+  preset: "vercel",
+  vercel: {
+    runtime: "nodejs22.x", // default
+    maxDuration: 30, // seconds, default
+    memory: 1024, // MB (platform default when omitted)
+    regions: ["fra1"], // pin regions (platform default when omitted)
+    functionName: "index", // the <name>.func dir + config.json route
+  },
+});
+```
+
+## Runtime Cache
+
+`VercelCacheStore` wraps the Vercel Runtime Cache. Locally (no `process.env.VERCEL`) fall back to an in-memory store so dev/preview work without the platform:
+
+```typescript
+import {
+  MemorySegmentCacheStore,
+  VercelCacheStore,
+} from "@rangojs/router/cache";
+import { getCache, waitUntil } from "@vercel/functions";
+
+const defaults = { ttl: 60, swr: 300 };
+const memoryStore = new MemorySegmentCacheStore({ defaults });
+
+function resolveCache() {
+  if (process.env.VERCEL) {
+    return {
+      store: new VercelCacheStore({
+        cache: getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID }),
+        waitUntil,
+        defaults,
+      }),
+    };
+  }
+  return { store: memoryStore };
+}
+
+export const router = createRouter({ cache: resolveCache }).routes(/* ... */);
+```
+
+The cache factory receives `(env, ctx)`; on Vercel `env` is `process.env` and `ctx` is `{ waitUntil }`.
+
+## Host routers (multi-app)
+
+A multi-app host router deploys as a **single function** running `hostRouter.match()` for every request (mirrors the Cloudflare single-worker model). Two requirements:
+
+1. The host module exports the `HostRouter` **instance** (default export, or a named `hostRouter`/`router` export) — not a Cloudflare-style `{ fetch }` object, because rango owns the entry and calls `match()` for you.
+2. Point at the host entry (a host app has several `createRouter()` sub-apps, so auto-discovery can't pick one). rango auto-detects a lone `createHostRouter()` file; set `hostRouter` to be explicit:
+
+```typescript
+rango({ preset: "vercel", hostRouter: "./src/worker.rsc.tsx" });
+```
+
+```typescript
+// src/worker.rsc.tsx
+import { createHostRouter } from "@rangojs/router/host";
+
+export const hostRouter = createHostRouter();
+hostRouter.host(["admin.*"]).lazy(() => import("./apps/admin/handler.js"));
+hostRouter.host(["."]).lazy(() => import("./apps/site/handler.js"));
+
+export default hostRouter; // the instance
+```
+
+`{ env, ctx }` is threaded unchanged from the function to each matched sub-app's handler and its `cache(env, ctx)` factory. See the `host-router` skill for sub-app structure and routing patterns.
+
+## Tracing (custom spans)
+
+Vercel exposes tracing through OpenTelemetry. `createVercelTracing()` (from `@rangojs/router/vercel`) emits the router's `rango.*` phase spans onto the global OTel tracer that `@vercel/otel`'s `registerOTel()` installs:
+
+```typescript
+// instrumentation.ts — install the provider, then export the tracing config so
+// importing this module is what runs registerOTel(). A Rango/Vite app does NOT
+// auto-load `instrumentation.ts` like Next.js does, so a standalone
+// registerOTel() that nothing imports is a silent no-op.
+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 { tracing } from "./instrumentation.js";
+export const router = createRouter({ tracing }).routes(/* ... */);
+```
+
+`createVercelTracing(opts?)` takes `{ enabled, spans, tracerName, tracer }` — same phase set as `createCloudflareTracing` (`rango.request/middleware/action/loader/render/ssr`). Caveats: Node-runtime only (Vercel custom spans are unsupported on Edge); `registerOTel()` must run before the first request; `@vercel/otel` is what unlocks Vercel Session Tracing + Trace Drains. The deploy bundles `@vercel/otel` and its `@opentelemetry/*` peers into the function (no `node_modules` at runtime), so they must be installed. See `examples/vercel-basic` for a worked hybrid setup and the `observability` skill for the cross-platform tracing model.
+
+## Local validation without deploying
+
+`vite preview` serves the static client assets only. To preview the RSC **function**, serve the assembled `.vercel/output` behind filesystem-then-function routing — `examples/vercel-basic/scripts/preview.mjs` does this (and `pnpm preview:vercel` runs it). For a faithful deploy test (isolated filesystem, ESM, self-contained bundle), `examples/vercel-basic/scripts/smoke.mjs` serves it from a temp dir outside the repo. Both share `scripts/serve-vercel-output.mjs`.

package/src/build/generate-route-types.ts

@@ -33,6 +33,7 @@ export {
   findNestedRouterConflict,
   formatNestedRouterConflictError,
   findRouterFiles,
+  findHostRouterFiles,
   writeCombinedRouteTypes,
   genFileTsPath,
   resolveSearchSchemas,

package/src/build/route-types/router-processing.ts

@@ -54,8 +54,33 @@ function isRoutableSourceFile(name: string): boolean {
   );
 }
 
-function findRouterFilesRecursive(
+function isExcludedScanDir(name: string): boolean {
+  return (
+    name === "node_modules" ||
+    name === "dist" ||
+    name === "coverage" ||
+    name === "__tests__" ||
+    name === "__mocks__" ||
+    name.startsWith(".")
+  );
+}
+
+/**
+ * Recursively collect source files whose code contains `pattern` (a comment- or
+ * string-only mention is ignored via firstCodeMatchIndex). Shared by createRouter
+ * and createHostRouter discovery, which differ only in the call pattern and
+ * `stopAtMatchDir`: createRouter treats a directory containing a match as a router
+ * root and stops descending it; createHostRouter descends the whole tree (the host
+ * entry sits above the sub-app router roots).
+ *
+ * `pattern` is the non-global tester (no lastIndex state); `patternG` is its global
+ * twin for the code-region scan.
+ */
+function findCallSiteFilesRecursive(
   dir: string,
+  pattern: RegExp,
+  patternG: RegExp,
+  stopAtMatchDir: boolean,
   filter: ScanFilter | undefined,
   results: string[],
 ): void {
@@ -70,21 +95,12 @@ function findRouterFilesRecursive(
   }
 
   const childDirs: string[] = [];
-  const routerFilesInDir: string[] = [];
+  const matchesInDir: string[] = [];
 
   for (const entry of entries) {
     const fullPath = join(dir, entry.name);
     if (entry.isDirectory()) {
-      if (
-        entry.name === "node_modules" ||
-        entry.name === "dist" ||
-        entry.name === "coverage" ||
-        entry.name === "__tests__" ||
-        entry.name === "__mocks__" ||
-        entry.name.startsWith(".")
-      )
-        continue;
-      childDirs.push(fullPath);
+      if (!isExcludedScanDir(entry.name)) childDirs.push(fullPath);
       continue;
     }
 
@@ -100,26 +116,29 @@ function findRouterFilesRecursive(
       // so a mention inside a comment or string is not mistaken for a real
       // router file (which previously triggered a spurious "Multiple routers
       // found" error).
-      if (
-        ROUTER_CALL_PATTERN.test(source) &&
-        firstCodeMatchIndex(source, ROUTER_CALL_PATTERN_G) >= 0
-      ) {
-        routerFilesInDir.push(fullPath);
+      if (pattern.test(source) && firstCodeMatchIndex(source, patternG) >= 0) {
+        matchesInDir.push(fullPath);
       }
     } catch {
       continue;
     }
   }
 
-  // A directory that contains a router file is treated as a router root.
-  // Once found, deeper directories are skipped to avoid redundant scans.
-  if (routerFilesInDir.length > 0) {
-    results.push(...routerFilesInDir);
-    return;
-  }
-
-  for (const childDir of childDirs) {
-    findRouterFilesRecursive(childDir, filter, results);
+  results.push(...matchesInDir);
+
+  // createRouter (stopAtMatchDir): a directory that contains a match is a router
+  // root, so deeper directories are skipped. createHostRouter: always descend.
+  if (!stopAtMatchDir || matchesInDir.length === 0) {
+    for (const childDir of childDirs) {
+      findCallSiteFilesRecursive(
+        childDir,
+        pattern,
+        patternG,
+        stopAtMatchDir,
+        filter,
+        results,
+      );
+    }
   }
 }
 
@@ -552,7 +571,38 @@ export function detectUnresolvableIncludesForUrlsFile(
  */
 export function findRouterFiles(root: string, filter?: ScanFilter): string[] {
   const result: string[] = [];
-  findRouterFilesRecursive(root, filter, result);
+  findCallSiteFilesRecursive(
+    root,
+    ROUTER_CALL_PATTERN,
+    ROUTER_CALL_PATTERN_G,
+    true,
+    filter,
+    result,
+  );
+  return result;
+}
+
+const HOST_ROUTER_CALL_PATTERN = /\bcreateHostRouter\s*[<(]/;
+const HOST_ROUTER_CALL_PATTERN_G = /\bcreateHostRouter\s*[<(]/g;
+
+/**
+ * Scan for files containing createHostRouter() and return their paths. Unlike
+ * findRouterFiles, this does NOT stop at the first router-root directory -- a host
+ * entry typically sits above the sub-app router roots, so the whole tree is scanned.
+ */
+export function findHostRouterFiles(
+  root: string,
+  filter?: ScanFilter,
+): string[] {
+  const result: string[] = [];
+  findCallSiteFilesRecursive(
+    root,
+    HOST_ROUTER_CALL_PATTERN,
+    HOST_ROUTER_CALL_PATTERN_G,
+    false,
+    filter,
+    result,
+  );
   return result;
 }
 

package/src/cache/index.ts

@@ -24,6 +24,18 @@ export {
   KV_READ_TIMEOUT_MS,
 } from "./cf/index.js";
 
+export {
+  VercelCacheStore,
+  type VercelCacheStoreOptions,
+  type VercelRuntimeCache,
+  type VercelCacheDebug,
+  type VercelCacheReadDebugEvent,
+  type VercelCacheReadOutcome,
+  VERCEL_MAX_ITEM_BYTES,
+  VERCEL_MAX_TAGS_PER_ITEM,
+  VERCEL_MAX_TAG_BYTES,
+} from "./vercel/index.js";
+
 export { CacheScope, createCacheScope } from "./cache-scope.js";
 
 export {

package/src/cache/vercel/index.ts

@@ -0,0 +1,11 @@
+export {
+  VercelCacheStore,
+  type VercelCacheStoreOptions,
+  type VercelRuntimeCache,
+  type VercelCacheDebug,
+  type VercelCacheReadDebugEvent,
+  type VercelCacheReadOutcome,
+  VERCEL_MAX_ITEM_BYTES,
+  VERCEL_MAX_TAGS_PER_ITEM,
+  VERCEL_MAX_TAG_BYTES,
+} from "./vercel-cache-store.js";