@rangojs/router 0.16.0 → 0.17.0

package/README.md

@@ -8,11 +8,19 @@ everything past the core is opt-in.
 > releases and are noted in the changelog. npm `latest` is the current 0.x
 > release; the `experimental` tag tracks `main` between tagged releases.
 
-This page is a tour: it builds one small shop and meets the entire core API
-along the way — about six primitives. Everything else is opt-in and linked at
-the end. For the design rationale behind these APIs, read
-[Why Rango](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/why-rango.md); this page shows how it feels, that page
-argues why it's right.
+This page is a tour. It builds one small shop in six steps and covers the
+whole core API along the way:
+
+1. **Pages**: nested layouts, named routes, typed params
+2. **Data**: fetching in handlers, and loaders for data that stays live
+3. **Mutations**: Server Actions that work without JavaScript
+4. **Speed**: cached pages with live loaders, prefetching, prerendering
+5. **APIs**: JSON and other responses served from the same URLs as pages
+6. **Tests**: unit tests for loaders, e2e tests in dev and production
+
+Everything else is opt-in and linked at the end. This page shows how the API
+feels to use. For why it's designed this way, read
+[Why Rango](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/why-rango.md).
 
 ## Start a new app
 
@@ -36,25 +44,46 @@ or newer.
 If you are adding Rango to an existing Vite RSC project:
 
 ```bash
-npm install @rangojs/router@latest react @vitejs/plugin-rsc
+npm install @rangojs/router@latest react react-dom
+npm install -D vite
 ```
 
 ```ts
 // vite.config.ts
-import react from "@vitejs/plugin-react";
 import { defineConfig } from "vite";
 import { rango } from "@rangojs/router/vite";
 
 export default defineConfig({
-  plugins: [react(), rango({ preset: "cloudflare" })],
+  plugins: [rango()],
 });
 ```
 
-The `cloudflare` preset targets Cloudflare Workers (add
-`@cloudflare/vite-plugin`); the `vercel` preset emits a ready-to-deploy
-`.vercel/output` (Build Output API) from a plain `vite build` — see the
-[`/vercel` skill](./skills/vercel/SKILL.md); omit `preset` for the default
-Node setup.
+That is the whole Node setup. `rango()` includes `@vitejs/plugin-rsc` and
+supplies the client and server entries, so you don't need an `index.html` or
+entry files. It finds the router by looking for the `createRouter()` call in
+your source. Add `@vitejs/plugin-react` only if you want Fast Refresh or the
+React Compiler.
+
+For Cloudflare Workers, use the `cloudflare` preset together with
+`@cloudflare/vite-plugin`:
+
+```ts
+import { cloudflare } from "@cloudflare/vite-plugin";
+
+export default defineConfig({
+  plugins: [
+    rango({ preset: "cloudflare" }),
+    cloudflare({
+      viteEnvironment: { name: "rsc", childEnvironments: ["ssr"] },
+    }),
+  ],
+});
+```
+
+The `vercel` preset turns a plain `vite build` into a ready-to-deploy
+`.vercel/output` (Build Output API). See the
+[`/cloudflare`](./skills/cloudflare/SKILL.md) and
+[`/vercel`](./skills/vercel/SKILL.md) skills.
 
 ## Using the skills with your coding agent
 
@@ -75,60 +104,98 @@ is at `skills/catalog.json`.
 
 ## 1. Pages
 
