@rangojs/router 0.24.3 → 0.25.0

package/skills/app-structure/multi-app.md

@@ -0,0 +1,280 @@
+# Several apps under createHostRouter()
+
+One deployment, several independently routed apps: marketing on the apex
+(`example.com`, `www.example.com`), the product on `app.`, the staff tools
+on `admin.`, the docs on `docs.`. Each app is an ordinary `createRouter()`
+app with its own `urls()`, Document and generated route map; the host router
+only picks which one handles a request.
+
+Reach for this when parts of the product want different documents, chrome,
+deploy cadence or hostnames. Sections that share one document belong in one
+router as `include()`s ([`./large-app.md`](./large-app.md)): a navigation
+between apps is always a document load.
+
+References in the router repository: `examples/cloudflare-multi-router` (a
+Cloudflare host entry, path-mounted and host-mounted apps, a shared cache)
+and `packages/rangojs-router/e2e/test-app/.host-fixture` (the Node preset,
+the host-override cookie, two apps on one store).
+
+## File tree
+
+```
+src/
+  worker.rsc.tsx              the host router (Cloudflare: you own the entry)
+  env.ts                      bindings shared by every app
+  shared/
+    document.tsx              "use client" Document the apps pass to createRouter()
+    styles.css                one stylesheet (e.g. @import "tailwindcss")
+    theme.ts                  one ThemeConfig
+    cache.ts                  one cache store factory
+    origins.ts                each app's origin, per environment
+    top-nav.tsx               components every app renders
+  apps/
+    site/   router.tsx  handler.ts  urls.tsx  router.named-routes.gen.ts  tsconfig.json
+    app/    router.tsx  handler.ts  urls.tsx  router.named-routes.gen.ts  tsconfig.json  …
+    admin/  …
+    docs/   …
+tsconfig.json                 the host entry's program only
+```
+
+## The host router
+
+```tsx
+// src/worker.rsc.tsx
+import {
+  createHostRouter,
+  defineHosts,
+  isNoRouteMatchError,
+} from "@rangojs/router/host";
+import type { AppBindings } from "./env";
+
+export const hosts = defineHosts({
+  site: [".", "www.*"],
+  app: "app.*",
+  admin: "admin.*",
+  docs: "docs.*",
+});
+
+// Dev: every app answers on localhost, and the x-rango-host cookie picks one
+// (x-rango-host=admin.example.com). The request is forwarded unchanged.
+const hostRouter = createHostRouter({
+  hostOverride: { cookieName: "x-rango-host", allowedHosts: ["localhost"] },
+});
+
+// Lazy mounts: an app's module graph loads on its first request, and each app
+// keeps its own cache version.
+hostRouter.host(hosts.admin).lazy(() => import("./apps/admin/handler"));
+hostRouter.host(hosts.app).lazy(() => import("./apps/app/handler"));
+hostRouter.host(hosts.docs).lazy(() => import("./apps/docs/handler"));
+hostRouter.host(hosts.site).lazy(() => import("./apps/site/handler"));
+// localhost has one label: neither "." nor "*." matches it.
+hostRouter.host(["localhost"]).lazy(() => import("./apps/site/handler"));
+
+export default {
+  async fetch(request, env, ctx) {
+    try {
+      return await hostRouter.match(request, { env, ctx });
+    } catch (err) {
+      if (isNoRouteMatchError(err))
+        return new Response("Not Found", { status: 404 });
+      throw err;
+    }
+  },
+} satisfies ExportedHandler<AppBindings>;
+```
+
+Patterns are tried in registration order, first match wins; "apex" means
+exactly two labels (no public-suffix list), so `example.co.uk` needs its own
+pattern (`/host-router` → "Pattern Syntax").
+
+On the `node` and `vercel` presets rango owns the entry: export the instance
+(`export default hostRouter`), drop the `fetch` wrapper, and an unmatched host
+answers 404 on its own. Point `rango({ hostRouter: "./src/worker.rsc.tsx" })`
+at the module when auto-detection cannot pick it.
+
+## Each app
+
+```ts
+// src/apps/app/handler.ts: what the host router's lazy mount imports
+import { router } from "./router";
+
+export default (request: Request, input: any) => router.fetch(request, input);
+```
+
+```tsx
+// src/apps/app/router.tsx
+import { createRouter } from "@rangojs/router";
+import { Document } from "../../shared/document";
+import { appCache } from "../../shared/cache";
+import { theme } from "../../shared/theme";
+import type { AppBindings } from "../../env";
+import { loadSession } from "./session";
+import { appPatterns } from "./urls";
+
+export const router = createRouter<AppBindings>({
+  document: Document,
+  cache: appCache,
+  theme,
+})
+  .use(loadSession)
+  .routes(appPatterns);
+```
+
+```tsx
+// src/apps/app/urls.tsx
+import { urls } from "@rangojs/router";
+import { Outlet } from "@rangojs/router/client";
+import { TopNav } from "../../shared/top-nav";
+import { DashboardPage, LoginPage } from "./pages";
+import { requireUser } from "./session";
+
+function Shell() {
+  return (
+    <>
+      <TopNav />
+      <Outlet />
+    </>
+  );
+}
+
+export const appPatterns = urls(({ path, layout, middleware }) => [
+  path("/login", LoginPage, { name: "login" }),
+  layout(Shell, () => [
+    middleware(requireUser),
+    path("/", DashboardPage, { name: "dashboard" }),
+    // … the app's sections as includes, as in ./large-app.md
+  ]),
+]);
+```
+
+Inside an app, everything in the other recipes applies unchanged: the `app.`
+app is [`./large-app.md`](./large-app.md) without its marketing pages, the
+`docs.` app is [`./content-site.md`](./content-site.md), and `site` is a
+handful of `ppr` pages:
+
+```tsx
+// src/apps/site/urls.tsx (excerpt)
+export const sitePatterns = urls(({ path, layout }) => [
+  layout(SiteLayout, () => [
+    path("/", Home, { name: "home", ppr: true }),
+    path("/pricing", Pricing, { name: "pricing", ppr: true }),
+  ]),
+]);
+```
+
+## What is shared, and how
+
+| Shared        | How                                                                                            | Notes                                                                                                                                                                                                                       |
+| ------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Components    | ordinary imports from `src/shared/`                                                            | One Vite build and one client manifest: a shared client component ships as the same hashed asset to every app. Keep route-name-typed calls (`ctx.reverse("…")`, `href()`) out of shared code; each app's names are its own. |
+| The Document  | one `"use client"` component every `createRouter({ document })` passes, or one per app         | Each document load is that app's own; apps may differ freely                                                                                                                                                                |
+| CSS           | `import styles from "../../shared/styles.css?url"` in the Document, `<link precedence>`        | Compiles to one hashed asset, cached across apps. Apps need not agree on `precedence`: a cross-app navigation is a document load (`/css`)                                                                                   |
+| Theme         | one `ThemeConfig` object passed as `theme` to every router                                     | The stored choice is a host-only cookie (`src/theme/ThemeProvider.tsx`, no `Domain`), so a theme picked on `app.` does not follow the user to `docs.`                                                                       |
+| Cache store   | one factory (`cache: appCache`), one KV namespace                                              | Keys holding one router's output start with that router's id, so two apps never read each other's shells, records or loader entries. Keep `createRouter({ ... })` an inline object literal (or pass `id`) so ids are stable |
+| Session       | a cookie on the parent domain, `cookies().set("session", token, { domain: "example.com", … })` | Set by the app that signs users in; every app resolves it in its own `router.use()`                                                                                                                                         |
+| Client caches | not shared                                                                                     | The state cookie is `rango-state_{routerId}`, one per app, so sibling apps on one origin do not collide                                                                                                                     |
+
+## TypeScript: one program per app
+
+Every router's `router.named-routes.gen.ts` augments the one global
+`Rango.GeneratedRouteMap`, so two apps with overlapping route names
+(`home`, `login`) collide in one program. Give each app its own
+`tsconfig.json`, and keep the root program to the host entry:
+
+```jsonc
+// tsconfig.json: the host entry only
+{ "extends": "./tsconfig.base.json", "include": ["src/env.ts", "src/worker.rsc.tsx"] }
+
+// src/apps/app/tsconfig.json: one app, its generated map, the shared code
+{ "extends": "../../../tsconfig.base.json", "include": ["**/*", "../../shared/**/*", "../../env.ts"] }
+```
+
+The root program still type-checks the apps' source through the lazy
+`import()`s, but not their generated maps, as long as no app source imports
+its own `*.named-routes.gen.ts`. Run `tsc -p` for each program in CI.
+Generated and committed: one `router.named-routes.gen.ts` per app (plus
+per-module `*.gen.ts` where an app uses `useReverse(routes)`). See
+`/typesafety` → multi-project setup.
+
+## Dev: the host-override cookie
+
+`vite dev` serves every app on one origin, `localhost`. The
+`hostOverride` option picks the app from a cookie when the request's real
+host matches `allowedHosts`:
+
+```js
+// browser devtools, on http://localhost:5173
+document.cookie = "x-rango-host=admin.example.com; path=/";
+```
+
+Reload and the admin app answers; delete the cookie for the site. Without a
+`fallback()`, a cookie the router refuses (a malformed hostname, a host not
+in `allowedHosts`) answers 400 and clears the cookie. Playwright sets it with
+`context.addCookies([{ name: "x-rango-host", value: "admin.example.com", url }])`,
+which is how both reference apps run their dev and production e2e.
+
+All apps answer under one origin in this mode, so links to another app's
+production host leave the dev server; switch apps by changing the cookie.
+
+## Links between apps
+
+A navigation from one app to another is a full document load, by design. A
+soft in-place swap between apps shipped once (#476) and was replaced by a
+document navigation (#555): a stylesheet two apps share by `href` could drop
+on the swap (React dedups stylesheets by `href`), and the theme, warmup and
+prefetch settings, which are document-lifetime, would remount or never take
+effect. A document load re-establishes the target app's whole document.
+
+| The other app is                                               | Link with                                                                                         | What happens                                                                                                                                                                         |
+| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| On another host (`app.example.com`)                            | an absolute URL: `<Link to="https://app.example.com/">` or `<a href>`                             | Another origin is external to `<Link>` (`src/browser/react/Link.tsx`) and to the plain-anchor interceptor: the browser navigates, nothing is prefetched                              |
+| On the same origin under a path (`host(["example.com/docs"])`) | `<Link to="/docs" reloadDocument prefetch="none">` or `<a href="/docs" data-no-intercept="true">` | A document navigation at the click. A plain same-origin `<Link>` also ends in a document load, after a wasted round trip: the server answers the partial request with `X-RSC-Reload` |
+
+```tsx
+// src/shared/origins.ts
+export const ORIGINS = {
+  site: import.meta.env.VITE_SITE_ORIGIN ?? "https://example.com",
+  app: import.meta.env.VITE_APP_ORIGIN ?? "https://app.example.com",
+  docs: import.meta.env.VITE_DOCS_ORIGIN ?? "https://docs.example.com",
+} as const;
+
+// src/shared/top-nav.tsx: a server component every app renders
+import { Link } from "@rangojs/router/client";
+import { ORIGINS } from "./origins";
+
+export function TopNav() {
+  return (
+    <nav>
+      <Link to={`${ORIGINS.site}/`}>Home</Link>
+      <Link to={`${ORIGINS.docs}/`}>Docs</Link>
+      <Link to={`${ORIGINS.app}/`}>Open the app</Link>
+    </nav>
+  );
+}
+```
+
+`reloadDocument` alone does not stop the prefetch: without
+`prefetch="none"`, a visible link still sends one, which the other app
+answers with `X-RSC-Reload` and the client drops. Make each app's entry pages
+fast as documents (`ppr`, or `Prerender`), since every cross-app click lands
+on one.
+
+## Deploys
+
+Each `createRouter()` app has its own cache version, computed from the code
+its router can run up to a lazy mount. A deploy that changes the admin app's
+server code clears the admin app's cached data and stored HTML and reloads
+its open tabs; the other apps keep theirs. Code shared by statically
+importing modules moves every app that imports it (`/host-router` →
+"Deploys and the cache").
+
+## Why
+
+| Choice                       | Why                                                                                           |
+| ---------------------------- | --------------------------------------------------------------------------------------------- |
+| One `createRouter()` per app | Own document, routes, names, middleware, cache version                                        |
+| `.lazy()` mounts             | An app's graph loads on its first request, and the mount is where its cache version stops     |
+| `defineHosts`                | One typed table of patterns, reused by tests                                                  |
+| The cookie override in dev   | One dev origin, hydration same-origin; the reference apps' e2e drive every app through it     |
+| Absolute URLs between hosts  | Another origin is another document; no request is wasted on a prefetch or a reload round trip |
+| A program per app            | Route-name augmentations of different apps cannot collide                                     |

package/skills/breadcrumbs/SKILL.md

@@ -137,6 +137,11 @@ path("/product/:id", async (ctx) => {
 Async content is a `Promise<ReactNode>`. Resolve it in your component
 with React's `use()` hook wrapped in `<Suspense>`.
 
+A server component that pushes a crumb after an `await` throws
+`LateHandlePushError`. Reserve the crumb in the handler with `.defer()` and
+resolve it from the component (see "Deferred content" below); the same works
+for a `Meta` title.
+
 A crumb the HANDLER pushes is handler output. In a route `cache()` entry and
 in a `ppr` shell it is stored resolved: the cache write, or the shell capture
 (within `ppr.captureTimeout`), waits for a `content` promise and for a
@@ -202,7 +207,7 @@ consumer sees it — `useHandle(Breadcrumbs)` returns the resolved item, never a
 `Promise`, so you read it like any sync crumb (no `use()`, no thenable narrowing).
 On a full/SSR load the value is resolved server-side; on a soft navigation the
 breadcrumbs HOLD the previous resolved value until the deferred value lands, then
-swap in — no blank, no pending entry. If the slot times out to `else: null`/
+swap in — no blank, no pending entry. The hold-then-swap is deliberate: a handle never holds the page and never shows the next page's values over the old one (see [hooks](../hooks/handle-and-actions.md#when-handle-values-change-by-design)). If the slot times out to `else: null`/
 undefined, the entry is simply dropped. Use `.defer()` only when even
 `label`/`href` are unknown at handler time AND the producer is a component,
 not a loader — a loader-produced crumb pushes directly from the loader body

package/skills/caching/SKILL.md

@@ -894,7 +894,9 @@ and a read that worked only on direct visits would break the first time a
 rewritten request reached it. A PPR shell capture and a render the document
 cache stores read it as `undefined` instead of throwing: those renders are
 the target page as a direct visit renders it, and the rewritten visitor's
-own render (outside them) still sees its URL. A response route under
+own render (outside them) still sees its URL. A shell keyed by the visitor's
+URL (`rewrite(...).shell("visitor")`, `/ppr`) reads it, since its key covers
+that URL. A response route under
 `cache()` whose handler read it is not stored.
 
 A loader body invoked from a handler with `await ctx.use(Loader)` may read

package/skills/catalog.json

@@ -9,6 +9,12 @@
       "argumentHint": "",
       "path": "skills/api-client/SKILL.md"
     },
+    {
+      "name": "app-structure",
+      "description": "Concrete urls() layouts for whole Rango apps, with the file tree, router.tsx, the root urls.tsx with sync include() of section modules, and where middleware, server layouts, clientUrls() groups, response routes, caching, prerender, PPR and boundaries sit. Recipes for a large signed-in app with a protected admin area (auth, onboarding, app, settings and admin as clientUrls() groups under one server shell), several apps under createHostRouter(), a docs site or blog, and a shop. Use when starting or restructuring a Rango app, laying out urls() files, splitting an app into sections or separate apps, or setting up a dashboard, SaaS, multi-app, static or content site, or e-commerce app.",
+      "argumentHint": "[large-app|multi-app|content-site|e-commerce]",
+      "path": "skills/app-structure/SKILL.md"
+    },
     {
       "name": "breadcrumbs",
       "description": "Built-in Breadcrumbs handle for accumulating breadcrumb navigation across route segments. Use when building a breadcrumb trail for nested routes, or asking how to show the current navigation path in a layout.",
@@ -273,6 +279,12 @@
       "argumentHint": "[profile-name]",
       "path": "skills/use-cache/SKILL.md"
     },
+    {
+      "name": "ux-architecture",
+      "description": "Architect a Rango app so navigation is instant and stable — when a server urls() page or a clientUrls() group wins, where layouts, loaders, Suspense boundaries, revalidate() rules, prefetch, transition(), intercept() modals and actions go, with worked recipes (shop, dashboard tabs, settings forms, search filters, a modal over a list) and the anti-patterns behind remounts, skeleton flashes and slow clicks. Use when designing or reviewing a Rango app's routing, layout, loading or navigation UX, choosing between urls() and clientUrls(), placing a loader or a boundary, writing revalidate() rules, or debugging a remount, a re-shown fallback or a click that waits.",
+      "argumentHint": "[shop|dashboard|settings|search|modal]",
+      "path": "skills/ux-architecture/SKILL.md"
+    },
     {
       "name": "vercel",
       "description": "Deploy a Rango app to Vercel Functions (Build Output API v3). Use when deploying a Rango app to Vercel, or asking how the router works with Vercel Functions and the Build Output API.",