@rangojs/router 0.0.0-experimental.0b3f4e91 → 0.0.0-experimental.0c4f94c2

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"
 ```
 
@@ -711,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 }));
@@ -723,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 }));
@@ -742,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

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;