-A router is a tree. `path()` places a page, `layout()` wraps children,
-`{ name }` gives a route an identity:
+A router is a tree. `path()` places a page, `layout()` wraps its children,
+and `{ name }` gives a route an identity. Layouts nest, so each part of the
+site wraps only what it owns:
 
 ```tsx
 // src/router.tsx
 import { createRouter, urls } from "@rangojs/router";
 import { Document } from "./document";
+import { SiteLayout } from "./layouts/site";
 import { ShopLayout } from "./layouts/shop";
 import { HomePage } from "./routes/home";
-import { ProductPage } from "./routes/product";
+import { ProductList, ProductPage } from "./routes/product";
 
 const urlpatterns = urls(({ path, layout }) => [
-  layout(<ShopLayout />, () => [
+  layout(<SiteLayout />, () => [
     path("/", HomePage, { name: "home" }),
-    path("/products/:slug", ProductPage, { name: "product" }),
+
+    layout(<ShopLayout />, () => [
+      path("/products", ProductList, { name: "products" }),
+      path("/products/:slug", ProductPage, { name: "product" }),
+    ]),
   ]),
 ]);
 
 export const router = createRouter({ document: Document }).routes(urlpatterns);
 ```
 
+A layout renders its children through `<Outlet />`. `SiteLayout` wraps every
+page, and `ShopLayout` adds the category sidebar only to the product routes:
+
+```tsx
+// src/layouts/site.tsx
+import { Link, Outlet } from "@rangojs/router/client";
+
+export function SiteLayout() {
+  return (
+    <>
+      <header>
+        <Link to="/">Home</Link> <Link to="/products">Shop</Link>
+      </header>
+      <Outlet /> {/* the home page or ShopLayout */}
+    </>
+  );
+}
+```
+
 ```tsx
 // src/layouts/shop.tsx
 import { Outlet } from "@rangojs/router/client";
 
 export function ShopLayout() {
   return (
-    <div>
-      <nav>Shop</nav>
+    <div className="shop">
+      <CategorySidebar />
       <main>
-        <Outlet /> {/* child routes render here */}
+        <Outlet /> {/* the product list or a product page */}
       </main>
     </div>
   );
 }
 ```
 
+When you navigate from `/products` to `/products/espresso-cup`, only the
+innermost segment changes. Both layouts stay mounted, so they keep their
+client state and aren't re-rendered on the server. A layout can also be a
+server function `(ctx) => <Shell />` when it needs request data, and it can
+carry its own loaders, middleware, and error boundaries. The
+[`/layout` skill](./skills/layout/SKILL.md) covers these, and
+[`/parallel`](./skills/parallel/SKILL.md) covers named slots such as a
+sidebar and main column that load independently.
+
+Outside all layouts is the document, the HTML shell passed to
+`createRouter({ document })`:
+
 ```tsx
 // src/document.tsx
 "use client";
 
 import type { ReactNode } from "react";
-import { MetaTags, Scripts } from "@rangojs/router/client";
+import { Html } from "@rangojs/router/client";
 
 export function Document({ children }: { children: ReactNode }) {
   return (
     <html lang="en">
       <head>
-        <MetaTags />
-        <Scripts />
+        <Html.Meta />
+        <Html.Scripts />
       </head>
       <body>
-        <Scripts position="body" />
+        <Html.Scripts position="body" />
         {children}
+        <Html.ScrollRestoration />
       </body>
     </html>
   );
@@ -157,16 +224,18 @@ const url = ctx.reverse("product", { slug: "espresso-cup" });
 // "/products/espresso-cup" — name and params compile-time checked
 ```
 
-Rename `/products/:slug` to `/shop/:slug` in the one place it's defined and
-every link, redirect, and prefetch follows. In client components, `href()`
-validates static paths against the registered patterns:
-`<Link to={href("/")}>Home</Link>`.
+Rename `/products/:slug` to `/shop/:slug` in the one place it's defined, and
+every URL built with `ctx.reverse()` or `useReverse()` follows. In client
+components, `href()` checks a literal path against the registered patterns
+(`<Link to={href("/")}>Home</Link>`). After a rename, a stale `href()` path is
+a compile error, not a broken link.
 
 The tree is also lazy-first, which is the shape serverless cold starts want.
 `include()` mounts a whole route module under a prefix — and with the async
 form, `include("/shop", () => import("./shop"))`, the group is code-split:
 its module doesn't load or run until a request matches it, a group nobody
