@rangojs/router 0.0.0-experimental.8874d8d2 → 0.0.0-experimental.89

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

@@ -91,24 +91,29 @@ This file is a server/RSC module and should import router construction APIs from
 
 ```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"
 ```
 
@@ -156,13 +161,18 @@ const urlpatterns = urls(({ path }) => [
 ]);
 ```
 
-Use `reverse()` as the default way to link to routes:
+Use `ctx.reverse()` from handler context as the default way to link to routes from server code:
 
 ```tsx
-router.reverse("product", { slug: "widget" }); // "/product/widget"
-router.reverse("search", undefined, { q: "rsc" }); // "/search?q=rsc"
+const ProductPage: Handler<"product"> = (ctx) => {
+  const url = ctx.reverse("product", { slug: "widget" }); // "/product/widget"
+  const searchUrl = ctx.reverse("search", undefined, { q: "rsc" }); // "/search?q=rsc"
+  return <Link to={url}>Widget</Link>;
+};
 ```
 
+`router.reverse()` (exported from the router module) is the same function without a handler context, useful in scripts or tests. In request code, prefer `ctx.reverse()` — it auto-fills mount params from the current match.
+
 ### Composable URL Modules
 
 Local route names compose cleanly with `include(..., { name })`:
@@ -474,39 +484,64 @@ const urlpatterns = urls(({ path, loader }) => [
 
 ## Navigation & Links
 
-### Named Routes with `reverse()` (Server Components)
+### Named Routes with `ctx.reverse()` (Server)
 
-In server components, use `reverse()` to generate URLs by route name:
+In server components and handlers, use `ctx.reverse()` to generate URLs by route name. This is the default — it is typed, auto-fills mount params from the current match, and resolves both local (`.name`) and absolute (`name.sub`) names:
 
 ```tsx
 import { Link } from "@rangojs/router/client";
+import type { Handler } from "@rangojs/router";
+
+const BlogPostPage: Handler<"blogPost"> = (ctx) => {
+  const backUrl = ctx.reverse("blog");
+  return <Link to={backUrl}>Back to blog</Link>;
+};
+```
+
+`reverse()` is type-safe — route names and required params are checked at compile time. Included routes use dotted names: `ctx.reverse("api.health")`.
+
+For scripts, tests, or other code without a handler context, import the router-level `reverse`:
+
+```tsx
 import { reverse } from "./router";
+reverse("blogPost", { slug: "my-post" });
+```
+
+### Client Components
+
+**`reverse()` is server-only.** It depends on the route manifest and handler context — neither is available in the browser bundle. Client components receive URLs as props, loader data, or server-action return values:
 
-function BlogIndex() {
+```tsx
+// server
+function BlogIndex(ctx: HandlerContext) {
   return (
-    <nav>
-      <Link to={reverse("home")}>Home</Link>
-      <Link to={reverse("blogPost", { slug: "my-post" })}>My Post</Link>
-      <Link to={reverse("about")}>About</Link>
-    </nav>
+    <Nav
+      home={ctx.reverse("home")}
+      post={ctx.reverse("blogPost", { slug: "my-post" })}
+    />
   );
 }
 ```
 
-`reverse()` is type-safe — route names and required params are checked at compile time. Included routes use dotted names: `reverse("api.health")`.
-
-Handlers also have `ctx.reverse()` directly on the context:
-
 ```tsx
-const BlogPostPage: Handler<"blogPost"> = (ctx) => {
-  const backUrl = ctx.reverse("blog");
-  return <Link to={backUrl}>Back to blog</Link>;
-};
+"use client";
+import { Link } from "@rangojs/router/client";
+
+export function Nav({ home, post }: { home: string; post: string }) {
+  return (
+    <nav>
+      <Link to={home}>Home</Link>
+      <Link to={post}>My Post</Link>
+    </nav>
+  );
+}
 ```
 
+For client-side navigation to static paths (no named-route lookup), use `href()` — see below. For URLs tied to named routes, always generate on the server and pass the string in.
+
 ### `href()` for Path Validation (Client Components)
 
-In client components, use `href()` for compile-time path validation:
+In client components, use `href()` for compile-time path validation on static path strings:
 
 ```tsx
 "use client";
@@ -711,10 +746,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 }));
@@ -723,16 +760,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 }));
@@ -742,10 +785,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

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);