devcorner: dc-t41 · session dc-s37

Draft for the user's review of the recipes. Also aligns /composability with the user's guidance: it said "Prefer the async form"; it now says default to sync include() and use async for large, rarely visited groups. The four plain-text mentions of ux-architecture (#1134) become /ux-architecture links once both land.

docs(skills): app-structure — concrete urls() layouts for SaaS, multi-app, content and e-commerce apps

Problem

An agent or a developer starting a Rango app finds one skill per primitive (/composability, /router-setup, /client-urls, /host-router, /prerender, /ppr, /middleware, …) and no whole app. The questions they actually have, "where does the auth guard go relative to the clientUrls() group", "what does the root urls.tsx of a dashboard look like", "how do I split marketing, app, admin and docs across hosts", "which pages get ppr and which Prerender", get answered by assembling five skills, and the assembly is where mistakes land: a guard expected to protect actions, a shared loader on a group layout(), a route module that imports the router.

Before and after

Before: a consumer reads /composability for include(), /client-urls for groups, /middleware for guards, and composes a tree, unverified.

After: /app-structure gives the tree, verified end to end:

// src/urls.tsx (recipe 1, abridged)
export const urlpatterns = urls(({ path, layout, include, middleware, loader, revalidate, errorBoundary, notFoundBoundary }) => [
  include("/", marketingPatterns, { name: "marketing" }), // ppr pages
  include("/auth", authUrls, { name: "auth" }), // clientUrls(), outside the guard
  layout(AppShell, () => [
    middleware(requireUser),
    loader(ViewerLoader, () => [revalidate((ctx) => (ctx.isAction() ? ctx.isAction(updateProfile) : undefined))]),
    errorBoundary(AppError),
    notFoundBoundary(AppNotFound),
    include("/onboarding", onboardingUrls, { name: "onboarding" }),
    middleware(requireOnboarded, () => [
      include("/app", appUrls, { name: "app" }),
      include("/settings", settingsUrls, { name: "settings" }),
    ]),
    middleware(requireAdmin, () => [include("/admin", adminUrls, { name: "admin" })]),
  ]),
  include("/api", apiPatterns, { name: "api" }),
  path("/maintenance", MaintenancePage, { name: "maintenance" }),
]);

End-to-end consumer example

skills/app-structure/large-app.md is the full app: file tree, router.tsx (router.use(loadSession), /api/* CSRF guard, optional throw rewrite() maintenance), the guard modules, the server shell and its user-menu loader, every clientUrls() group with its revalidate() predicates, the marketing and API modules, loaders with "use cache" + cacheTag(), actions with updateTag(), out-of-band refresh (refetch(), useRefreshLoaders(), invalidateClientCache()), and the generated files to commit.

Outline

packages/rangojs-router/skills/app-structure/ (2,086 lines):

• SKILL.md (214): not-this-skill-if; recipe picker; the six rules every recipe follows (route tree in its own module, named sync include per section, identity in router.use() and gates in route middleware(), shared chrome in a server layout, data in loaders, generated files); a small app in one module; sync vs async include() (table with measured costs, when async pays, rango generate limits); naming includes (name nested includes through 0.24.2, Nested unnamed include() never matches: its routes answer 404 with no warning #1104); where shared chrome lives; growing an app (6 steps); related skills.
• large-app.md (823): the user's target architecture as the primary recipe. How navigations behave inside vs between groups; file tree; router.tsx; session, guards, fetch-lane guard, maintenance rewrite; root urls.tsx; the server shell; the auth and app groups in full, settings and admin excerpts; marketing (ppr) and API (path.json, CSRF); loaders, caches, actions; prefetch: false with the measured trade-off and rules of thumb; keeping data current (actions + revalidate(), "use cache" tags, refetch() / useRefreshLoaders() / invalidateClientCache(), useRouter().refresh(), keepClientCache()); fetchable loaders guard themselves; names and generated files; placement table; the group layout() loader gap through 0.24.2 (dc-t38) with its workaround; mistakes the shape avoids.
• multi-app.md (280): createHostRouter() with apex, app., admin., docs.; Cloudflare entry and the node/vercel variant; each app's router.tsx/handler.ts/urls.tsx; what is shared and how (components, Document, CSS, theme config, cache store, parent-domain session; theme choice and client caches are not); one TypeScript program per app; the host-override cookie in dev; cross-app links as document navigations (fix(router): swap app shell on cross-router SPA navigation #476 → fix(router): redirect on cross-app navigation so the target document is fully re-established #555), absolute URLs vs reloadDocument + prefetch="none"; deploys.
• content-site.md (333): docs with Prerender + ppr and a Static nav in a parallel slot; a blog with Prerender onDemand + Passthrough, drafts via notFound() (and why not Skip in a refresh); the publish webhook beside the Worker entry; machine routes; locales in the URL.
• e-commerce.md (436): ppr category (typed search, one shell per query, tracking params excluded) and product pages (tagged "use cache" handler output, live loader holes, prefetch: false reviews); the cart as a store-layout loader narrowed to cart actions; per-segment action outcomes; checkout guarded and server-rendered with an external redirect; variants: prerendered products, a clientUrls() shop.

Code-change summary

• New: skills/app-structure/{SKILL.md,large-app.md,multi-app.md,content-site.md,e-commerce.md}.
• skills/rango/SKILL.md: a row in "Structure & routing" and in "Pick a primitive".
• skills/catalog.json: regenerated (node tools/generate-skills-catalog.mjs).
• README.md: one row in "Everything else, when you need it".
• tools/check-docs-api.mjs: the five app-structure files join the guarded docs (404 identifiers verified, up from the previous set).
• tools/check-skills.mjs: /app and /settings added to URL_EXAMPLES (route examples in the recipes).

Verification

Every snippet was written first as a scratch app per recipe, typechecked against the package's built declarations with rango generate route maps, and exercised through @rangojs/router/testing/flight (serveShellRequest, router.prerender()). The final check extracted every full-file code block from the five markdown files over those apps and re-ran tsc and the probes: 5 programs plus 4 per-app programs clean, 25 probe tests passing. Blocks marked "(excerpt)" (settings and admin groups in recipe 1, the site urls in recipe 2) were not extracted; the full versions they abridge are in the scratch apps and typecheck.

Test plan

• node tools/check-skills.mjs: OK, 48 skills.
• node tools/generate-skills-catalog.mjs --check: OK.
• node tools/check-docs-api.mjs: 404 identifiers verified (the five new files included).
• node tools/check-doc-links.mjs: OK.
• node tools/generate-route-types.mjs --check: current (no app sources changed).
• oxfmt --check ., oxlint --deny-warnings: clean.
• Snippet typecheck: every full-file block of the five files, extracted over the scratch apps: tsc clean in 9 programs.
• Probes: 25 serveShellRequest / router.prerender() tests over the extracted snippets pass.
• pnpm run typecheck, pnpm run test:unit:all: not run; no TypeScript source changed (markdown, JSON, two .mjs check scripts).
• E2e: none; docs-only change.

Notes

• ux-architecture links are plain text. The sibling skill (dc-t40) is not on this branch, and the skills guard (pre-commit and CI) rejects a /ux-architecture cross-reference to a missing directory. The four mentions read "the ux-architecture skill"; once dc-t40 lands, switch them to /ux-architecture so the guard checks them (SKILL.md ×3, large-app.md ×1).
• Tension with /composability. That skill says "Prefer the async form for any route group that is a natural, independently-loadable unit". This skill defaults to sync and names when async pays. One of the two should move; follow-up.
• rango generate and an inline root urls(). rango generate src/router.tsx on createRouter({}).routes(urls(({ path }) => [...])) writes a per-module router.gen.ts and no router.named-routes.gen.ts, with no warning (the .routes(({ path }) => [...]) and urls: urlpatterns forms both work). The recipes keep the root tree in urls.tsx, so they are unaffected; worth a ticket.
• G2 and Nested unnamed include() never matches: its routes answer 404 with no warning #1104 are dated ("through 0.24.2"). When 0.24.3 ships the G2 fix and fix(router): nested unnamed include() routes match; dispatch matches through the route trie #1128 merges, trim the two sections.
• Scratch apps and probes: /private/tmp/claude-501/-Users-ivotodorov-Development-vite-rsc/b29807e8-f2f4-4afb-bc0b-4452071e8f6f/scratchpad/skill-structure/ (large-app, multi-app, content-site, shop, small, extract.py, doc-* extractions).

Update 2026-10-13

• G2 (fix(router): a clientUrls() layout() loader is held across its routes and follows its revalidate(), as a server layout's does #1137): a clientUrls() layout() loader is now held on navigation, as on a server layout. The defaults tables and recipes say so, the known gap is removed, and the revalidate(true|false) shorthand (feat(router): revalidate(true) and revalidate(false) shorthand in urls() and clientUrls() #1130) is used.
• Links by name, never by string.
  • Inside a module, link by local name (ctx.reverse(".x"), useReverse(routes) with the module's generated .gen.ts). The module never knows its mount, and mount params (/:accountId/:projectId, /:locale, /:locale?) are filled automatically.
  • Links that cross modules are built on the server and passed down.
  • Hardcoded paths in the recipes are replaced.
  • The rules are verified in research dc-d58.
• Held layouts. A server layout stays held across navigations, its own param included, by design. Param-dependent nav goes in a client component with useReverse(routes), or the layout gets a revalidate() that compares the param.
• Rewrite or redirect: when to use throw rewrite() from middleware (same URL, no round trip), and its limits.