-visits never evaluates at all, and warm requests run zero route handlers.
+visits never evaluates at all, and warm requests re-evaluate zero route
+definitions.
 Boot cost stays flat as the app grows — one module body at startup, not one
 per group — while matching stays an `O(path length)` prefix trie, identical
 in dev and production. None of this is assumed: the trie is benchmarked
@@ -230,16 +299,26 @@ export function StockBadge() {
 }
 ```
 
-Loaders run in parallel with the handler and stream; `loading()` opts the
-segment into skeleton-then-stream. Without it, document requests arrive
-**ready** — the HTML ships with data in place; the skeleton is a per-segment
-choice, not the first impression.
+Loaders run in parallel with the handler and stream their results.
+`loading()` makes the segment render a skeleton first and stream the data
+into it. Without `loading()`, the segment has no skeleton, and the HTML
+normally arrives with the data already in place. To guarantee that a
+loader's data, head tags, or a real 404 are in the first HTML flush, register
+it with `loader(StockLoader, { ssr: false })`.
 
-The rule of thumb: fetch in the **handler** when the data belongs to the
-rendered page — it will be frozen with the shell if you cache it (step 4).
-Put data in a **loader** when it must outlive the shell: shared with client
-components, fresh on every hit even when the segment is cached, refetchable
-from the client, or revalidated on its own after actions.
+When a loader's data changes, every component that reads it updates too.
+Calling `load()` from `useLoader()` refetches it on the client, and
+`createLoader(fn, true)` makes a loader fetchable directly from client code
+with `useFetchLoader()`. See the [`/loader` skill](./skills/loader/SKILL.md).
+
+The rule of thumb:
+
+- Fetch in the **handler** when the data belongs to the rendered page. If
+  you cache the page (step 4), that data is cached with it.
+- Put data in a **loader** when it needs to stay independent of the page:
+  shared with client components, fresh on every request even when the page is
+  cached, refetchable from the client, or revalidated separately after
+  actions.
 
 ## 3. Mutations
 
@@ -251,8 +330,12 @@ JavaScript:
 // src/actions/cart.ts
 "use server";
 
-export async function addToCart(productId: string) {
+export type CartState = { added?: string } | null;
+
+export async function addToCart(_prev: CartState, formData: FormData) {
+  const productId = String(formData.get("productId"));
   await db.cart.insert({ productId });
+  return { added: productId };
 }
 ```
 
@@ -263,26 +346,36 @@ import { useActionState } from "react";
 import { addToCart } from "../actions/cart";
 
 export function AddToCart({ productId }: { productId: string }) {
-  const [, action, pending] = useActionState(() => addToCart(productId), null);
+  const [state, action, pending] = useActionState(addToCart, null);
   return (
     <form action={action}>
+      <input type="hidden" name="productId" value={productId} />
       <button disabled={pending}>{pending ? "Adding…" : "Add to cart"}</button>
+      {state?.added && <p>Added.</p>}
     </form>
   );
 }
 ```
 
-After an action, route segments and loaders re-render by default so the UI
-reflects the new state. `revalidate()` narrows that to the segments that
-actually own the data — matched by action **reference**, so renames are
-compile errors, not stale predicates:
+Pass `addToCart` to the hook directly. Wrapping it in a client-side
+closure such as `() => addToCart(id)` turns it into a function that only
+exists in the browser. The form then has no server URL to post to before
+JavaScript loads.
+
+After an action, the route's segments and all loaders re-run by default, so
+the UI reflects the new state. Parent layouts are skipped. `revalidate()`
+lets you change that for a segment or loader. It matches actions by
+**reference**, so renaming an action is a compile error, not a check that
+silently stops matching:
 
 ```tsx
 import * as CartActions from "./actions/cart";
 
