@rangojs/router 0.0.0-experimental.20 → 0.0.0-experimental.21efdd86

package/AGENTS.md

@@ -3,3 +3,7 @@
 A file-system based React Server Components router.
 
 Run `/rango` to understand the API. Detailed guides for each feature are in the `skills/` directory (e.g. `node_modules/@rangojs/router/skills/loader`, `skills/caching`, `skills/middleware`, etc.).
+
+## Development rules
+
+- Always commit generated files (e.g. `*.gen.ts`) alongside the source changes that produced them.

package/README.md

@@ -45,6 +45,30 @@ For Cloudflare Workers:
 npm install @cloudflare/vite-plugin
 ```
 
+## Import Paths
+
+Use these import paths consistently:
+
+- `@rangojs/router` — server/RSC router APIs, route DSL, `createRouter`, `urls`, `redirect`, `Prerender`, `Static`, shared types
+- `@rangojs/router/client` — hooks and components such as `Link`, `Outlet`, `href`, `useNavigation`, `useLoader`, `useAction`, `useLocationState`
+- `@rangojs/router/cache` — public cache APIs such as `CFCacheStore`, `MemorySegmentCacheStore`, `createDocumentCacheMiddleware`
+- `@rangojs/router/host`, `@rangojs/router/theme`, `@rangojs/router/vite` — specialized public subpaths
+- `@rangojs/router/rsc`, `@rangojs/router/ssr` — advanced server-only integration subpaths for custom request/HTML pipelines
+
+Use only subpaths that are explicitly exported from the package. Avoid deep imports such as `@rangojs/router/cache/cf`.
+
+`@rangojs/router` is conditionally resolved. Server-only root APIs such as
+`createRouter()`, `urls()`, `redirect()`, `Prerender()`, and `cookies()` rely on
+the `react-server` export condition and are meant to run in router definitions,
+handlers, and other RSC/server modules. Outside that environment the root entry
+falls back to stub implementations that throw guidance errors.
+
+If you hit a root-entrypoint stub error:
+
+- hooks and components like `Link`, `Outlet`, `useLoader`, `useNavigation`, and `MetaTags` belong in `@rangojs/router/client`
+- cache APIs like `CFCacheStore` and `createDocumentCacheMiddleware` belong in `@rangojs/router/cache`
+- host-router APIs belong in `@rangojs/router/host`
+
 ## Quick Start
 
 ### Vite Config
@@ -62,26 +86,34 @@ export default defineConfig({
 
 ### Router
 
+This file is a server/RSC module and should import router construction APIs from
+`@rangojs/router`.
+
 ```tsx
 // src/router.tsx
-import { createRouter, urls } from "@rangojs/router";
-import { Document } from "./document";
+import { createRouter } from "@rangojs/router";
 
