@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/route/SKILL.md
CHANGED
|
@@ -33,6 +33,26 @@ urls(({ path }) => [
|
|
|
33
33
|
]);
|
|
34
34
|
```
|
|
35
35
|
|
|
36
|
+
### Optional URL params at runtime
|
|
37
|
+
|
|
38
|
+
Absent optional params are **omitted from `ctx.params`** — `ctx.params.<name>`
|
|
39
|
+
reads as `undefined`, matching the `RouteParams<"name">` type
|
|
40
|
+
(`{ query?: string }`). Use `??` to default and `=== undefined` to check
|
|
41
|
+
absence:
|
|
42
|
+
|
|
43
|
+
```typescript
|
|
44
|
+
path("/search/:query?", (ctx) => {
|
|
45
|
+
const query = ctx.params.query ?? ""; // works — undefined coalesces
|
|
46
|
+
if (ctx.params.query === undefined) return <EmptySearch />;
|
|
47
|
+
return <Results query={ctx.params.query} />;
|
|
48
|
+
}, { name: "search" });
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
For the common pattern of an optional locale prefix
|
|
52
|
+
(`include("/:locale?", routes)`) and the wider react-intl integration —
|
|
53
|
+
locale detection, fallback chains, URL generation with absent locale —
|
|
54
|
+
see `/i18n`.
|
|
55
|
+
|
|
36
56
|
## Route Handler Patterns
|
|
37
57
|
|
|
38
58
|
### Component Function
|
|
@@ -103,8 +123,8 @@ export const SearchPage: Handler<"search"> = (ctx) => {
|
|
|
103
123
|
```
|
|
104
124
|
|
|
105
125
|
Supported types: `"string"`, `"number"`, `"boolean"`, with `?` suffix for optional.
|
|
106
|
-
|
|
107
|
-
|
|
126
|
+
Missing params are `undefined` regardless of required/optional. The required/optional
|
|
127
|
+
distinction is a consumer-facing contract (for `href()` and `reverse()` autocomplete).
|
|
108
128
|
|
|
109
129
|
Use `RouteSearchParams<"name">` and `RouteParams<"name">` to extract types for props:
|
|
110
130
|
|
|
@@ -181,16 +201,55 @@ String keys still work (`ctx.set("key", value)` / `ctx.get("key")`), but
|
|
|
181
201
|
Only route handlers and middleware can call `ctx.set()`. Layouts, parallels,
|
|
182
202
|
and intercepts can only read via `ctx.get()`.
|
|
183
203
|
|
|
204
|
+
#### Non-cacheable context variables
|
|
205
|
+
|
|
206
|
+
Mark a var as non-cacheable when it holds inherently request-specific data
|
|
207
|
+
(sessions, auth tokens, per-request IDs). There are two ways:
|
|
208
|
+
|
|
209
|
+
```typescript
|
|
210
|
+
// Var-level: every value written to this var is non-cacheable
|
|
211
|
+
const Session = createVar<SessionData>({ cache: false });
|
|
212
|
+
|
|
213
|
+
// Write-level: escalate a normally-cacheable var for this specific write
|
|
214
|
+
const Theme = createVar<string>();
|
|
215
|
+
ctx.set(Theme, userTheme, { cache: false });
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
"Least cacheable wins" — if either the var definition or the write site says
|
|
219
|
+
`cache: false`, the value is non-cacheable.
|
|
220
|
+
|
|
221
|
+
Reading a non-cacheable var inside `cache()` or `"use cache"` throws at
|
|
222
|
+
runtime. This prevents request-specific data from leaking into cached output:
|
|
223
|
+
|
|
224
|
+
```typescript
|
|
225
|
+
// This throws — Session is non-cacheable
|
|
226
|
+
async function CachedWidget(ctx) {
|
|
227
|
+
"use cache";
|
|
228
|
+
const session = ctx.get(Session); // Error: non-cacheable var read inside cache scope
|
|
229
|
+
return <Widget />;
|
|
230
|
+
}
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
Cacheable vars (the default) can be read freely inside cache scopes.
|
|
234
|
+
|
|
184
235
|
### Revalidation Contracts for Handler Data
|
|
185
236
|
|
|
237
|
+
> **Scope: `revalidate()` is a partial-render concern, not a cache concern.**
|
|
238
|
+
> It decides whether this segment re-runs and streams to the client on a
|
|
239
|
+
> navigation or action — never whether a cached value is stale. The cache
|
|
240
|
+
> decides hit/miss/ttl/swr independently and never reads `revalidate()`. See
|
|
241
|
+
> `/cache-guide` → "Two axes" and `/rango` → "The shape of rango".
|
|
242
|
+
|
|
186
243
|
Handler-first guarantees apply within a single full render pass. For partial
|
|
187
244
|
action revalidation, define named revalidation contracts and reuse them on both
|
|
188
245
|
the producer route and the consumer child segments.
|
|
189
246
|
|
|
190
247
|
```typescript
|
|
191
248
|
// revalidation-contracts.ts
|
|
249
|
+
// Defer (|| undefined), not ?? false: a hard `false` short-circuits the chain,
|
|
250
|
+
// so when the same segment composes multiple contracts the later ones never run.
|
|
192
251
|
export const revalidateCheckoutData = ({ actionId }) =>
|
|
193
|
-
actionId?.includes("src/actions/checkout.ts#")
|
|
252
|
+
actionId?.includes("src/actions/checkout.ts#") || undefined;
|
|
194
253
|
|
|
195
254
|
path("/checkout", CheckoutPage, { name: "checkout" }, () => [
|
|
196
255
|
revalidate(revalidateCheckoutData), // producer (route handler) reruns
|
|
@@ -219,9 +278,6 @@ path("/checkout", CheckoutPage, { name: "checkout" }, () => [
|
|
|
219
278
|
]);
|
|
220
279
|
```
|
|
221
280
|
|
|
222
|
-
For scope/revalidation guarantees and non-guarantees, see:
|
|
223
|
-
[docs/execution-model.md](../../docs/internal/execution-model.md)
|
|
224
|
-
|
|
225
281
|
## Redirects
|
|
226
282
|
|
|
227
283
|
### Basic redirect
|
|
@@ -352,11 +408,38 @@ urls(({ path, layout }) => [
|
|
|
352
408
|
])
|
|
353
409
|
```
|
|
354
410
|
|
|
411
|
+
## View Transitions
|
|
412
|
+
|
|
413
|
+
A route can configure its own `transition()` — the wrap goes around the route's component itself (routes are leaves; they have no separate default outlet channel). If the route component renders a `<ParallelOutlet />` directly, that slot remains inside the route's VT subtree, so prefer mounting parallel slots in a layout when combining intercept modals with route-level transitions. See [skills/view-transitions](../view-transitions/SKILL.md) for examples and the wrap-location rules across layouts, routes, and slots.
|
|
414
|
+
|
|
415
|
+
## Handler-attached `.use`
|
|
416
|
+
|
|
417
|
+
Page handlers can carry their own loader, middleware, error boundaries, parallels, and other defaults via a `.use` callback — so the page is self-contained and reusable across mount sites without re-wiring the same items.
|
|
418
|
+
|
|
419
|
+
```typescript
|
|
420
|
+
const ProductPage: Handler<"/product/:slug"> = async (ctx) => {
|
|
421
|
+
const product = await ctx.use(ProductLoader);
|
|
422
|
+
return <ProductView product={product} />;
|
|
423
|
+
};
|
|
424
|
+
ProductPage.use = () => [
|
|
425
|
+
loader(ProductLoader),
|
|
426
|
+
loading(<ProductSkeleton />),
|
|
427
|
+
middleware(async (ctx, next) => {
|
|
428
|
+
await next();
|
|
429
|
+
ctx.header("Cache-Control", "private, max-age=60");
|
|
430
|
+
}),
|
|
431
|
+
];
|
|
432
|
+
|
|
433
|
+
// Mount site has no per-page wiring — defaults travel with the handler.
|
|
434
|
+
path("/product/:slug", ProductPage, { name: "product" });
|
|
435
|
+
```
|
|
436
|
+
|
|
437
|
+
Explicit `use()` at the mount site merges with `handler.use` (handler defaults first, explicit second). See [skills/handler-use](../handler-use/SKILL.md) for the merge order, allowed item types per mount site, and override semantics.
|
|
438
|
+
|
|
355
439
|
## Complete Example
|
|
356
440
|
|
|
357
441
|
```typescript
|
|
358
|
-
import { urls } from "@rangojs/router";
|
|
359
|
-
import { Breadcrumbs } from "./handles/breadcrumbs";
|
|
442
|
+
import { urls, Breadcrumbs } from "@rangojs/router";
|
|
360
443
|
|
|
361
444
|
export const urlpatterns = urls(({ path, layout, loader, loading }) => [
|
|
362
445
|
// Simple route
|
|
@@ -71,23 +71,28 @@ urls(
|
|
|
71
71
|
## Router Options
|
|
72
72
|
|
|
73
73
|
```typescript
|
|
74
|
-
interface
|
|
74
|
+
interface RangoOptions<TEnv> {
|
|
75
75
|
// URL patterns from urls() function
|
|
76
76
|
urls: UrlPatterns;
|
|
77
77
|
|
|
78
78
|
// Document component wrapping entire app
|
|
79
79
|
document?: ComponentType<{ children: ReactNode }>;
|
|
80
80
|
|
|
81
|
-
//
|
|
81
|
+
// URL prefix for sub-path deployments (e.g. "/admin")
|
|
82
|
+
// All routes, reverse(), href(), Link, redirect(), and router.use()
|
|
83
|
+
// patterns are automatically prefixed. Route names stay unprefixed.
|
|
84
|
+
basename?: string;
|
|
85
|
+
|
|
86
|
+
// Enable per-request performance timeline (console waterfall + Server-Timing header)
|
|
82
87
|
debugPerformance?: boolean;
|
|
83
88
|
|
|
84
89
|
// Default error boundary
|
|
85
90
|
defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler;
|
|
86
91
|
|
|
87
|
-
// Default not-found boundary
|
|
92
|
+
// Default not-found boundary for notFound() thrown in handlers/loaders
|
|
88
93
|
defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler;
|
|
89
94
|
|
|
90
|
-
// Component for 404
|
|
95
|
+
// Component for 404 (no route match, or notFound() without a boundary)
|
|
91
96
|
notFound?: ReactNode | ((props: { pathname: string }) => ReactNode);
|
|
92
97
|
|
|
93
98
|
// Error logging callback
|
|
@@ -108,6 +113,11 @@ interface RSCRouterOptions<TEnv> {
|
|
|
108
113
|
// Connection warmup (default: true)
|
|
109
114
|
warmup?: boolean;
|
|
110
115
|
|
|
116
|
+
// Prefetch cache TTL in seconds (default: 300)
|
|
117
|
+
// Controls in-memory cache duration and Cache-Control max-age for prefetch responses.
|
|
118
|
+
// Set to false to disable prefetch caching.
|
|
119
|
+
prefetchCacheTTL?: number | false;
|
|
120
|
+
|
|
111
121
|
// CSP nonce provider (for router.fetch)
|
|
112
122
|
nonce?: (
|
|
113
123
|
request: Request,
|
|
@@ -119,6 +129,36 @@ interface RSCRouterOptions<TEnv> {
|
|
|
119
129
|
}
|
|
120
130
|
```
|
|
121
131
|
|
|
132
|
+
## Basename (Sub-Path Deployment)
|
|
133
|
+
|
|
134
|
+
When your app is served under a sub-path (e.g. `/admin` or `/v2`), set `basename`:
|
|
135
|
+
|
|
136
|
+
```typescript
|
|
137
|
+
const router = createRouter({
|
|
138
|
+
basename: "/admin",
|
|
139
|
+
document: Document,
|
|
140
|
+
}).routes(({ path, include }) => [
|
|
141
|
+
path("/", Dashboard, { name: "home" }), // matches /admin
|
|
142
|
+
path("/users", Users, { name: "users" }), // matches /admin/users
|
|
143
|
+
include("/api", apiPatterns, { name: "api" }), // matches /admin/api/*
|
|
144
|
+
]);
|
|
145
|
+
|
|
146
|
+
router.reverse("home"); // "/admin"
|
|
147
|
+
router.reverse("users"); // "/admin/users"
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Router-owned APIs are basename-aware:
|
|
151
|
+
|
|
152
|
+
- `reverse()` returns prefixed paths
|
|
153
|
+
- `<Link to="/users">` renders `<a href="/admin/users">`
|
|
154
|
+
- `redirect("/login")` redirects to `"/admin/login"`
|
|
155
|
+
- `router.use("/users/*", mw)` matches `/admin/users/*`
|
|
156
|
+
- `useRouter().push("/users")` navigates to `/admin/users`
|
|
157
|
+
- Route names stay unprefixed (`"home"`, not `"admin.home"`)
|
|
158
|
+
|
|
159
|
+
Note: `href()` is a raw path helper and does **not** auto-prefix with basename.
|
|
160
|
+
Use `reverse()` or `<Link>` for basename-aware URLs.
|
|
161
|
+
|
|
122
162
|
## Using the Request Handler
|
|
123
163
|
|
|
124
164
|
The router provides a `fetch` method to handle RSC requests:
|
|
@@ -285,6 +325,56 @@ const router = createRouter({
|
|
|
285
325
|
export default router;
|
|
286
326
|
```
|
|
287
327
|
|
|
328
|
+
## Not Found Handling
|
|
329
|
+
|
|
330
|
+
Two distinct 404 scenarios:
|
|
331
|
+
|
|
332
|
+
**1. No route matches the URL** — the router renders the `notFound` component from `createRouter()` config. This is automatic.
|
|
333
|
+
|
|
334
|
+
**2. A handler/loader calls `notFound()`** — signals that the route matched but the data doesn't exist (e.g., invalid product ID).
|
|
335
|
+
|
|
336
|
+
```typescript
|
|
337
|
+
import { notFound } from "@rangojs/router";
|
|
338
|
+
|
|
339
|
+
// In a handler or loader
|
|
340
|
+
path("/product/:slug", async (ctx) => {
|
|
341
|
+
const product = await db.getProduct(ctx.params.slug);
|
|
342
|
+
if (!product) notFound("Product not found");
|
|
343
|
+
return <ProductPage product={product} />;
|
|
344
|
+
});
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
### Fallback chain for `notFound()`
|
|
348
|
+
|
|
349
|
+
When `notFound()` is thrown, the router looks for a fallback in this order:
|
|
350
|
+
|
|
351
|
+
1. **`notFoundBoundary()`** — nearest boundary in the route tree (route-level)
|
|
352
|
+
2. **`defaultNotFoundBoundary`** — from `createRouter()` config (app-level)
|
|
353
|
+
3. **`notFound`** — from `createRouter()` config (same component used for no-route-match)
|
|
354
|
+
4. **Default `<h1>Not Found</h1>`** — built-in fallback
|
|
355
|
+
|
|
356
|
+
All cases set HTTP 404 status.
|
|
357
|
+
|
|
358
|
+
### notFoundBoundary
|
|
359
|
+
|
|
360
|
+
Wrap routes with `notFoundBoundary()` for route-specific not-found UI:
|
|
361
|
+
|
|
362
|
+
```typescript
|
|
363
|
+
urls(({ path, layout }) => [
|
|
364
|
+
layout(ShopLayout, () => [
|
|
365
|
+
notFoundBoundary(({ notFound: info }) => (
|
|
366
|
+
<div>
|
|
367
|
+
<h1>Not Found</h1>
|
|
368
|
+
<p>{info.message}</p>
|
|
369
|
+
</div>
|
|
370
|
+
)),
|
|
371
|
+
path("/product/:slug", ProductPage),
|
|
372
|
+
]),
|
|
373
|
+
]);
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
`notFoundBoundary` receives `{ notFound: NotFoundInfo }` where `NotFoundInfo` contains `message`, `segmentId`, `segmentType`, and `pathname`.
|
|
377
|
+
|
|
288
378
|
## Including Sub-patterns
|
|
289
379
|
|
|
290
380
|
```typescript
|
|
@@ -297,10 +387,10 @@ export const shopPatterns = urls(({ path, layout }) => [
|
|
|
297
387
|
]);
|
|
298
388
|
|
|
299
389
|
// src/urls.tsx
|
|
300
|
-
import { urls
|
|
390
|
+
import { urls } from "@rangojs/router";
|
|
301
391
|
import { shopPatterns } from "./urls/shop";
|
|
302
392
|
|
|
303
|
-
export const urlpatterns = urls(({ path }) => [
|
|
393
|
+
export const urlpatterns = urls(({ path, include }) => [
|
|
304
394
|
path("/", HomePage, { name: "home" }),
|
|
305
395
|
include("/shop", shopPatterns, { name: "shop" }),
|
|
306
396
|
]);
|
|
@@ -315,7 +405,7 @@ interface AppBindings {
|
|
|
315
405
|
KV: KVNamespace;
|
|
316
406
|
}
|
|
317
407
|
|
|
318
|
-
// Variables declared via
|
|
408
|
+
// Variables declared via global namespace augmentation
|
|
319
409
|
interface AppVariables {
|
|
320
410
|
user?: { id: string; name: string };
|
|
321
411
|
}
|
|
@@ -327,7 +417,7 @@ const router = createRouter<AppBindings>({
|
|
|
327
417
|
|
|
328
418
|
// Register types globally for implicit typing
|
|
329
419
|
declare global {
|
|
330
|
-
namespace
|
|
420
|
+
namespace Rango {
|
|
331
421
|
interface Env extends AppBindings {}
|
|
332
422
|
interface Vars extends AppVariables {}
|
|
333
423
|
}
|