-path("/cart", CartPage, { name: "cart" }, () => [
-  loader(CartLoader, () => [
-    revalidate((ctx) => ctx.isAction(CartActions) || undefined),
+path("/products/:slug", ProductPage, { name: "product" }, () => [
+  // After an action, re-run the cart summary only for cart actions.
+  // On plain navigation, `undefined` keeps the default behavior.
+  loader(CartSummaryLoader, () => [
+    revalidate((ctx) => (ctx.isAction() ? ctx.isAction(CartActions) : undefined)),
   ]),
 ]),
 ```
@@ -302,21 +395,31 @@ choice from step 2 pays off: handler data freezes with the shell, the
 
 ```tsx
 const urlpatterns = urls(({ path, layout, loader, loading, cache }) => [
-  layout(<ShopLayout />, () => [
+  layout(<SiteLayout />, () => [
     path("/", HomePage, { name: "home" }),
-    cache({ ttl: 600, swr: 3600, tags: ["products"] }, () => [
-      path("/products/:slug", ProductPage, { name: "product" }, () => [
-        loader(StockLoader), // never cached: re-runs on every hit
-        loading(<ProductSkeleton />),
+
+    layout(<ShopLayout />, () => [
+      path("/products", ProductList, { name: "products" }),
+      cache({ ttl: 600, swr: 3600, tags: ["products"] }, () => [
+        path("/products/:slug", ProductPage, { name: "product" }, () => [
+          loader(StockLoader), // never cached: re-runs on every hit
+          loading(<ProductSkeleton />),
+        ]),
       ]),
     ]),
   ]),
 ]);
 ```
 
-Wire a store once on the router (`MemorySegmentCacheStore` for dev,
-`CFCacheStore` for Cloudflare — see the [`/caching` skill](./skills/caching/SKILL.md)),
-and bust by tag from the mutation that changes the data:
+Set up a store once on the router. Use `MemorySegmentCacheStore` in
+development, `CFCacheStore` on Cloudflare (Cache API with optional KV), or
+`VercelCacheStore` on Vercel. The memory store expires entries at `ttl` and
+does not serve stale content in the background, so you will only see `swr`
+work on the Cloudflare and Vercel stores. The
+[`/caching` skill](./skills/caching/SKILL.md) covers setup.
+
+To invalidate, call `updateTag()` with the tag from the action that changes
+the data:
 
 ```tsx
 // src/actions/products.ts
@@ -329,27 +432,40 @@ export async function renameProduct(id: string, name: string) {
 }
 ```
 
-Navigation speed is a `Link` prop away:
+In production, links prefetch when they scroll into view. You can change
+that per link with `prefetch`: `"hover"`, `"viewport"`, `"render"`,
+`"adaptive"` (hover on pointer devices, viewport on touch), or `"none"`:
 
 ```tsx
-<Link to={url} prefetch="viewport">
+<Link to={url} prefetch="adaptive">
   {product.name}
 </Link>
 ```
 
-A fully-prefetched navigation commits a **finished page** — no skeleton, no
-loading flash — and staying correct is the router's job: every action
-invalidates the prefetch caches by default, so a prefetched page can't show
-pre-mutation data.
-
-To move the shell's cost to build time entirely, `Prerender()` bakes it while
-loaders stay live at runtime — same mental model, earlier cache write. See
-the [`/prerender` skill](./skills/prerender/SKILL.md).
+When a navigation has been fully prefetched, the page appears finished, with
+no skeleton or loading flash. If you click while a prefetch is still loading,
+the navigation reuses that request instead of starting a new one. Every
+action clears the prefetch caches by default, so a prefetched page can't
+show data from before a mutation.
+
+You can do the same caching work at other times:
+
+- **At build time:** `Prerender()` renders the page during `vite build` and
+  stores it in the same format as a runtime cache entry. Loaders still run
+  on every request. The browser can't tell a prerendered page from a cached
+  one. See the [`/prerender` skill](./skills/prerender/SKILL.md).
+- **As an HTML shell:** `{ name: "product", ppr: true }` on a path stores
+  the static HTML around the loaders. On a hit, the router sends that shell
+  once middleware has run, then streams in only the live parts. See the
+  [`/ppr` skill](./skills/ppr/SKILL.md).
+- **Per function:** `"use cache"` caches a single function or component,
+  with named profiles. See the [`/use-cache` skill](./skills/use-cache/SKILL.md).
 
 ## 5. An API, when you need one
 
-Response routes live in the same tree — `path.json()`, `path.text()`,
-`path.xml()`, `path.image()`, `path.stream()`:
+Response routes live in the same tree: `path.json()`, `path.text()`,
+`path.html()`, `path.xml()`, `path.md()`, `path.image()`, `path.stream()`,
+and `path.any()` for raw `Response`s such as WebSocket upgrades:
 
 ```tsx
 path("/products/:slug", ProductPage, { name: "product" }),
@@ -370,11 +486,52 @@ type Product = RouteResponse<typeof urlpatterns, "productJson">;
 See the [`/api-client` skill](./skills/api-client/SKILL.md) for a small typed
 client over these endpoints.
 
+## 6. Tests
+
+Everything above can be tested at its own layer, through the same public
+APIs your app uses. A loader runs in plain Node with the real request
+context, and you supply the params:
+
+```ts
+// src/loaders/stock.test.ts
+import { runLoader } from "@rangojs/router/testing";
+import { StockLoader } from "./stock";
+
+test("reports stock for a product", async () => {
+  const stock = await runLoader(StockLoader, {
+    params: { slug: "espresso-cup" },
+  });
+  expect(stock.inStock).toBe(true);
+});
+```
+
+End to end, `parityDescribe` runs one test body against the dev server and
+the production build. `expectParity` submits the form once with JavaScript
+and once without, then checks that both show the same result:
+
+```ts
+// e2e/cart.test.ts
+parityDescribe("add to cart", (f) => {
+  test("works the same with and without JavaScript", async ({ page }) => {
+    await page.goto(f.url("/products/espresso-cup"));
+    await expectParity(
+      page,
+      { submit: { testId: "add-to-cart-form" } },
+      { observe: ["cart-count"] },
+    );
+  });
+});
+```
+
+`runMiddleware`, `renderHandler` (Server Component handlers rendered to a
+real Flight tree), `renderRoute` (DOM tests) and the cache assertions follow
+the same pattern. See the [`/testing` skill](./skills/testing/SKILL.md).
+
 ## Everything else, when you need it
 
-That was the core: `path`/`layout`/`include`, names, loaders, actions +
-`revalidate`, `cache`, response routes. The rest is opt-in — reach for it
-when the requirement appears:
+That was the core: `path`/`layout`/`include`, names, loaders, actions and
+`revalidate`, `cache`, response routes, and tests. Everything else is opt-in.
+Use it when you need it:
 
 | I need to…                                      | Skill                                                                                        |
 | ----------------------------------------------- | -------------------------------------------------------------------------------------------- |
@@ -404,25 +561,28 @@ mental model that ties it together.
 
 ### Imports and subpaths
 
-| 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`, `VercelCacheStore`, `MemorySegmentCacheStore`, `createDocumentCacheMiddleware`                          |
-| `@rangojs/router/theme`   | Theme: `useTheme`, `ThemeProvider`, `ThemeScript`                                                                              |
-| `@rangojs/router/host`    | Host routing: `createHostRouter`, `defineHosts`, `isNoRouteMatchError`                                                         |
-| `@rangojs/router/vercel`  | Vercel: `createVercelTracing` (phase spans via `@vercel/otel`'s global tracer)                                                 |
-| `@rangojs/router/vite`    | Vite plugin: `rango()`                                                                                                         |
-| `@rangojs/router/testing` | Consumer testing primitives: `runLoader`, `runMiddleware`, `dispatch` (plus `/testing/dom`, `/testing/flight`, `/testing/e2e`) |
-| `@rangojs/router/rsc`     | Advanced server pipeline APIs: `createRSCHandler`, request-context access                                                      |
-| `@rangojs/router/ssr`     | Advanced SSR bridge APIs: `createSSRHandler`                                                                                   |
+| 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`, `Html`                                                         |
+| `@rangojs/router/cache`        | Cache: `CFCacheStore`, `VercelCacheStore`, `MemorySegmentCacheStore`, `createDocumentCacheMiddleware`                          |
+| `@rangojs/router/theme`        | Theme: `useTheme`, `ThemeProvider`, `ThemeScript`                                                                              |
+| `@rangojs/router/host`         | Host routing: `createHostRouter`, `defineHosts`, `isNoRouteMatchError`                                                         |
+| `@rangojs/router/vercel`       | Vercel: `createVercelTracing` (phase spans via `@vercel/otel`'s global tracer)                                                 |
+| `@rangojs/router/cloudflare`   | Cloudflare: `createCloudflareTracing`                                                                                          |
+| `@rangojs/router/vite`         | Vite plugin: `rango()`                                                                                                         |
+| `@rangojs/router/testing`      | Consumer testing primitives: `runLoader`, `runMiddleware`, `dispatch`, cache assertions                                        |
+| `@rangojs/router/testing/*`    | `/dom` (`renderRoute`), `/flight` (`renderHandler`), `/flight-matchers`, `/e2e` (`createRangoE2E`), `/vitest` (config helpers) |
+| `@rangojs/router/host/testing` | Test helpers for host routers                                                                                                  |
+| `@rangojs/router/rsc`          | Advanced server pipeline APIs: `createRSCHandler`, request-context access                                                      |
+| `@rangojs/router/ssr`          | Advanced SSR bridge APIs: `createSSRHandler`                                                                                   |
 
 Use only subpaths that are explicitly exported; avoid deep imports.
 
 The root entry is conditionally resolved: server-only APIs (`createRouter`,
 `urls`, `redirect`, `Prerender`, `cookies`) run under the `react-server`
 condition and throw guidance errors elsewhere. If you hit a root-entrypoint
-stub error: hooks and components (`Link`, `Outlet`, `useLoader`, `MetaTags`)
+stub error: hooks and components (`Link`, `Outlet`, `useLoader`, `Html`)
 live in `@rangojs/router/client`; cache APIs in `@rangojs/router/cache`;
 host APIs in `@rangojs/router/host`.
 
@@ -431,14 +591,19 @@ host APIs in `@rangojs/router/host`.
 The Vite plugin generates `router.named-routes.gen.ts` automatically (on dev
 startup, HMR, and builds), registering route names, params, and search
 schemas globally via `Rango.GeneratedRouteMap`. That powers `Handler<"name">`,
-`ctx.reverse()`, and `RouteParams<"name">` with no manual registration.
+`ctx.reverse()`, `href()`, `Rango.Path` and `RouteParams<"name">` with no
+manual registration. `RouteResponse<typeof urlpatterns, "name">` takes the
+patterns directly, so it needs no registration either.
 
-For response-aware and path-based utilities (`href()`, `Rango.Path`,
-`RouteResponse`), augment `Rango.RegisteredRoutes` once:
+Two things are opt-in augmentations. `Rango.Env` types `ctx.env`.
+`Rango.RegisteredRoutes` is needed only for `Rango.PathResponse` (looking up
+a response payload by path):
 
 ```ts
 // router.tsx
-const router = createRouter<AppBindings>({}).routes(urlpatterns);
+type AppBindings = { DB: D1Database };
+
+export const router = createRouter<AppBindings>({}).routes(urlpatterns);
 
 // The alias is required: an interface heritage clause cannot take a `typeof`
 // type query directly (TS1109), so extend through a named alias.
@@ -446,7 +611,7 @@ type AppRoutes = typeof router.routeMap;
 
 declare global {
   namespace Rango {
-    interface Env extends AppEnv {}
+    interface Env extends AppBindings {}
     interface RegisteredRoutes extends AppRoutes {}
   }
 }