-const blogPatterns = urls(({ path }) => [
-  path("/", BlogIndexPage, { name: "index" }),
-  path("/:slug", BlogPostPage, { name: "post" }),
+export const router = createRouter().routes(({ path }) => [
+  path("/", HomePage, { name: "home" }),
+  path("/about", AboutPage, { name: "about" }),
 ]);
 
+export const reverse = router.reverse;
+// reverse("home") -> "/"
+```
+
+For larger apps, extract route modules with `urls()` and compose with `include()`:
+
+```tsx
+import { createRouter, urls } from "@rangojs/router";
+import { blogPatterns } from "./urls/blog";
+
 const urlpatterns = urls(({ path, include }) => [
   path("/", HomePage, { name: "home" }),
   include("/blog", blogPatterns, { name: "blog" }),
 ]);
 
-export const router = createRouter({ document: Document }).routes(urlpatterns);
-
-// Export typed reverse function for URL generation by route name
-export const reverse = router.reverse;
-
+export const router = createRouter().routes(urlpatterns);
 // reverse("blog.post", { slug: "hello-world" }) -> "/blog/hello-world"
 ```
 
@@ -248,7 +280,8 @@ All handler typing styles are supported, but they solve different problems:
 Example of a scoped local name inside a mounted module:
 
 ```tsx
-import type { Handler, ScopedRouteMap } from "@rangojs/router";
+import type { Handler } from "@rangojs/router";
+import type { ScopedRouteMap } from "@rangojs/router/__internal";
 
 type BlogRoutes = ScopedRouteMap<"blog">;
 
@@ -488,7 +521,7 @@ function Nav() {
   return (
     <nav>
       <Link to={href("/")}>Home</Link>
-      <Link to={href("/blog")} prefetch="hybrid">
+      <Link to={href("/blog")} prefetch="adaptive">
         Blog
       </Link>
       <Link to={href("/about")}>About</Link>
@@ -683,10 +716,12 @@ export const BlogPost = Prerender(
 
 ### Passthrough for Unknown Params
 
+Wrap a `Prerender` definition with `Passthrough()` to add a live handler for unknown params at runtime. The build handler runs at build time, the live handler runs at request time for params not in the prerender cache.
+
 ```tsx
-import { Prerender } from "@rangojs/router";
+import { Prerender, Passthrough } from "@rangojs/router";
 
-export const ProductPage = Prerender(
+export const ProductPageDef = Prerender(
   async () => {
     const featured = await db.getFeaturedProducts();
     return featured.map((p) => ({ id: p.id }));
@@ -695,16 +730,22 @@ export const ProductPage = Prerender(
     const product = await db.getProduct(ctx.params.id);
     return <Product data={product} />;
   },
-  { passthrough: true },
 );
-```
 
-With `passthrough: true`, known params are served from the build-time cache and unknown params fall through to live rendering.
+// In route definition:
+path(
+  "/products/:id",
+  Passthrough(ProductPageDef, async (ctx) => {
+    const product = await ctx.env.DB.getProduct(ctx.params.id);
+    return <Product data={product} />;
+  }),
+);
+```
 
-Handlers can also skip individual param sets with `ctx.passthrough()`, deferring them to the live handler at runtime:
+Build handlers can also skip individual param sets with `ctx.passthrough()`, deferring them to the live handler:
 
 ```tsx
-export const ProductPage = Prerender(
+export const ProductPageDef = Prerender(
   async () => {
     const all = await db.getAllProducts();
     return all.map((p) => ({ id: p.id }));
@@ -714,10 +755,55 @@ export const ProductPage = Prerender(
     if (!product.published) return ctx.passthrough();
     return <Product data={product} />;
   },
-  { passthrough: true },
 );
 ```
 
+### Build-Time Environment Bindings
+
+Prerender handlers can access platform bindings (KV, D1, R2) at build time when `buildEnv` is configured in the Vite plugin:
+
+```ts
+// vite.config.ts
+import { rango } from "@rangojs/router/vite";
+
+rango({ preset: "cloudflare", buildEnv: "auto" });
+```
+
+With `buildEnv: "auto"`, the plugin calls `wrangler.getPlatformProxy()` to provide local bindings. Handlers then access `ctx.env` during build:
+
+```tsx
+export const BlogPosts = Prerender<{ slug: string }>(
+  async (ctx) => {
+    const rows = await ctx.env.DB.prepare("SELECT slug FROM posts").all();
+    return rows.map((r) => ({ slug: r.slug }));
+  },
+  async (ctx) => {
+    const post = await ctx.env.DB.prepare("SELECT * FROM posts WHERE slug = ?")
+      .bind(ctx.params.slug)
+      .first();
+    return <BlogPost post={post} />;
+  },
+);
+```
+
+`buildEnv` also accepts a factory function or plain object:
+
+```ts
+// Custom factory
+rango({
+  buildEnv: async (ctx) => {
+    const { getPlatformProxy } = await import("wrangler");
+    const proxy = await getPlatformProxy();
+    return { env: proxy.env, dispose: proxy.dispose };
+  },
+});
+
+// Plain object (Node.js)
+rango({ buildEnv: { DATABASE_URL: process.env.DATABASE_URL } });
+```
+
+Build-time env applies to both production builds and dev on-demand prerender. Without `buildEnv`, accessing `ctx.env` in a Prerender handler throws with a clear error.
+
 ## Theme
 
 ### Router Configuration
@@ -842,16 +928,22 @@ module, use `scopedReverse<typeof localPatterns>(ctx.reverse)` or
 
 ## Subpath Exports
 
-| Export                   | Description                                                                       |
-| ------------------------ | --------------------------------------------------------------------------------- |
-| `@rangojs/router`        | Core: `createRouter`, `urls`, `createLoader`, `Handler`, `Prerender`, `Meta`      |
-| `@rangojs/router/client` | Client: `Link`, `Outlet`, `href`, `useNavigation`, `useLoader`, `MetaTags`        |
-| `@rangojs/router/cache`  | Cache: `CFCacheStore`, `MemorySegmentCacheStore`, `createDocumentCacheMiddleware` |
-| `@rangojs/router/theme`  | Theme: `useTheme`, `ThemeProvider`, `ThemeScript`                                 |
-| `@rangojs/router/host`   | Host routing: `createHostRouter`, `defineHosts`                                   |
-| `@rangojs/router/vite`   | Vite plugin: `rango()`                                                            |
-| `@rangojs/router/server` | Server utilities                                                                  |
-| `@rangojs/router/build`  | Build utilities                                                                   |
+| Export                   | Description                                                                                              |
+| ------------------------ | -------------------------------------------------------------------------------------------------------- |
+| `@rangojs/router`        | Server/RSC core and shared types: `createRouter`, `urls`, `createLoader`, `Handler`, `Prerender`, `Meta` |
+| `@rangojs/router/client` | Client: `Link`, `Outlet`, `href`, `useNavigation`, `useLoader`, `MetaTags`                               |
+| `@rangojs/router/cache`  | Cache: `CFCacheStore`, `MemorySegmentCacheStore`, `createDocumentCacheMiddleware`                        |
+| `@rangojs/router/theme`  | Theme: `useTheme`, `ThemeProvider`, `ThemeScript`                                                        |
+| `@rangojs/router/host`   | Host routing: `createHostRouter`, `defineHosts`                                                          |
+| `@rangojs/router/vite`   | Vite plugin: `rango()`                                                                                   |
+| `@rangojs/router/rsc`    | Advanced server pipeline APIs: `createRSCHandler`, request-context access                                |
+| `@rangojs/router/ssr`    | Advanced SSR bridge APIs: `createSSRHandler`                                                             |
+| `@rangojs/router/server` | Internal build/runtime utilities for advanced integrations                                               |
+| `@rangojs/router/build`  | Build utilities                                                                                          |
+
+The root entrypoint is not a generic client/runtime barrel. If you need hooks
+or components, import from `@rangojs/router/client`; if you need cache or host
+APIs, use their dedicated subpaths.
 
 ## Examples
 

package/dist/bin/rango.js

@@ -218,7 +218,8 @@ function findTsFiles(dir, filter) {
   for (const entry of entries) {
     const fullPath = join(dir, entry.name);
     if (entry.isDirectory()) {
-      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      if (entry.name === "node_modules" || entry.name.startsWith(".") || entry.name === "dist" || entry.name === "build" || entry.name === "coverage")
+        continue;
       results.push(...findTsFiles(fullPath, filter));
     } else if ((entry.name.endsWith(".ts") || entry.name.endsWith(".tsx") || entry.name.endsWith(".js") || entry.name.endsWith(".jsx")) && !entry.name.includes(".gen.")) {
       if (filter && !filter(fullPath)) continue;
@@ -450,7 +451,7 @@ function buildRouteMapFromBlock(block, fullSource, filePath, visited, searchSche
   }
   return routeMap;
 }
-function buildCombinedRouteMapWithSearch(filePath, variableName, visited, diagnosticsOut) {
+function buildCombinedRouteMapWithSearch(filePath, variableName, visited, diagnosticsOut, inlineBlock) {
   visited = visited ?? /* @__PURE__ */ new Set();
   const realPath = resolve(filePath);
   const key = variableName ? `${realPath}:${variableName}` : realPath;
@@ -466,7 +467,9 @@ function buildCombinedRouteMapWithSearch(filePath, variableName, visited, diagno
     return { routes: {}, searchSchemas: {} };
   }
   let block;
-  if (variableName) {
+  if (inlineBlock) {
+    block = inlineBlock;
+  } else if (variableName) {
     const extracted = extractUrlsBlockForVariable(source, variableName);
     if (!extracted) return { routes: {}, searchSchemas: {} };
     block = extracted;
@@ -601,7 +604,7 @@ function countPublicRouteEntries(source) {
   return count;
 }
 function isRoutableSourceFile(name) {
-  return (name.endsWith(".ts") || name.endsWith(".tsx") || name.endsWith(".js") || name.endsWith(".jsx")) && !name.includes(".gen.");
+  return (name.endsWith(".ts") || name.endsWith(".tsx") || name.endsWith(".js") || name.endsWith(".jsx")) && !name.includes(".gen.") && !name.includes(".test.") && !name.includes(".spec.");
 }
 function findRouterFilesRecursive(dir, filter, results) {
   let entries;
@@ -618,7 +621,8 @@ function findRouterFilesRecursive(dir, filter, results) {
   for (const entry of entries) {
     const fullPath = join2(dir, entry.name);
     if (entry.isDirectory()) {
-      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      if (entry.name === "node_modules" || entry.name === "dist" || entry.name === "coverage" || entry.name === "__tests__" || entry.name === "__mocks__" || entry.name.startsWith("."))
+        continue;
       childDirs.push(fullPath);
       continue;
     }
@@ -670,7 +674,7 @@ Router root: ${conflict.ancestor}
 Nested router: ${conflict.nested}
 Move the nested router into a sibling directory or configure it as a separate app root.`;
 }
-function extractUrlsVariableFromRouter(code) {
+function extractUrlsFromRouter(code) {
   const sourceFile = ts5.createSourceFile(
     "router.tsx",
     code,
@@ -684,24 +688,70 @@ function extractUrlsVariableFromRouter(code) {
     const callee = node.expression;
     return ts5.isIdentifier(callee) && callee.text === "createRouter";
   }
+  function isInlineBuilder(node) {
+    return ts5.isArrowFunction(node) || ts5.isFunctionExpression(node);
+  }
+  function isRoutesOnCreateRouter(node) {
+    if (!ts5.isPropertyAccessExpression(node.expression) || node.expression.name.text !== "routes")
+      return false;
+    let inner = node.expression.expression;
+    while (ts5.isCallExpression(inner) && ts5.isPropertyAccessExpression(inner.expression)) {
+      inner = inner.expression.expression;
+    }
+    return isCreateRouterCall(inner);
+  }
   function visit(node) {
     if (result) return;
-    if (ts5.isCallExpression(node) && ts5.isPropertyAccessExpression(node.expression) && node.expression.name.text === "routes" && node.arguments.length >= 1 && ts5.isIdentifier(node.arguments[0])) {
-      let inner = node.expression.expression;
-      while (ts5.isCallExpression(inner) && ts5.isPropertyAccessExpression(inner.expression)) {
-        inner = inner.expression.expression;
-      }
-      if (isCreateRouterCall(inner)) {
-        result = node.arguments[0].text;
-        return;
+    if (ts5.isCallExpression(node) && node.arguments.length >= 1 && isRoutesOnCreateRouter(node)) {
+      const arg = node.arguments[0];
+      if (ts5.isIdentifier(arg)) {
+        result = { kind: "variable", name: arg.text };
+      } else if (isInlineBuilder(arg)) {
+        result = { kind: "inline", block: arg.getText(sourceFile) };
       }
+      return;
     }
     if (isCreateRouterCall(node)) {
       const callExpr = node;
-      for (const arg of callExpr.arguments) {
+      for (const callArg of callExpr.arguments) {
+        if (ts5.isObjectLiteralExpression(callArg)) {
+          for (const prop of callArg.properties) {
+            if (ts5.isPropertyAssignment(prop) && ts5.isIdentifier(prop.name) && prop.name.text === "urls") {
+              if (ts5.isIdentifier(prop.initializer)) {
+                result = { kind: "variable", name: prop.initializer.text };
+              } else if (isInlineBuilder(prop.initializer)) {
+                result = {
+                  kind: "inline",
+                  block: prop.initializer.getText(sourceFile)
+                };
+              }
+              return;
+            }
+          }
+        }
+      }
+    }
+    ts5.forEachChild(node, visit);
+  }
+  visit(sourceFile);
+  return result;
+}
+function extractBasenameFromRouter(code) {
+  const sourceFile = ts5.createSourceFile(
+    "router.tsx",
+    code,
+    ts5.ScriptTarget.Latest,
+    true,
+    ts5.ScriptKind.TSX
+  );
+  let result;
+  function visit(node) {
+    if (result !== void 0) return;
+    if (ts5.isCallExpression(node) && ts5.isIdentifier(node.expression) && node.expression.text === "createRouter") {
+      for (const arg of node.arguments) {
         if (ts5.isObjectLiteralExpression(arg)) {
           for (const prop of arg.properties) {
-            if (ts5.isPropertyAssignment(prop) && ts5.isIdentifier(prop.name) && prop.name.text === "urls" && ts5.isIdentifier(prop.initializer)) {
+            if (ts5.isPropertyAssignment(prop) && ts5.isIdentifier(prop.name) && prop.name.text === "basename" && ts5.isStringLiteral(prop.initializer)) {
               result = prop.initializer.text;
               return;
             }
@@ -714,6 +764,19 @@ function extractUrlsVariableFromRouter(code) {
   visit(sourceFile);
   return result;
 }
+function applyBasenameToRoutes(result, basename2) {
+  const prefixed = {};
+  for (const [name, pattern] of Object.entries(result.routes)) {
+    if (pattern === "/") {
+      prefixed[name] = basename2;
+    } else if (basename2.endsWith("/") && pattern.startsWith("/")) {
+      prefixed[name] = basename2 + pattern.slice(1);
+    } else {
+      prefixed[name] = basename2 + pattern;
+    }
+  }
+  return { routes: prefixed, searchSchemas: result.searchSchemas };
+}
 function buildCombinedRouteMapForRouterFile(routerFilePath) {
   let routerSource;
   try {
@@ -721,19 +784,40 @@ function buildCombinedRouteMapForRouterFile(routerFilePath) {
   } catch {
     return { routes: {}, searchSchemas: {} };
   }
-  const urlsVarName = extractUrlsVariableFromRouter(routerSource);
-  if (!urlsVarName) {
+  const extraction = extractUrlsFromRouter(routerSource);
+  if (!extraction) {
     return { routes: {}, searchSchemas: {} };
   }
-  const imported = resolveImportedVariable(routerSource, urlsVarName);
-  if (imported) {
-    const targetFile = resolveImportPath(imported.specifier, routerFilePath);
-    if (!targetFile) {
-      return { routes: {}, searchSchemas: {} };
+  const rawBasename = extractBasenameFromRouter(routerSource);
+  const basename2 = rawBasename ? ("/" + rawBasename.replace(/^\/+|\/+$/g, "")).replace(/^\/$/, "") : void 0;
+  let result;
+  if (extraction.kind === "inline") {
+    result = buildCombinedRouteMapWithSearch(
+      routerFilePath,
+      void 0,
+      void 0,
+      void 0,
+      extraction.block
+    );
+  } else {
+    const imported = resolveImportedVariable(routerSource, extraction.name);
+    if (imported) {
+      const targetFile = resolveImportPath(imported.specifier, routerFilePath);
+      if (!targetFile) {
+        return { routes: {}, searchSchemas: {} };
+      }
+      result = buildCombinedRouteMapWithSearch(
+        targetFile,
+        imported.exportedName
+      );
+    } else {
+      result = buildCombinedRouteMapWithSearch(routerFilePath, extraction.name);
     }
-    return buildCombinedRouteMapWithSearch(targetFile, imported.exportedName);
   }
-  return buildCombinedRouteMapWithSearch(routerFilePath, urlsVarName);
+  if (basename2) {
+    result = applyBasenameToRoutes(result, basename2);
+  }
+  return result;
 }
 function detectUnresolvableIncludes(routerFilePath) {
   const realPath = resolve2(routerFilePath);
@@ -743,9 +827,20 @@ function detectUnresolvableIncludes(routerFilePath) {
   } catch {
     return [];
   }
-  const urlsVarName = extractUrlsVariableFromRouter(source);
-  if (!urlsVarName) return [];
-  const imported = resolveImportedVariable(source, urlsVarName);
+  const extraction = extractUrlsFromRouter(source);
+  if (!extraction) return [];
+  const diagnostics = [];
+  if (extraction.kind === "inline") {
+    buildCombinedRouteMapWithSearch(
+      realPath,
+      void 0,
+      /* @__PURE__ */ new Set(),
+      diagnostics,
+      extraction.block
+    );
+    return diagnostics;
+  }
+  const imported = resolveImportedVariable(source, extraction.name);
   let targetFile;
   let exportedName;
   if (imported) {
@@ -765,9 +860,8 @@ function detectUnresolvableIncludes(routerFilePath) {
     exportedName = imported.exportedName;
   } else {
     targetFile = realPath;
-    exportedName = urlsVarName;
+    exportedName = extraction.name;
   }
-  const diagnostics = [];
   buildCombinedRouteMapWithSearch(
     targetFile,
     exportedName,
@@ -815,25 +909,15 @@ function writeCombinedRouteTypes(root, knownRouterFiles, opts) {
     throw new Error(formatNestedRouterConflictError(nestedRouterConflict));
   }
   for (const routerFilePath of routerFilePaths) {
-    let routerSource;
-    try {
-      routerSource = readFileSync3(routerFilePath, "utf-8");
-    } catch {
-      continue;
-    }
-    const urlsVarName = extractUrlsVariableFromRouter(routerSource);
-    if (!urlsVarName) continue;
-    let result;
-    const imported = resolveImportedVariable(routerSource, urlsVarName);
-    if (imported) {
-      const targetFile = resolveImportPath(imported.specifier, routerFilePath);
-      if (!targetFile) continue;
-      result = buildCombinedRouteMapWithSearch(
-        targetFile,
-        imported.exportedName
-      );
-    } else {
-      result = buildCombinedRouteMapWithSearch(routerFilePath, urlsVarName);
+    const result = buildCombinedRouteMapForRouterFile(routerFilePath);
+    if (Object.keys(result.routes).length === 0 && Object.keys(result.searchSchemas).length === 0) {
+      let routerSource;
+      try {
+        routerSource = readFileSync3(routerFilePath, "utf-8");
+      } catch {
+        continue;
+      }
+      if (!extractUrlsFromRouter(routerSource)) continue;
     }
     const routerBasename = pathBasename(routerFilePath).replace(
       /\.(tsx?|jsx?)$/,
@@ -1062,8 +1146,9 @@ function createVersionPlugin() {
   let isDev = false;
   let server = null;
   const clientModuleSignatures = /* @__PURE__ */ new Map();
+  let versionCounter = 0;
   const bumpVersion = (reason) => {
-    currentVersion = Date.now().toString(16);
+    currentVersion = Date.now().toString(16) + String(++versionCounter);
     console.log(`[rsc-router] ${reason}, version updated: ${currentVersion}`);
     const rscEnv = server?.environments?.rsc;
     const versionMod = rscEnv?.moduleGraph?.getModuleById(
@@ -1119,6 +1204,9 @@ function createVersionPlugin() {
       if (!isDev) return;
       const isRscModule = this.environment?.name === "rsc";
       if (!isRscModule) return;
+      if (ctx.modules.length === 1 && ctx.modules[0].id === "\0" + VIRTUAL_IDS.version) {
+        return;
+      }
       if (isCodeModule(ctx.file)) {
         const filePath = normalizeModuleId(ctx.file);
         const previousSignature = clientModuleSignatures.get(filePath);