@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.80daa23e

package/skills/migrate-nextjs/backend-host-swap.md

@@ -0,0 +1,120 @@
+# Backend and host swap audit
+
+Use this audit when the Next-to-Rango migration also changes runtime, database,
+or authentication provider. Route parity is not backend parity.
+
+## Contents
+
+- [Choose ownership](#choose-ownership)
+- [Inventory database guarantees](#inventory-database-guarantees)
+- [Replace authorization deliberately](#replace-authorization-deliberately)
+- [Extract shared server services](#extract-shared-server-services)
+- [Keep mutation side effects caller-owned](#keep-mutation-side-effects-caller-owned)
+- [Audit runtime compatibility](#audit-runtime-compatibility)
+- [Plan cutover and rollback](#plan-cutover-and-rollback)
+
+## Choose ownership
+
+Write down which system owns each concern before porting code:
+
+| Concern                     | Existing owner          | Target owner                | Proof required                  |
+| --------------------------- | ----------------------- | --------------------------- | ------------------------------- |
+| session issuance/revocation | auth provider/app       | provider/app                | login, logout, expiry, rotation |
+| tenant authorization        | RLS/service             | DAL/middleware/service      | cross-tenant denial tests       |
+| invariants/atomicity        | DB function/trigger     | DB constraint/batch/service | concurrent mutation tests       |
+| scheduled/background work   | host/provider           | Worker queue/cron/waitUntil | retry/idempotency test          |
+| secrets                     | host env/provider vault | target secret store         | no client bundle leakage        |
+
+Do not let a concern become "application code" without naming the module that
+now enforces it.
+
+## Inventory database guarantees
+
+Search the source database for more than tables:
+
+- row-level security policies and grants;
+- functions/RPCs, triggers, generated columns, views, and extensions;
+- unique/check/foreign-key constraints;
+- transaction isolation, row locks, advisory locks, and sequences;
+- storage objects, realtime subscriptions, and database webhooks.
+
+For each item, choose one target:
+
+1. preserve it in the target database;
+2. replace it with a transaction/batch and application service;
+3. reject the feature as unsupported and surface that product gap.
+
+SQLite/D1 does not provide Postgres RLS, stored procedures, or row-level locking
+semantics. A mechanical schema conversion is therefore incomplete even when
+every table exists.
+
+## Replace authorization deliberately
+
+When RLS disappears, build an actor/tenant-scoped data-access layer. Accept an
+actor and tenant scope at the repository boundary, verify membership/role, and
+perform the data query through that scope. Avoid exporting an unrestricted DB
+handle to page handlers.
+
+Tests must prove denial, not only success:
+
+- a user cannot read another tenant by guessing an ID;
+- a member cannot perform an owner/admin mutation;
+- a revoked session/token fails immediately enough for the product contract;
+- background jobs and webhooks use an explicit service identity;
+- every API/loader/action path reaches the same guard.
+
+## Extract shared server services
+
+Search server-only Next code for self-calls such as `fetch("/api/...")` or a
+fully qualified request back to the same deployment. On Workers that is a real
+subrequest with added latency and another authentication pass. Extract the
+business operation into a plain service function instead:
+
+```typescript
+async function createProposal(db, scope, actor, input) {
+  // validate, authorize, and mutate once
+}
+```
+
+Let the HTTP response route and an MCP/OAuth/server caller each authenticate in
+their own protocol, derive the same scope, and call that function in-process.
+Keep the HTTP route as an auth-and-delegate boundary for external clients, not
+as the unit of reuse inside the Worker.
+
+## Keep mutation side effects caller-owned
+
+Audit low-level mutations for bundled effects such as activity rows, audit
+logs, cache invalidation, emails, and webhooks. A primitive written for a direct
+edit can double-log when a reviewed proposal later composes the same primitive.
+Prefer an atomic mutation with caller-selected effects, or expose an explicit
+option such as `{ logActivity: false }`. Test composed flows for effect counts,
+not only final row state.
+
+## Audit runtime compatibility
+
+For a Node-to-Workers move, search for:
+
+- `node:*` modules, filesystem/process access, native addons, and TCP clients;
+- SDKs whose default HTTP or crypto implementation is Node-only;
+- synchronous crypto APIs and `Buffer`-specific formats;
+- long-running/background work that exceeds `waitUntil`;
+- response buffering that would destroy RSC streaming.
+
+Prefer web standards (`fetch`, `Request`, `Response`, WebCrypto) and provider
+bindings. Test the production bundle in `vite preview`; a successful TypeScript
+check does not prove an SDK runs in workerd.
+
+## Plan cutover and rollback
+
+Define:
+
+1. schema migration order and backfill scripts;
+2. dual-read/write period, if any;
+3. consistency checks and record counts;
+4. auth/session migration or forced reauthentication;
+5. DNS/traffic cutover;
+6. rollback source of truth and the point after which rollback is unsafe.
+
+Run behavior parity in both the old and new applications for protected reads,
+mutations, OAuth/provider callbacks, billing/webhooks, and failure paths. A page
+rendering successfully is not evidence that the backend contract survived.

package/skills/migrate-react-router/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: migrate-react-router
+description: Migrate a React Router v7/v6 project to @rangojs/router. Use when the user asks to "migrate from React Router", "convert React Router to Rango", "replace React Router", "move from Remix to Rango", or has a React Router / Remix app they want to port.
+argument-hint: path-to-react-router-app
+---
+
+# Migrate from React Router to @rangojs/router
+
+Covers React Router v7 (framework mode and library mode), v6, and Remix v2.
+
+## Why Rango
+
+Common reasons to migrate:
+
+- **Server components by default** — move from client-first route rendering to
+  server-first UI and data fetching.
+  See: `/router-setup`, `/route`
+- **Django-style route definition** — `urls()`, `path()`, and `layout()` make
+  the route tree explicit instead of splitting behavior across route modules or
+  router config objects.
+  See: `/route`, `/layout`
+- **Named routes** — reverse URLs by route name instead of repeating path
+  strings in links, redirects, and navigation logic.
+  See: `/links`, `/typesafety`
+- **Clear execution model** — request scope, render scope, segment boundaries,
+  and shared `ctx` behavior are explicit instead of being inferred from route
+  module conventions.
+  See: `/middleware`, `/loader`
+- **Live data layer** — `createLoader()` and `loader()` keep data fresh
+  independently of cached UI. A route can serve cached segments while loaders
+  still resolve live on every request.
+  See: `/loader`, `/caching`, `/cache-guide`
+- **Explicit caching model** — `cache()` DSL, `revalidate()`, `use cache`, and
+  custom cache stores make data and render caching a first-class part of the router.
+  See: `/caching`, `/cache-guide`, `/use-cache`
+- **Build-time rendering** — `Static()` and `Prerender()` provide explicit
+  build-time rendering for routes that benefit from it.
+  See: `/prerender`
+- **Composable route tree** — layouts, includes, middleware, parallels, and
+  intercepts compose directly in the route definition.
+  See: `/composability`, `/parallel`, `/intercept`
+- **Multi-router flexibility** — support multiple routers, domain routing, and
+  more advanced host-routing setups than a single client router tree.
+  See: `/host-router`
+
+## Identify the mode first
+
+React Router v7 has two modes that require different migration paths:
+
+- **Framework mode** (`@react-router/dev` plugin, file-based routing, route module
+  API with `loader`/`action`/`meta`/`headers`/`shouldRevalidate` exports) — this is
+  the Remix successor. Migration involves replacing the route module convention with
+  Rango's `urls()` DSL and server component handlers.
+
+- **Library mode** (`createBrowserRouter` or `<BrowserRouter>`, client-side only) —
+  migration involves moving from client-side routing to server-rendered RSC with the
+  `urls()` DSL.
+
+React Router v6 and Remix v2 follow the same patterns as v7 library mode and
+framework mode respectively.
+
+## Two target shapes: server handlers or clientUrls()
+
+Every RR route lands in one of two Rango shapes — pick per route group, not
+per app (both compose in one `urls()` tree via `include()`):
+
+- **Server handlers** (the default in this guide): the route component becomes
+  a server component, data fetching merges into the handler. This is the shape
+  with the biggest wins — server-first rendering, smaller client bundles — and
+  the right target whenever the component CAN become a server component.
+
+- **`clientUrls()` groups** (`/client-urls`): for route groups whose components
+  are irreducibly hook-heavy client components, this is the mechanical port —
+  the RR route-module shape maps almost 1:1 and nothing changes seat:
+
+  | RR route module                  | clientUrls()                                             |
+  | -------------------------------- | -------------------------------------------------------- |
+  | component (client, hooks)        | stays a client component — no conversion                 |
+  | `loader` (throws `redirect`/404) | `createLoader()` — thrown `redirect()`/`notFound()` kept |
+  | `useLoaderData()`                | `useLoader(Loader)` at the read site, under `<Suspense>` |
+  | `shouldRevalidate` (runs client) | `revalidate()` predicate — ALSO runs in the browser      |
+  | `meta({ data })`                 | `ctx.use(Meta)` push from the loader body                |
+  | `defer` / `Await`                | loaders stream; `<Suspense>` above each read             |
+
+  Note the `shouldRevalidate` row: a server-tree `revalidate()` runs on the
+  server, but a `clientUrls()` predicate runs in the browser with
+  client-computable args — the exact RR semantics. A group ported this way can
+  still be re-migrated to server handlers later, route by route.
+
+Start with server handlers; reach for `clientUrls()` when a route group's
+conversion cost is dominated by rewriting interactive components rather than
+by moving data fetching — or when the group is a **high-navigation-speed
+surface** (dashboard, admin panel, settings): browser-local matching gives
+instant optimistic pending, and browser-run predicates hold data across
+tab/param switches, so transitions are the fastest Rango offers. See
+`/client-urls`.
+
+## Migration Strategy
+
+Work route-by-route, bottom-up. Start with leaf routes, then layouts, then
+loaders/actions. Verify each route works before moving to the next.
+
+## Replace imports, never shim React Router
+
+Do NOT create mock `react-router` modules, Vite aliases, or compatibility
+wrappers (a local `useLoaderData` backed by context, a `Form` that wraps
+`<form>`, a fake `useFetcher`). Shims freeze RR semantics into the app, hide
+unsupported behavior until runtime, and keep the old packages in the dependency
+graph. Replace every `react-router` / `react-router-dom` / `@remix-run/*`
+import at its call site:
+
+| React Router import                           | Replace with                                                                                                         |
+| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `Link`, `NavLink`                             | `Link` from `@rangojs/router/client` (`NavLink` active state via `usePathname()`, see §6)                            |
+| `Outlet`                                      | `Outlet` from `@rangojs/router/client`                                                                               |
+| `useNavigate`                                 | `useRouter()` from `@rangojs/router/client` (see §6)                                                                 |
+| `useLocation`, `useSearchParams`, `useParams` | `usePathname()`, `useSearchParams()` (same `[params, setParams]` tuple), `useParams()` from `@rangojs/router/client` |
+| `useLoaderData`                               | merge the loader into the handler; `useLoader()` for live client data or `clientUrls()` routes (see §3)              |
+| `useActionData`                               | `useActionState` (standard React, see §3)                                                                            |
+| `Form`                                        | `<form action={serverAction}>` with a `"use server"` function (see §3)                                               |
+| `useFetcher`                                  | submits → server actions + `useActionState`/`useOptimistic`; reads → `useLoader()`                                   |
+| `defer` / `Await`                             | `loading()` DSL / plain `<Suspense>` (see §5)                                                                        |
+| `json()`, `redirect()`                        | plain return values; `redirect` from `@rangojs/router`                                                               |
+| `useRouteError`                               | the `error` prop of `errorBoundary()` (see §5)                                                                       |
+
+If an import has no row here and no obvious Rango equivalent, stop and surface
+it to the user — do not mock it to keep the build green.
+
+Done means: `grep -rnE "from ['\"](react-router|@remix-run)" src/ app/` returns
+nothing, and the packages are out of `package.json`.
+
+## Migration steps
+
+Each numbered step's full walkthrough lives in a companion file linked below.
+
+| Step                                                                                                                                           | File                                                                                                   |
+| ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| §1 Project Setup, §2 Route Mapping                                                                                                             | [`./route-mapping.md`](./route-mapping.md)                                                             |
+| §3 Data Fetching (loaders, actions, `useLoaderData`/`useActionData`, `clientLoader`/`clientAction`, `shouldRevalidate`)                        | [`./data-and-actions.md`](./data-and-actions.md)                                                       |
+| §4 Middleware / Route Protection, §5 Loading & Error States, §6 Navigation, §7 Metadata / Head, §8 API / Resource Routes, §9 Theme / Dark Mode | [`./component-migration.md`](./component-migration.md)                                                 |
+| §10 Cloudflare Workers (streaming, dev tooling, deploy)                                                                                        | [`../cloudflare/references/streaming-and-deploy.md`](../cloudflare/references/streaming-and-deploy.md) |
+
+## 11. Key Conceptual Differences
+
+| Concept             | React Router                        | Rango                                  |
+| ------------------- | ----------------------------------- | -------------------------------------- |
+| Rendering           | Client-side by default, SSR opt-in  | Server components by default (RSC)     |
+| Data loading        | `loader()` + `useLoaderData()`      | Direct fetch in server components      |
+| Form actions        | Route-scoped `action()`             | Function-scoped `"use server"`         |
+| Route definition    | File-based or `createBrowserRouter` | `urls()` DSL with `path()`, `layout()` |
+| Middleware          | Not built-in (use loaders)          | `router.use()` + DSL `middleware()`    |
+| Parallel routes     | Not built-in                        | `parallel()` DSL                       |
+| Intercepting routes | Not built-in                        | `intercept()` DSL                      |
+| Caching             | Not built-in                        | `cache()` DSL, `"use cache"`           |
+| Type-safe routes    | Partial (v7 framework mode)         | Full: params, names, href, reverse     |
+
+## Migration Checklist
+
+1. [ ] Set up Vite config with `rango()` plugin
+2. [ ] Create Document component with `<MetaTags />` in head
+3. [ ] Create `router.tsx` with `createRouter()`
+4. [ ] Convert route config / file routes to `urls()` DSL
+5. [ ] Migrate layouts — keep `<Outlet />` (import from `@rangojs/router/client`)
+6. [ ] Merge loaders + components into handler functions (fetch + render in one place)
+7. [ ] Convert React Router actions to `"use server"` functions
+8. [ ] Migrate auth guards from loaders to `router.use()`
+9. [ ] Replace `react-router-dom` Link/navigation with `@rangojs/router/client`
+10. [ ] Convert error boundaries to `errorBoundary()` DSL
+11. [ ] Update metadata to use `Meta` handle + `<MetaTags />`
+12. [ ] Replace custom theme provider with `theme: true` in createRouter (see `/theme`)
+13. [ ] Run `npx rango generate src/` to generate route types
+14. [ ] Verify no shims: `grep -rnE "from ['\"](react-router|@remix-run)" src/ app/`
+        returns nothing, no mock modules or aliases exist, and the packages are
+        out of `package.json`
+
+**Cloudflare Workers (if migrating an RR7-on-Workers app):**
+
+14. [ ] Audit the custom worker entry — the `router.fetch()` response must pass
+        through as a **stream** (`new Response(response.body, response)`); remove
+        any `.text()`/`.arrayBuffer()`/`HTMLRewriter` buffering from the Rango
+        path (keep it only on legacy/proxy branches). See §10a.
+15. [ ] Switch local dev to `vite dev` / `vite preview` (they stream + load
+        `.dev.vars` + provide bindings); stop using `wrangler dev` for local
+        verification — it gzip-buffers and kills streaming. See §10b.
+16. [ ] Move build output paths from RR7's `build/` to vite's `dist/` in
+        `wrangler.toml` (`assets` → `./dist/client/`) and cleanup scripts. See §10d.
+17. [ ] Fix deploy to use the built config `dist/<env>/wrangler.json`
+        (`no_bundle: true`), not a root `wrangler deploy` against the source
+        worker entry (which can't bundle Rango's virtual modules). See §10e.

package/skills/migrate-react-router/component-migration.md

@@ -0,0 +1,201 @@
+# Middleware, Loading States, Navigation, Metadata, API Routes, and Theming
+
+## 4. Middleware / Route Protection
+
+React Router doesn't have built-in middleware. Protection is typically done in loaders:
+
+```typescript
+// React Router: auth check in loader
+export async function loader({ request }) {
+  const user = await getUser(request);
+  if (!user) throw redirect("/login");
+  return { user };
+}
+
+// Rango: router.use() for request-level auth
+const router = createRouter({})
+  .use(authInit) // all routes — resolves session
+  .use("/dashboard/*", requireAuth) // scoped guard
+  .routes(urlpatterns);
+```
+
+Use `router.use()` for auth guards (wraps entire request including actions).
+Use DSL `middleware()` for render-level concerns (context shaping, headers).
+See `/middleware`.
+
+## 5. Loading & Error States
+
+### Loading / Suspense
+
+```typescript
+// React Router: defer() + Suspense, or HydrateFallback
+export async function loader() {
+  return defer({ data: fetchData() });
+}
+
+// Rango: loading() DSL for automatic Suspense boundaries
+path("/dashboard", DashboardPage, { name: "dashboard" }, () => [
+  loading(<DashboardSkeleton />),
+])
+```
+
+### Error boundaries
+
+```typescript
+// React Router:
+{ path: "dashboard", element: <Dashboard />, errorElement: <ErrorPage /> }
+
+// or with ErrorBoundary component:
+function ErrorBoundary() {
+  const error = useRouteError();
+  return <div>Error: {error.message}</div>;
+}
+
+// Rango: errorBoundary() wrapping a group of routes
+// Server-side error boundaries only receive `error` (no `reset` — server render
+// cannot be retried; users can navigate away or refresh).
+layout(<DashboardLayout />, () => [
+  errorBoundary(({ error }) => (
+    <div>
+      <h2>Something went wrong</h2>
+      <p>{error.message}</p>
+    </div>
+  )),
+  path("/dashboard", DashboardIndex, { name: "dashboard" }),
+  path("/dashboard/settings", Settings, { name: "settings" }),
+])
+```
+
+### Not found
+
+```typescript
+// React Router: { path: "*", element: <NotFound /> }
+
+// Rango (app-level):
+createRouter({
+  notFound: ({ pathname }) => <NotFoundPage pathname={pathname} />,
+})
+
+// Rango (route-level — catches notFound() thrown in handlers/loaders):
+layout(<ShopLayout />, () => [
+  notFoundBoundary(<ProductNotFound />),
+  path("/product/:slug", ProductPage, { name: "product" }),
+])
+```
+
+## 6. Navigation
+
+| React Router                              | Rango                                                                                                                                                                    |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `import { Link } from "react-router-dom"` | `import { Link } from "@rangojs/router/client"`                                                                                                                          |
+| `<Link to="/about">`                      | `<Link to="/about">`                                                                                                                                                     |
+| `useNavigate()`                           | `useRouter()` from `@rangojs/router/client`                                                                                                                              |
+| `navigate("/about")`                      | `useRouter().push("/about")`                                                                                                                                             |
+| `navigate("/about", { replace: true })`   | `useRouter().replace("/about")`                                                                                                                                          |
+| `navigate(-1)`                            | `useRouter().back()`                                                                                                                                                     |
+| `useLocation().pathname`                  | `usePathname()` from `@rangojs/router/client`                                                                                                                            |
+| `useSearchParams()`                       | `useSearchParams()` from `@rangojs/router/client` — same `[params, setParams]` tuple; setter replaces the whole search string, options `{ replace, scroll, revalidate }` |
+| `useParams()`                             | `useParams()` from `@rangojs/router/client` (or `ctx.params` in server handlers)                                                                                         |
+| `useParams<T>()`                          | `useParams<T>()` — same generic annotation pattern                                                                                                                       |
+| `<NavLink>`                               | `<Link>` with `usePathname()` for active state                                                                                                                           |
+
+### useNavigate → useRouter
+
+```typescript
+// React Router:
+const navigate = useNavigate();
+navigate("/dashboard");
+navigate(-1);
+
+// Rango:
+const router = useRouter();
+router.push("/dashboard");
+router.back();
+```
+
+## 7. Metadata / Head
+
+```typescript
+// React Router: meta function export (framework mode)
+export function meta() {
+  return [{ title: "Home" }, { name: "description", content: "Welcome" }];
+}
+
+// Rango: Meta handle in server handlers
+import { Meta } from "@rangojs/router";
+
+const HomePage: Handler<"home"> = (ctx) => {
+  const meta = ctx.use(Meta);
+  meta({ title: "Home" });
+  meta({ name: "description", content: "Welcome" });
+  return <div>Home page</div>;
+};
+```
+
+RR's data-derived `meta({ data })` maps to the same push from the LOADER that
+owns the data — `ctx.use(Meta)({ title: data.name })` in the loader body, with
+`loader(Def, { ssr: false })` when the title must be in the SSR'd
+head. See `/loader` → "Writing Handles from Loaders".
+
+Add `<MetaTags />` in the Document component's `<head>`:
+
+```typescript
+import { MetaTags } from "@rangojs/router/client";
+
+function Document({ children }: { children: ReactNode }) {
+  return (
+    <html>
+      <head>
+        <MetaTags />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+## 8. API / Resource Routes
+
+```typescript
+// React Router (framework mode):
+// app/routes/api.users.ts
+export async function loader() {
+  return Response.json(await getUsers());
+}
+
+// Rango: response routes
+path.json(
+  "/api/users",
+  async () => {
+    return await getUsers();
+  },
+  { name: "apiUsers" },
+);
+```
+
+See `/response-routes` for `path.json()`, `path.text()`, `path.html()`, etc.
+
+## 9. Theme / Dark Mode
+
+Rango has a built-in theme system with FOUC prevention. If the React Router app
+uses a custom theme provider or `next-themes`, replace it with Rango's theme API:
+
+```typescript
+const router = createRouter({
+  theme: true, // or { defaultTheme: "system", attribute: "class" }
+});
+```
+
+Client components use `useTheme()` to read and toggle:
+
+```typescript
+"use client";
+import { useTheme } from "@rangojs/router/theme";
+
+function ThemeToggle() {
+  const { theme, setTheme } = useTheme();
+  return <button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>{theme}</button>;
+}
+```
+
+See `/theme` for full API including system detection and cookie persistence.