@rangojs/router 0.0.0-experimental.20 → 0.0.0-experimental.204030a9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +4 -0
- package/README.md +242 -55
- package/dist/bin/rango.js +277 -99
- package/dist/vite/index.js +2929 -1132
- package/dist/vite/index.js.bak +5448 -0
- package/dist/vite/plugins/cloudflare-protocol-loader-hook.mjs +76 -0
- package/package.json +68 -21
- package/skills/breadcrumbs/SKILL.md +252 -0
- package/skills/bundle-analysis/SKILL.md +159 -0
- package/skills/cache-guide/SKILL.md +243 -21
- package/skills/caching/SKILL.md +159 -10
- package/skills/composability/SKILL.md +27 -2
- package/skills/document-cache/SKILL.md +78 -55
- package/skills/handler-use/SKILL.md +364 -0
- package/skills/hooks/SKILL.md +262 -51
- package/skills/host-router/SKILL.md +243 -0
- package/skills/i18n/SKILL.md +276 -0
- package/skills/intercept/SKILL.md +46 -4
- package/skills/layout/SKILL.md +28 -7
- package/skills/links/SKILL.md +249 -17
- package/skills/loader/SKILL.md +291 -31
- package/skills/middleware/SKILL.md +49 -12
- package/skills/migrate-nextjs/SKILL.md +562 -0
- package/skills/migrate-react-router/SKILL.md +769 -0
- package/skills/mime-routes/SKILL.md +27 -0
- package/skills/observability/SKILL.md +137 -0
- package/skills/parallel/SKILL.md +197 -6
- package/skills/prerender/SKILL.md +125 -102
- package/skills/rango/SKILL.md +242 -23
- package/skills/react-compiler/SKILL.md +168 -0
- package/skills/response-routes/SKILL.md +66 -9
- package/skills/route/SKILL.md +91 -8
- package/skills/router-setup/SKILL.md +98 -8
- package/skills/server-actions/SKILL.md +751 -0
- package/skills/streams-and-websockets/SKILL.md +283 -0
- package/skills/testing/SKILL.md +511 -188
- package/skills/typesafety/SKILL.md +354 -50
- package/skills/use-cache/SKILL.md +34 -5
- package/skills/view-transitions/SKILL.md +294 -0
- package/src/__augment-tests__/augment.ts +81 -0
- package/src/__augment-tests__/augmented.check.ts +117 -0
- package/src/__internal.ts +92 -0
- package/src/browser/action-coordinator.ts +53 -36
- package/src/browser/app-shell.ts +52 -0
- package/src/browser/app-version.ts +14 -0
- package/src/browser/event-controller.ts +91 -70
- package/src/browser/history-state.ts +21 -0
- package/src/browser/index.ts +3 -3
- package/src/browser/link-interceptor.ts +4 -0
- package/src/browser/navigation-bridge.ts +183 -18
- package/src/browser/navigation-client.ts +187 -57
- package/src/browser/navigation-store.ts +75 -17
- package/src/browser/navigation-transaction.ts +21 -37
- package/src/browser/partial-update.ts +143 -40
- package/src/browser/prefetch/cache.ts +275 -28
- package/src/browser/prefetch/fetch.ts +191 -46
- package/src/browser/prefetch/policy.ts +6 -0
- package/src/browser/prefetch/queue.ts +123 -20
- package/src/browser/prefetch/resource-ready.ts +77 -0
- package/src/browser/rango-state.ts +53 -13
- package/src/browser/react/Link.tsx +98 -14
- package/src/browser/react/NavigationProvider.tsx +110 -33
- package/src/browser/react/context.ts +7 -2
- package/src/browser/react/filter-segment-order.ts +51 -7
- package/src/browser/react/index.ts +3 -0
- package/src/browser/react/location-state-shared.ts +175 -4
- package/src/browser/react/location-state.ts +39 -13
- package/src/browser/react/use-handle.ts +23 -64
- package/src/browser/react/use-navigation.ts +22 -2
- package/src/browser/react/use-params.ts +20 -8
- package/src/browser/react/use-reverse.ts +106 -0
- package/src/browser/react/use-router.ts +43 -10
- package/src/browser/react/use-segments.ts +11 -8
- package/src/browser/response-adapter.ts +25 -0
- package/src/browser/rsc-router.tsx +200 -75
- package/src/browser/scroll-restoration.ts +46 -39
- package/src/browser/segment-reconciler.ts +36 -9
- package/src/browser/segment-structure-assert.ts +2 -2
- package/src/browser/server-action-bridge.ts +31 -36
- package/src/browser/types.ts +81 -5
- package/src/build/collect-fallback-refs.ts +107 -0
- package/src/build/generate-manifest.ts +65 -40
- package/src/build/generate-route-types.ts +5 -0
- package/src/build/index.ts +2 -0
- package/src/build/route-trie.ts +69 -26
- package/src/build/route-types/codegen.ts +4 -4
- package/src/build/route-types/include-resolution.ts +9 -2
- package/src/build/route-types/per-module-writer.ts +7 -4
- package/src/build/route-types/router-processing.ts +278 -88
- package/src/build/route-types/scan-filter.ts +9 -2
- package/src/build/route-types/source-scan.ts +118 -0
- package/src/build/runtime-discovery.ts +9 -20
- package/src/cache/cache-runtime.ts +15 -11
- package/src/cache/cache-scope.ts +76 -49
- package/src/cache/cf/cf-cache-store.ts +501 -18
- package/src/cache/cf/index.ts +5 -1
- package/src/cache/document-cache.ts +17 -7
- package/src/cache/index.ts +1 -0
- package/src/cache/taint.ts +55 -0
- package/src/client.rsc.tsx +5 -1
- package/src/client.tsx +95 -284
- package/src/context-var.ts +72 -2
- package/src/debug.ts +2 -2
- package/src/decode-loader-results.ts +36 -0
- package/src/errors.ts +30 -1
- package/src/handle.ts +65 -12
- package/src/handles/breadcrumbs.ts +66 -0
- package/src/handles/index.ts +1 -0
- package/src/host/index.ts +2 -5
- package/src/host/router.ts +129 -57
- package/src/host/types.ts +31 -2
- package/src/host/utils.ts +1 -1
- package/src/href-client.ts +140 -20
- package/src/index.rsc.ts +15 -40
- package/src/index.ts +92 -76
- package/src/loader-store.ts +500 -0
- package/src/loader.rsc.ts +2 -5
- package/src/loader.ts +3 -10
- package/src/missing-id-error.ts +68 -0
- package/src/outlet-context.ts +1 -1
- package/src/prerender/store.ts +57 -15
- package/src/prerender.ts +141 -80
- package/src/response-utils.ts +37 -0
- package/src/reverse.ts +65 -15
- package/src/route-content-wrapper.tsx +6 -28
- package/src/route-definition/dsl-helpers.ts +435 -260
- package/src/route-definition/helper-factories.ts +29 -139
- package/src/route-definition/helpers-types.ts +110 -34
- package/src/route-definition/index.ts +3 -3
- package/src/route-definition/redirect.ts +11 -3
- package/src/route-definition/resolve-handler-use.ts +155 -0
- package/src/route-definition/use-item-types.ts +32 -0
- package/src/route-map-builder.ts +7 -1
- package/src/route-types.ts +37 -41
- package/src/router/basename.ts +14 -0
- package/src/router/content-negotiation.ts +113 -1
- package/src/router/error-handling.ts +1 -1
- package/src/router/find-match.ts +4 -2
- package/src/router/handler-context.ts +105 -39
- package/src/router/intercept-resolution.ts +15 -22
- package/src/router/lazy-includes.ts +12 -9
- package/src/router/loader-resolution.ts +175 -23
- package/src/router/logging.ts +5 -2
- package/src/router/manifest.ts +31 -16
- package/src/router/match-api.ts +129 -193
- package/src/router/match-handlers.ts +63 -20
- package/src/router/match-middleware/background-revalidation.ts +30 -2
- package/src/router/match-middleware/cache-lookup.ts +136 -106
- package/src/router/match-middleware/cache-store.ts +54 -10
- package/src/router/match-middleware/intercept-resolution.ts +9 -7
- package/src/router/match-middleware/segment-resolution.ts +61 -5
- package/src/router/match-result.ts +124 -18
- package/src/router/metrics.ts +239 -14
- package/src/router/middleware-types.ts +61 -31
- package/src/router/middleware.ts +226 -124
- package/src/router/navigation-snapshot.ts +182 -0
- package/src/router/pattern-matching.ts +118 -19
- package/src/router/prerender-match.ts +114 -10
- package/src/router/preview-match.ts +32 -102
- package/src/router/request-classification.ts +286 -0
- package/src/router/revalidation.ts +85 -9
- package/src/router/route-snapshot.ts +245 -0
- package/src/router/router-context.ts +6 -1
- package/src/router/router-interfaces.ts +91 -29
- package/src/router/router-options.ts +89 -19
- package/src/router/router-registry.ts +2 -5
- package/src/router/segment-resolution/fresh.ts +240 -23
- package/src/router/segment-resolution/helpers.ts +30 -25
- package/src/router/segment-resolution/loader-cache.ts +1 -0
- package/src/router/segment-resolution/revalidation.ts +483 -289
- package/src/router/segment-resolution/view-transition-default.ts +36 -0
- package/src/router/segment-wrappers.ts +2 -0
- package/src/router/substitute-pattern-params.ts +56 -0
- package/src/router/telemetry.ts +99 -0
- package/src/router/trie-matching.ts +38 -15
- package/src/router/types.ts +9 -0
- package/src/router/url-params.ts +49 -0
- package/src/router.ts +120 -32
- package/src/rsc/handler-context.ts +2 -2
- package/src/rsc/handler.ts +524 -370
- package/src/rsc/helpers.ts +91 -43
- package/src/rsc/index.ts +1 -21
- package/src/rsc/loader-fetch.ts +23 -3
- package/src/rsc/manifest-init.ts +5 -1
- package/src/rsc/origin-guard.ts +28 -10
- package/src/rsc/progressive-enhancement.ts +39 -10
- package/src/rsc/response-route-handler.ts +46 -53
- package/src/rsc/rsc-rendering.ts +69 -89
- package/src/rsc/runtime-warnings.ts +9 -10
- package/src/rsc/server-action.ts +39 -47
- package/src/rsc/ssr-setup.ts +144 -0
- package/src/rsc/types.ts +19 -3
- package/src/search-params.ts +20 -17
- package/src/segment-content-promise.ts +67 -0
- package/src/segment-loader-promise.ts +122 -0
- package/src/segment-system.tsx +219 -67
- package/src/serialize.ts +243 -0
- package/src/server/context.ts +285 -63
- package/src/server/cookie-store.ts +28 -4
- package/src/server/handle-store.ts +19 -0
- package/src/server/loader-registry.ts +9 -8
- package/src/server/request-context.ts +228 -65
- package/src/server.ts +6 -0
- package/src/ssr/index.tsx +9 -1
- package/src/static-handler.ts +19 -7
- package/src/testing/cache-status.ts +166 -0
- package/src/testing/collect-handle.ts +63 -0
- package/src/testing/dispatch.ts +440 -0
- package/src/testing/dom.entry.ts +22 -0
- package/src/testing/e2e/fixture.ts +154 -0
- package/src/testing/e2e/index.ts +149 -0
- package/src/testing/e2e/matchers.ts +51 -0
- package/src/testing/e2e/page-helpers.ts +272 -0
- package/src/testing/e2e/parity.ts +306 -0
- package/src/testing/e2e/server.ts +183 -0
- package/src/testing/flight-matchers.ts +104 -0
- package/src/testing/flight-runtime.d.ts +21 -0
- package/src/testing/flight.entry.ts +22 -0
- package/src/testing/flight.ts +182 -0
- package/src/testing/generated-routes.ts +223 -0
- package/src/testing/index.ts +98 -0
- package/src/testing/internal/context.ts +151 -0
- package/src/testing/render-route.tsx +536 -0
- package/src/testing/run-loader.ts +296 -0
- package/src/testing/run-middleware.ts +170 -0
- package/src/testing/vitest-stubs/cloudflare-email.ts +9 -0
- package/src/testing/vitest-stubs/cloudflare-workers.ts +21 -0
- package/src/testing/vitest-stubs/plugin-rsc.ts +16 -0
- package/src/testing/vitest-stubs/version.ts +5 -0
- package/src/testing/vitest.ts +112 -0
- package/src/theme/index.ts +4 -13
- package/src/types/cache-types.ts +4 -4
- package/src/types/global-namespace.ts +39 -26
- package/src/types/handler-context.ts +197 -79
- package/src/types/index.ts +1 -0
- package/src/types/loader-types.ts +41 -15
- package/src/types/request-scope.ts +126 -0
- package/src/types/route-config.ts +17 -8
- package/src/types/route-entry.ts +19 -1
- package/src/types/segments.ts +37 -6
- package/src/urls/include-helper.ts +34 -67
- package/src/urls/index.ts +0 -3
- package/src/urls/path-helper-types.ts +50 -9
- package/src/urls/path-helper.ts +63 -63
- package/src/urls/pattern-types.ts +48 -19
- package/src/urls/response-types.ts +25 -22
- package/src/urls/type-extraction.ts +26 -116
- package/src/urls/urls-function.ts +1 -5
- package/src/use-loader.tsx +487 -44
- package/src/vite/debug.ts +185 -0
- package/src/vite/discovery/bundle-postprocess.ts +63 -91
- package/src/vite/discovery/discover-routers.ts +106 -53
- package/src/vite/discovery/discovery-errors.ts +194 -0
- package/src/vite/discovery/gate-state.ts +171 -0
- package/src/vite/discovery/prerender-collection.ts +222 -107
- package/src/vite/discovery/route-types-writer.ts +40 -84
- package/src/vite/discovery/self-gen-tracking.ts +27 -1
- package/src/vite/discovery/state.ts +50 -13
- package/src/vite/discovery/virtual-module-codegen.ts +13 -23
- package/src/vite/index.ts +10 -3
- package/src/vite/plugin-types.ts +111 -72
- package/src/vite/plugins/cjs-to-esm.ts +8 -7
- package/src/vite/plugins/client-ref-dedup.ts +16 -0
- package/src/vite/plugins/client-ref-hashing.ts +28 -5
- package/src/vite/plugins/cloudflare-protocol-loader-hook.d.mts +23 -0
- package/src/vite/plugins/cloudflare-protocol-loader-hook.mjs +76 -0
- package/src/vite/plugins/cloudflare-protocol-stub.ts +214 -0
- package/src/vite/plugins/expose-action-id.ts +55 -33
- package/src/vite/plugins/expose-id-utils.ts +24 -8
- package/src/vite/plugins/expose-ids/export-analysis.ts +100 -20
- package/src/vite/plugins/expose-ids/handler-transform.ts +12 -35
- package/src/vite/plugins/expose-ids/loader-transform.ts +3 -5
- package/src/vite/plugins/expose-ids/router-transform.ts +20 -3
- package/src/vite/plugins/expose-internal-ids.ts +544 -317
- package/src/vite/plugins/performance-tracks.ts +92 -0
- package/src/vite/plugins/refresh-cmd.ts +127 -0
- package/src/vite/plugins/use-cache-transform.ts +65 -50
- package/src/vite/plugins/version-injector.ts +39 -23
- package/src/vite/plugins/version-plugin.ts +72 -3
- package/src/vite/plugins/virtual-entries.ts +2 -2
- package/src/vite/rango.ts +265 -226
- package/src/vite/router-discovery.ts +924 -137
- package/src/vite/utils/ast-handler-extract.ts +15 -15
- package/src/vite/utils/banner.ts +4 -4
- package/src/vite/utils/bundle-analysis.ts +4 -2
- package/src/vite/utils/client-chunks.ts +190 -0
- package/src/vite/utils/forward-user-plugins.ts +193 -0
- package/src/vite/utils/manifest-utils.ts +21 -5
- package/src/vite/utils/package-resolution.ts +41 -1
- package/src/vite/utils/prerender-utils.ts +98 -5
- package/src/vite/utils/shared-utils.ts +109 -27
- package/src/browser/action-response-classifier.ts +0 -99
- package/src/route-definition/route-function.ts +0 -119
package/skills/loader/SKILL.md
CHANGED
|
@@ -6,7 +6,10 @@ argument-hint: [loader]
|
|
|
6
6
|
|
|
7
7
|
# Data Loaders with loader()
|
|
8
8
|
|
|
9
|
-
Loaders fetch data on the server and stream it to the client.
|
|
9
|
+
Loaders fetch data on the server and stream it to the client. For mutations
|
|
10
|
+
(writes triggered by forms or buttons), use server actions instead — see
|
|
11
|
+
`/server-actions`. Loaders re-resolve after an action runs, so the typical
|
|
12
|
+
flow is _action mutates → loader re-reads → UI updates_.
|
|
10
13
|
|
|
11
14
|
## Creating a Loader
|
|
12
15
|
|
|
@@ -65,19 +68,10 @@ export const urlpatterns = urls(({ path, loader }) => [
|
|
|
65
68
|
|
|
66
69
|
## Consuming Loader Data
|
|
67
70
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
import { ProductLoader } from "./loaders/product";
|
|
73
|
-
|
|
74
|
-
async function ProductPage() {
|
|
75
|
-
const { product } = await useLoader(ProductLoader);
|
|
76
|
-
return <h1>{product.name}</h1>;
|
|
77
|
-
}
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
### In Client Components
|
|
71
|
+
Register loaders with `loader()` in the DSL and consume them in client
|
|
72
|
+
components with `useLoader()`. This is the recommended pattern — it keeps
|
|
73
|
+
data fetching on the server and consumption on the client, with a clean
|
|
74
|
+
separation that works correctly with `cache()`.
|
|
81
75
|
|
|
82
76
|
```typescript
|
|
83
77
|
"use client";
|
|
@@ -90,9 +84,101 @@ function ProductDetails() {
|
|
|
90
84
|
}
|
|
91
85
|
```
|
|
92
86
|
|
|
87
|
+
```typescript
|
|
88
|
+
// Route definition — loader() registration required
|
|
89
|
+
path("/product/:slug", ProductPage, { name: "product" }, () => [
|
|
90
|
+
loader(ProductLoader),
|
|
91
|
+
]);
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
> **Client refresh `key` vs. server `cache({ key })` vs. `revalidate()`.** Three
|
|
95
|
+
> different "what refreshes" knobs that are easy to confuse:
|
|
96
|
+
>
|
|
97
|
+
> - `useLoader(Loader, { key })` / `useFetchLoader(Loader, { key })` — a
|
|
98
|
+
> **client** refresh identity. It groups which mounted reads of one loader
|
|
99
|
+
> refresh together when one calls `load()`. It never touches the server
|
|
100
|
+
> request. For refreshing **different** loaders together, tag them with
|
|
101
|
+
> `{ refreshGroup }` (one name or several) and call `useRefreshLoaders()(name)`
|
|
102
|
+
> (plain GET only). See the hooks skill ("Scoping refetch with a `key`" and
|
|
103
|
+
> "Refreshing multiple loaders together").
|
|
104
|
+
> - `cache({ key })` — a **server** cache identity (storage hit/miss/ttl/swr).
|
|
105
|
+
> - `revalidate()` — which **server** segments/loaders recompute during
|
|
106
|
+
> navigation and action refreshes.
|
|
107
|
+
|
|
108
|
+
DSL loaders are the **live data layer** — they resolve fresh on every
|
|
109
|
+
request, even when the route is inside a `cache()` boundary. The router
|
|
110
|
+
excludes them from the segment cache at storage time and re-resolves them
|
|
111
|
+
on retrieval. This means `cache()` gives you cached UI + fresh data by
|
|
112
|
+
default.
|
|
113
|
+
|
|
114
|
+
### Cache safety
|
|
115
|
+
|
|
116
|
+
DSL loaders can safely read `createVar({ cache: false })` variables
|
|
117
|
+
because they are always resolved fresh. The read guard is bypassed for
|
|
118
|
+
loader functions — they never produce stale data.
|
|
119
|
+
|
|
120
|
+
### ctx.use(Loader) — escape hatch
|
|
121
|
+
|
|
122
|
+
For cases where you need loader data in the server handler itself (e.g.,
|
|
123
|
+
to set ctx variables or make routing decisions), use `ctx.use(Loader)`:
|
|
124
|
+
|
|
125
|
+
```typescript
|
|
126
|
+
path("/product/:slug", async (ctx) => {
|
|
127
|
+
const { product } = await ctx.use(ProductLoader);
|
|
128
|
+
ctx.set(Product, product); // make available to children
|
|
129
|
+
return <ProductPage />;
|
|
130
|
+
}, { name: "product" }, () => [
|
|
131
|
+
loader(ProductLoader), // still register for client consumption
|
|
132
|
+
])
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
When you register with `loader()` in the DSL, `ctx.use()` returns the
|
|
136
|
+
same memoized result — loaders never run twice per request.
|
|
137
|
+
|
|
138
|
+
**Limitations of ctx.use(Loader):**
|
|
139
|
+
|
|
140
|
+
- The handler output depends on the loader data. If the route is inside
|
|
141
|
+
`cache()`, the handler is cached with the loader result baked in —
|
|
142
|
+
defeating the live data guarantee.
|
|
143
|
+
- Non-cacheable variable reads (`createVar({ cache: false })`) inside the
|
|
144
|
+
handler still throw, even if the data came from a loader.
|
|
145
|
+
- Prefer DSL `loader()` + client `useLoader()` for data that depends on
|
|
146
|
+
non-cacheable context variables.
|
|
147
|
+
|
|
148
|
+
**Never use `useLoader()` in server components** — it is a client-only API.
|
|
149
|
+
|
|
150
|
+
### Summary
|
|
151
|
+
|
|
152
|
+
| Pattern | API | Cache-safe | Recommended |
|
|
153
|
+
| ---------------------- | ------------------- | ---------- | ----------- |
|
|
154
|
+
| DSL + client component | `useLoader(Loader)` | Yes | Yes |
|
|
155
|
+
| Handler escape hatch | `ctx.use(Loader)` | No | When needed |
|
|
156
|
+
|
|
93
157
|
## Loader Context
|
|
94
158
|
|
|
95
|
-
Loaders receive the same context as route handlers
|
|
159
|
+
Loaders receive the same context shape as route handlers.
|
|
160
|
+
|
|
161
|
+
### Full field surface
|
|
162
|
+
|
|
163
|
+
| Field | Type | Notes |
|
|
164
|
+
| -------------- | ------------------------------ | --------------------------------------------------------------------------------------------------- |
|
|
165
|
+
| `params` | `TParams` | Merged route + explicit loader params; overridable by fetchable `load({ params })`. |
|
|
166
|
+
| `routeParams` | `Record<string, string>` | Server-trusted route params from URL pattern matching; cannot be overridden. |
|
|
167
|
+
| `request` | `Request` | The incoming `Request` (headers, method, body, `signal` for abort). |
|
|
168
|
+
| `url` | `URL` | Parsed request URL. |
|
|
169
|
+
| `pathname` | `string` | URL pathname (shortcut for `ctx.url.pathname`). |
|
|
170
|
+
| `searchParams` | `URLSearchParams` | Shortcut for `ctx.url.searchParams`. |
|
|
171
|
+
| `search` | `ResolveSearchSchema<TSearch>` | Typed query params when a search schema is declared on the route; `{}` otherwise. |
|
|
172
|
+
| `env` | `TEnv` | Plain bindings from `createRouter<TEnv>()` (DB, KV, secrets, etc.). |
|
|
173
|
+
| `get` | `(key \| ContextVar) => value` | Reads variables/context-vars set by middleware. |
|
|
174
|
+
| `use` | `(loader \| handle) => T` | Access another loader's data (Promise) or a handle's collected data (after `await ctx.rendered()`). |
|
|
175
|
+
| `rendered` | `() => Promise<void>` | **Experimental.** DSL loaders only — waits for non-loader segments before reading handle data. |
|
|
176
|
+
| `method` | `string` | HTTP method. `"GET"` for SSR loader runs; reflects real method for fetchable loaders. |
|
|
177
|
+
| `body` | `TBody \| undefined` | Parsed request body for fetchable POST/PUT/PATCH/DELETE calls. |
|
|
178
|
+
| `formData` | `FormData \| undefined` | Present when a fetchable loader is invoked via form submission. |
|
|
179
|
+
| `reverse` | `ScopedReverseFunction` | Generate type-checked URLs from route names (same scoped semantics as route handlers). |
|
|
180
|
+
|
|
181
|
+
### Example
|
|
96
182
|
|
|
97
183
|
```typescript
|
|
98
184
|
export const ProductLoader = createLoader(async (ctx) => {
|
|
@@ -113,13 +199,24 @@ export const ProductLoader = createLoader(async (ctx) => {
|
|
|
113
199
|
// Request headers
|
|
114
200
|
const auth = ctx.request.headers.get("Authorization");
|
|
115
201
|
|
|
116
|
-
// Variables set by middleware (from
|
|
202
|
+
// Variables set by middleware (from Rango.Vars augmentation)
|
|
117
203
|
const user = ctx.get("user");
|
|
118
204
|
|
|
119
|
-
|
|
205
|
+
// Type-checked URLs for payloads. `.name` resolves within the current
|
|
206
|
+
// include() scope; a bare `name` resolves globally. See /route and
|
|
207
|
+
// /typesafety for scope rules and route-name autocomplete.
|
|
208
|
+
const detailUrl = ctx.reverse(".detail", { slug });
|
|
209
|
+
|
|
210
|
+
return {
|
|
211
|
+
product: await fetchProduct(slug),
|
|
212
|
+
links: { self: detailUrl },
|
|
213
|
+
};
|
|
120
214
|
});
|
|
121
215
|
```
|
|
122
216
|
|
|
217
|
+
See `/route` for the full handler-context contract (shared with loaders) and
|
|
218
|
+
`/typesafety` for route-name typing that powers `ctx.reverse` autocomplete.
|
|
219
|
+
|
|
123
220
|
### params vs routeParams
|
|
124
221
|
|
|
125
222
|
- `ctx.params` — merged route params + explicit loader params. For fetchable
|
|
@@ -161,13 +258,104 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
|
|
|
161
258
|
revalidate(() => false), // Never revalidate
|
|
162
259
|
]),
|
|
163
260
|
|
|
164
|
-
// Loader that revalidates after cart actions
|
|
261
|
+
// Loader that revalidates after cart actions (defer otherwise — keeps the
|
|
262
|
+
// permissive loader defaults for navigation and other actions intact)
|
|
165
263
|
loader(CartLoader, () => [
|
|
166
|
-
revalidate(({ actionId }) => actionId?.includes("Cart")
|
|
264
|
+
revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
|
|
167
265
|
]),
|
|
168
266
|
]);
|
|
169
267
|
```
|
|
170
268
|
|
|
269
|
+
### `revalidate()` return shapes
|
|
270
|
+
|
|
271
|
+
> **Scope: `revalidate()` is a partial-render concern, not a cache concern.**
|
|
272
|
+
> It decides whether a segment (here, a loader) re-runs and streams to the
|
|
273
|
+
> client on a navigation or action — never whether a cached value is stale. The
|
|
274
|
+
> cache decides hit/miss/ttl/swr independently and never reads `revalidate()`.
|
|
275
|
+
> Caching a loader is a separate, opt-in step (`loader(Fn, () => [cache({...})])`).
|
|
276
|
+
> See `/cache-guide` → "Two axes" and `/rango` → "The shape of rango".
|
|
277
|
+
|
|
278
|
+
A `revalidate(fn)` callback can return one of four shapes. The chain
|
|
279
|
+
processes revalidators in order; each call's return controls how the
|
|
280
|
+
chain continues:
|
|
281
|
+
|
|
282
|
+
```typescript
|
|
283
|
+
// 1) Hard decision — short-circuits the chain, used as the final answer.
|
|
284
|
+
revalidate(() => true);
|
|
285
|
+
revalidate(({ actionId }) => actionId?.includes("Cart") ?? false);
|
|
286
|
+
|
|
287
|
+
// 2) Soft decision — updates the running suggestion for downstream
|
|
288
|
+
// revalidators on the same segment, chain continues.
|
|
289
|
+
revalidate(({ defaultShouldRevalidate }) => ({
|
|
290
|
+
defaultShouldRevalidate: !defaultShouldRevalidate,
|
|
291
|
+
}));
|
|
292
|
+
|
|
293
|
+
// 3) Defer (no opinion) — leaves the running suggestion unchanged and
|
|
294
|
+
// continues to the next revalidator. Implicit return / null /
|
|
295
|
+
// undefined are all equivalent and consumer-friendly.
|
|
296
|
+
revalidate(({ actionId }) => {
|
|
297
|
+
if (actionId?.includes("Cart")) return true; // hard for this branch only
|
|
298
|
+
// implicit return — let downstream revalidators or the segment default decide
|
|
299
|
+
});
|
|
300
|
+
revalidate(() => undefined); // explicit defer
|
|
301
|
+
revalidate(() => null); // explicit defer
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
If every revalidator on a segment defers, the segment-type default
|
|
305
|
+
(e.g. params-changed for routes, `false` for parallels) is used.
|
|
306
|
+
|
|
307
|
+
#### `|| undefined` (defer) vs `?? false` (hard) — pick deliberately
|
|
308
|
+
|
|
309
|
+
A boolean return — including `false` — is a **hard** decision: it short-circuits
|
|
310
|
+
the chain and overrides the segment default. `undefined` **defers** to the
|
|
311
|
+
running suggestion / segment default. They are not interchangeable:
|
|
312
|
+
|
|
313
|
+
```typescript
|
|
314
|
+
// Defer: "revalidate on match, otherwise let the default/downstream decide."
|
|
315
|
+
revalidate(({ actionId }) => actionId?.includes("Cart") || undefined);
|
|
316
|
+
|
|
317
|
+
// Hard: "revalidate ONLY on match, suppress everything else."
|
|
318
|
+
revalidate(({ actionId }) => actionId?.includes("Cart") ?? false);
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
This matters most for loaders, whose defaults are permissive: a loader defaults
|
|
322
|
+
to revalidating on **any** action (`POST`) and on **param/search changes**
|
|
323
|
+
during navigation. So `?? false` on a loader silently suppresses both — the
|
|
324
|
+
loader will not refetch when you navigate to a different `:id`. Use
|
|
325
|
+
`|| undefined` when you want to _add_ a revalidation signal on top of the
|
|
326
|
+
sensible defaults, and reserve `?? false` for the rare case where you genuinely
|
|
327
|
+
want the loader to refetch on nothing but your matched action.
|
|
328
|
+
|
|
329
|
+
When **composing multiple revalidators** on one segment (see below), defer is
|
|
330
|
+
mandatory: the first hard `?? false` ends the chain and the later contracts
|
|
331
|
+
never run.
|
|
332
|
+
|
|
333
|
+
#### Matching actions: `ctx.isAction()`
|
|
334
|
+
|
|
335
|
+
To revalidate after specific server actions, match them by **reference** with
|
|
336
|
+
`ctx.isAction()` rather than hand-written `actionId` substrings. A rename or
|
|
337
|
+
moved file then becomes a type error instead of silently failing to match:
|
|
338
|
+
|
|
339
|
+
```typescript
|
|
340
|
+
import { addToCart, removeFromCart } from "../actions/cart";
|
|
341
|
+
import * as CartActions from "../actions/cart";
|
|
342
|
+
|
|
343
|
+
loader(CartLoader, () => [
|
|
344
|
+
revalidate((ctx) => ctx.isAction(addToCart) || undefined), // one action
|
|
345
|
+
]);
|
|
346
|
+
revalidate((ctx) => ctx.isAction(addToCart, removeFromCart) || undefined); // several
|
|
347
|
+
revalidate((ctx) => ctx.isAction(CartActions) || undefined); // any action in the module
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
`isAction()` is a method on the revalidate predicate's **context argument** —
|
|
351
|
+
there is no standalone `isAction` import; you always reach it through the callback
|
|
352
|
+
parameter (`revalidate((ctx) => ctx.isAction(...))`). It returns a raw boolean, so
|
|
353
|
+
pair it with `|| undefined` for the usual "revalidate on match, else defer"
|
|
354
|
+
intent. It returns `false` on plain navigation and on non-matches, and resolves
|
|
355
|
+
the reference the same way the router derives `actionId` (`$id` in production,
|
|
356
|
+
`$$id` in dev), so it matches in both modes. The raw `actionId` string stays
|
|
357
|
+
available on the same context as an escape hatch.
|
|
358
|
+
|
|
171
359
|
### Revalidation Contracts for Loader Dependencies
|
|
172
360
|
|
|
173
361
|
If a loader reads `ctx.get()` data produced by an outer handler/layout, share
|
|
@@ -175,8 +363,12 @@ the same named revalidation contract across producer and consumer segments.
|
|
|
175
363
|
|
|
176
364
|
```typescript
|
|
177
365
|
// revalidation-contracts.ts
|
|
178
|
-
|
|
179
|
-
|
|
366
|
+
import * as AccountActions from "./actions/account";
|
|
367
|
+
|
|
368
|
+
// Match by reference with ctx.isAction() (rename-safe), and defer (|| undefined)
|
|
369
|
+
// so these contracts compose — a hard `false` would short-circuit the rest.
|
|
370
|
+
export const revalidateAccountScope = (ctx) =>
|
|
371
|
+
ctx.isAction(AccountActions) || undefined;
|
|
180
372
|
|
|
181
373
|
layout(AccountLayout, () => [
|
|
182
374
|
revalidate(revalidateAccountScope), // producer reruns
|
|
@@ -219,6 +411,64 @@ follows the same rule: at build time, loaders are skipped entirely (there is no
|
|
|
219
411
|
real request context), and at runtime the worker resolves them fresh against
|
|
220
412
|
the live database.
|
|
221
413
|
|
|
414
|
+
### Parallel and streaming — latency overlaps first paint
|
|
415
|
+
|
|
416
|
+
Loaders do not block the page. As the render pass begins — the pass that route
|
|
417
|
+
middleware wraps, so loaders run right after middleware, not in a later
|
|
418
|
+
phase — every matched loader is kicked off **concurrently** (their promises start in the
|
|
419
|
+
same tick), and each result is **streamed** to the client as its own RSC Flight
|
|
420
|
+
chunk rather than awaited up front. Pair a loader with `loading()` (or a
|
|
421
|
+
client `<Suspense>`) and the shell paints immediately while the data streams in.
|
|
422
|
+
|
|
423
|
+
This is why **"cached UI still pays full data latency" is the wrong intuition**:
|
|
424
|
+
on a `cache()` hit the UI segments stream instantly from cache while the live
|
|
425
|
+
loaders resolve fresh **in parallel** — data latency _overlaps_ first paint
|
|
426
|
+
instead of being added on top of it. (Without a `loading()` / `<Suspense>`
|
|
427
|
+
boundary a parallel loader blocks its parent, so add one to keep the overlap.)
|
|
428
|
+
|
|
429
|
+
If you come from a framework where the loader is a blocking step that runs
|
|
430
|
+
before the response is built, this is the shift to internalize: here the
|
|
431
|
+
response starts streaming first and loader data fills in.
|
|
432
|
+
|
|
433
|
+
### See it: `debugPerformance`
|
|
434
|
+
|
|
435
|
+
Turn on the per-request performance timeline early — it is the fastest way to
|
|
436
|
+
confirm loaders overlap rather than serialize, and to find the real bottleneck
|
|
437
|
+
locally instead of guessing:
|
|
438
|
+
|
|
439
|
+
```typescript
|
|
440
|
+
const router = createRouter({ document: Document, debugPerformance: true });
|
|
441
|
+
```
|
|
442
|
+
|
|
443
|
+
Or enable it per-request from middleware (e.g. only when `?debug` is present) by
|
|
444
|
+
calling `ctx.debugPerformance()` **before** `await next()`. Each HTML request
|
|
445
|
+
then prints a shared-axis waterfall (and emits a `Server-Timing` header):
|
|
446
|
+
|
|
447
|
+
```
|
|
448
|
+
[RSC Perf] GET /product/widget (24.53ms)
|
|
449
|
+
start dur span timeline
|
|
450
|
+
0.08ms 3.20ms route-matching |#####...................................|
|
|
451
|
+
3.40ms 8.70ms ssr-render-html |.....##############.....................|
|
|
452
|
+
3.42ms 11.90ms loader:…#ProductLoader |.....###################................|
|
|
453
|
+
3.45ms 11.40ms loader:…#ReviewsLoader |.....##################.................|
|
|
454
|
+
0.00ms 24.53ms handler:total |########################################|
|
|
455
|
+
```
|
|
456
|
+
|
|
457
|
+
How to read it:
|
|
458
|
+
|
|
459
|
+
- **Humans:** scan the `#` bars on the shared axis. Bars that start at the same
|
|
460
|
+
offset and run side by side are executing **in parallel** — loaders should
|
|
461
|
+
overlap `ssr-render-html` / `render:total`, not sit alone to the right of
|
|
462
|
+
everything. A lone `loader:*` bar past the render bar is serialized latency to
|
|
463
|
+
chase. `handler:total` is the whole request; `render:total` is the render pass.
|
|
464
|
+
- **LLMs / programmatic:** read each row as `{ start, dur, label }`. A loader
|
|
465
|
+
overlaps paint when its `[start, start+dur]` interval intersects
|
|
466
|
+
`render:total` / `ssr-render-html`. Flag a regression when a `loader:*`
|
|
467
|
+
interval is **disjoint from and starts after** `render:total`, or when its
|
|
468
|
+
`dur` approaches `handler:total` — that loader is on the critical path instead
|
|
469
|
+
of overlapping it. Two `loader:*` rows with near-equal `start` confirm
|
|
470
|
+
parallel execution.
|
|
471
|
+
|
|
222
472
|
### Opting a Loader into Caching
|
|
223
473
|
|
|
224
474
|
To cache a specific loader's data, attach a `cache()` child:
|
|
@@ -492,6 +742,13 @@ export const FileUploadLoader = createLoader(async (ctx) => {
|
|
|
492
742
|
|
|
493
743
|
Client usage — see `/hooks useFetchLoader` for the full client-side pattern.
|
|
494
744
|
|
|
745
|
+
> **Refetch sharing**: when the loader is registered on the route via
|
|
746
|
+
> `loader()`, a plain `load()` call (no `params`, no `body`) broadcasts
|
|
747
|
+
> the new value to every component reading the same loader id —
|
|
748
|
+
> `useLoader` reads in layouts, pages, and parallel slots all converge.
|
|
749
|
+
> Calls with `params` or a non-GET method stay local to the call site.
|
|
750
|
+
> See `/hooks` → "Shared refetch behavior" for the full contract.
|
|
751
|
+
|
|
495
752
|
## Complete Example
|
|
496
753
|
|
|
497
754
|
```typescript
|
|
@@ -507,7 +764,7 @@ export const ProductLoader = createLoader(async (ctx) => {
|
|
|
507
764
|
.first();
|
|
508
765
|
|
|
509
766
|
if (!product) {
|
|
510
|
-
|
|
767
|
+
notFound("Product not found");
|
|
511
768
|
}
|
|
512
769
|
|
|
513
770
|
return { product };
|
|
@@ -523,12 +780,11 @@ export const CartLoader = createLoader(async (ctx) => {
|
|
|
523
780
|
return { cart };
|
|
524
781
|
});
|
|
525
782
|
|
|
526
|
-
// urls.tsx
|
|
783
|
+
// urls.tsx — register loaders in the DSL
|
|
527
784
|
export const urlpatterns = urls(({ path, layout, loader, loading, cache, revalidate }) => [
|
|
528
785
|
layout(<ShopLayout />, () => [
|
|
529
|
-
// Shared cart loader for all shop routes
|
|
530
786
|
loader(CartLoader, () => [
|
|
531
|
-
revalidate(({ actionId }) => actionId?.includes("Cart")
|
|
787
|
+
revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
|
|
532
788
|
]),
|
|
533
789
|
|
|
534
790
|
path("/shop/product/:slug", ProductPage, { name: "product" }, () => [
|
|
@@ -538,18 +794,22 @@ export const urlpatterns = urls(({ path, layout, loader, loading, cache, revalid
|
|
|
538
794
|
]),
|
|
539
795
|
]);
|
|
540
796
|
|
|
541
|
-
//
|
|
542
|
-
|
|
797
|
+
// components/ProductDetails.tsx — consume in client component
|
|
798
|
+
"use client";
|
|
799
|
+
import { useLoader } from "@rangojs/router/client";
|
|
543
800
|
import { ProductLoader, CartLoader } from "./loaders/shop";
|
|
544
801
|
|
|
545
|
-
|
|
546
|
-
const { product } =
|
|
547
|
-
const { cart } =
|
|
802
|
+
function ProductDetails() {
|
|
803
|
+
const { data: { product } } = useLoader(ProductLoader);
|
|
804
|
+
const { data: { cart } } = useLoader(CartLoader);
|
|
548
805
|
|
|
549
806
|
return (
|
|
550
807
|
<div>
|
|
551
808
|
<h1>{product.name}</h1>
|
|
552
|
-
<AddToCartButton
|
|
809
|
+
<AddToCartButton
|
|
810
|
+
productId={product.id}
|
|
811
|
+
inCart={cart?.items.includes(product.id)}
|
|
812
|
+
/>
|
|
553
813
|
</div>
|
|
554
814
|
);
|
|
555
815
|
}
|
|
@@ -10,9 +10,6 @@ Middleware runs before/after route handlers using the onion model.
|
|
|
10
10
|
|
|
11
11
|
## Execution Model
|
|
12
12
|
|
|
13
|
-
Canonical semantics reference:
|
|
14
|
-
[docs/execution-model.md](../../docs/internal/execution-model.md)
|
|
15
|
-
|
|
16
13
|
There are two levels of middleware with different execution scopes:
|
|
17
14
|
|
|
18
15
|
### Global middleware (`router.use()`)
|
|
@@ -26,21 +23,32 @@ const router = createRouter<AppEnv>({})
|
|
|
26
23
|
.routes(urlpatterns);
|
|
27
24
|
```
|
|
28
25
|
|
|
26
|
+
When the router has a `basename`, pattern-scoped `.use()` patterns are automatically prefixed. For example, with `basename: "/app"`, `.use("/admin/*", mw)` matches `/app/admin/*`.
|
|
27
|
+
|
|
29
28
|
### Route middleware (`middleware()` in `urls()`)
|
|
30
29
|
|
|
31
30
|
Registered inside `urls()` callback. Wraps **rendering only** -- it does NOT wrap server action execution. Actions run before route middleware, so when route middleware executes during post-action revalidation, it can observe state that the action set (cookies, context variables, headers).
|
|
32
31
|
|
|
32
|
+
> **Implication for auth:** route middleware cannot guard server actions. Use `router.use("/admin/*", requireAuth)` (global, scoped) for action protection, or check inside the action body. See `/server-actions` for action-side auth patterns.
|
|
33
|
+
|
|
33
34
|
```
|
|
34
35
|
Request flow (with action):
|
|
35
|
-
global mw -> action executes -> route mw ->
|
|
36
|
+
global mw -> action executes -> route mw -> render pass
|
|
36
37
|
|
|
37
38
|
Request flow (no action):
|
|
38
|
-
global mw -> route mw ->
|
|
39
|
+
global mw -> route mw -> render pass
|
|
39
40
|
|
|
40
41
|
Progressive enhancement (no-JS form POST):
|
|
41
42
|
global mw -> action executes -> route mw -> full page re-render
|
|
42
43
|
```
|
|
43
44
|
|
|
45
|
+
The **render pass** resolves handler, layouts, parallels, and loaders together —
|
|
46
|
+
it is not a handler-then-loaders sequence. Handler-first ordering is guaranteed
|
|
47
|
+
only between a route handler and its child/orphan layouts and parallels (so
|
|
48
|
+
`ctx.set` is visible); loaders run **concurrently** and stream their results, so
|
|
49
|
+
their latency overlaps rendering rather than blocking it. See `/loader` →
|
|
50
|
+
"Parallel and streaming".
|
|
51
|
+
|
|
44
52
|
The contract is: **route middleware wraps rendering regardless of transport** (JS-enabled RSC stream or no-JS HTML). During PE re-render, route middleware observes action-set state (cookies, context variables) the same way it does during JS-enabled post-action revalidation.
|
|
45
53
|
|
|
46
54
|
Revalidation is still partial. Route middleware wraps the render pass that
|
|
@@ -60,7 +68,7 @@ and consumer segments, even when middleware is present in the chain.
|
|
|
60
68
|
|
|
61
69
|
```typescript
|
|
62
70
|
export const revalidateCartData = ({ actionId }) =>
|
|
63
|
-
actionId?.includes("src/actions/cart.ts#")
|
|
71
|
+
actionId?.includes("src/actions/cart.ts#") || undefined;
|
|
64
72
|
|
|
65
73
|
layout(CartLayout, () => [
|
|
66
74
|
middleware(cartRenderMiddleware),
|
|
@@ -135,17 +143,46 @@ export const urlpatterns = urls(({ path, layout, middleware }) => [
|
|
|
135
143
|
## Middleware with Multiple Handlers
|
|
136
144
|
|
|
137
145
|
```typescript
|
|
138
|
-
//
|
|
146
|
+
// Group multiple middleware in an array
|
|
139
147
|
export const shopMiddleware = [loggerMiddleware, mockAuthMiddleware];
|
|
140
148
|
|
|
141
|
-
// In routes
|
|
149
|
+
// In routes — pass the array directly
|
|
142
150
|
layout(<ShopLayout />, () => [
|
|
143
|
-
middleware(
|
|
151
|
+
middleware(shopMiddleware),
|
|
144
152
|
|
|
145
153
|
path("/shop", ShopIndex, { name: "shop" }),
|
|
146
154
|
])
|
|
147
155
|
```
|
|
148
156
|
|
|
157
|
+
## Wrapping Middleware (Scoped to Children)
|
|
158
|
+
|
|
159
|
+
Use the wrapping form to scope middleware to a subset of routes without
|
|
160
|
+
introducing a visible layout:
|
|
161
|
+
|
|
162
|
+
```typescript
|
|
163
|
+
urls(({ path, middleware }) => [
|
|
164
|
+
// authMw only applies to /admin and /admin/settings
|
|
165
|
+
middleware(authMw, () => [
|
|
166
|
+
path("/admin", AdminPage, { name: "admin" }),
|
|
167
|
+
path("/admin/settings", SettingsPage, { name: "settings" }),
|
|
168
|
+
]),
|
|
169
|
+
|
|
170
|
+
// Public route — no authMw
|
|
171
|
+
path("/", HomePage, { name: "home" }),
|
|
172
|
+
]);
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
Multiple middleware with wrapping:
|
|
176
|
+
|
|
177
|
+
```typescript
|
|
178
|
+
middleware([authMw, loggingMw], () => [
|
|
179
|
+
path("/admin", AdminPage, { name: "admin" }),
|
|
180
|
+
]);
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
This creates a transparent layout (`<Outlet />`) that carries the middleware.
|
|
184
|
+
The middleware does not affect sibling routes outside the callback.
|
|
185
|
+
|
|
149
186
|
## Middleware Context
|
|
150
187
|
|
|
151
188
|
```typescript
|
|
@@ -159,7 +196,7 @@ export const myMiddleware: Middleware = async (ctx, next) => {
|
|
|
159
196
|
ctx.env.DB; // D1Database
|
|
160
197
|
ctx.env.KV; // KVNamespace
|
|
161
198
|
|
|
162
|
-
// Set variables for downstream handlers (typed via
|
|
199
|
+
// Set variables for downstream handlers (typed via Rango.Vars)
|
|
163
200
|
ctx.set("user", { id: "123", name: "John" });
|
|
164
201
|
|
|
165
202
|
// Continue to next middleware/handler
|
|
@@ -200,8 +237,8 @@ const Dashboard: Handler<"dashboard"> = (ctx) => {
|
|
|
200
237
|
```
|
|
201
238
|
|
|
202
239
|
This works alongside `ctx.get("key")` / `ctx.set("key", value)` (global typing
|
|
203
|
-
via
|
|
204
|
-
data; use
|
|
240
|
+
via Rango.Vars augmentation). Use `createVar` for route-local or feature-scoped
|
|
241
|
+
data; use Rango.Vars for app-wide middleware state.
|
|
205
242
|
|
|
206
243
|
## Redirect with State in Middleware
|
|
207
244
|
|