Skip to content

Commit 892663b

Browse files
committed
docs(router): scope the clientUrls action-failure table to loading(), add the cache caveat; tidy the dev SSR hold
A urls() route with loading() does not reject the action call when a loader throws on its rerun: the action lane hands the settled data to LoaderBoundary, which decodes it while React renders, so the call resolves and the read throws to the nearest error boundary. A group route never takes that branch. The skill, docs/client-urls.md, the docs-site guide and the server-actions skill and page now scope the first row and add a row for a urls() route with loading(), pinned by new dev + production e2e cases in both apps (/throw-loading in the group and its urls() twin). Returning a failure as data now carries a caveat: cache(), a ppr bake of an ssr:false loader, and a prerender store it like any value; a thrown error is never stored. ssr: false is described as guaranteeing the loader's data, not a client module's first load in a build. The internal doc drops the consolidation note (fixed in the previous commit) and cites server-action-bridge.ts:848. The I5 drift allowance in the bounded e2e case now names its cause: segment-system.tsx:863 plants the error fallback in place of the StreamedLoaderErrorBoundary-wrapped content, against suspense-contract.md:448. SSR: trackDocumentClientLoads owns the dev decode's client-load set, and settleDocumentClientLoads races the loads against the deadline instead of an expired flag. The dev gate keeps process.env.NODE_ENV, with the reason in a comment. New unit tests fail when the two task yields are removed, when the 5 s cap is removed, and when the gate is forced on in production.
1 parent f415e8a commit 892663b

16 files changed

Lines changed: 374 additions & 116 deletions

File tree

‎apps/docs/content/docs/rango/guides/client-urls.mdx‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -334,12 +334,13 @@ A form's React state survives an action's revalidation in a group, as it does on
334334

335335
The action has already run when its loaders re-run, so a loader that throws then does not undo it. Where the error lands decides what the user sees:
336336

337-
| Above the route | Action called directly (`await action()`) | Action from `<form action>`, `useActionState`, or `useTransition` |
338-
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
339-
| No `errorBoundary()` | The call rejects with the loader's error (`"An error occurred"` in a production build), although the action returned. Nothing of that revalidation commits: the page keeps its data and its React state. | React hands the rejection to the nearest React error boundary above the form. If you have none, the router's root error boundary replaces the page. |
340-
| `errorBoundary()` around the mount | Its fallback replaces the route, so the page and its form state unmount. | The same. |
337+
| The route | Action called directly (`await action()`) | Action from `<form action>`, `useActionState`, or `useTransition` |
338+
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
339+
| A group route, or a `urls()` route without `loading()` | The call rejects with the loader's error (`"An error occurred"` in a production build), although the action returned. Nothing of that revalidation commits: the page keeps its data and its React state. | React hands the rejection to the nearest React error boundary above the form. If you have none, the router's root error boundary replaces the page. |
340+
| A `urls()` route with `loading()` | The call resolves with the action's result. The page renders, the loader's read throws, and the nearest React error boundary catches it. If you have none, the router's root error boundary replaces the page. | The same. |
341+
| Under an `errorBoundary()` (for a group, around the mount) | Its fallback replaces the route, so the page and its form state unmount. | The same. |
341342

342-
A `urls()` route behaves the same way. For a failure the user can retry, such as a flaky upstream or a rate limit, return the failure as data instead of throwing, and render it where the data goes:
343+
A `loading()` on a group route doesn't change the first row. For a failure the user can retry, such as a flaky upstream or a rate limit, return the failure as data instead of throwing, and render it where the data goes:
343344

344345
```tsx
345346
// src/catalog/stock.loader.ts
@@ -369,6 +370,8 @@ function Stock() {
369370

370371
The action resolves with its result, the page and its form state stay, and the next action or navigation that re-runs the loader replaces the message. Keep throwing for a failure that should stop the page, and put an `errorBoundary()` around the mount for it.
371372

373+
A failure returned as data is an ordinary value, so anything that stores the loader's value stores it too: a `cache()` on the loader serves it until its TTL runs out, a `ppr` shell bakes the value of an `ssr: false` loader, and a prerender stores it at build time. A thrown error is never stored, and a stale entry keeps serving. To cache the expensive part, cache the call the loader makes, with `"use cache"` on that function (a call that throws stores nothing), and turn the throw into data in a loader that isn't cached itself.
374+
372375
### `ssr: false`
373376

374377
By default every loader streams, so nothing a slow loader produces is guaranteed to be in the server-rendered HTML: its data, its handle pushes, or the 404 status from a thrown `notFound()`. `loader(Def, { ssr: false })` makes document renders wait for that loader before the first flush. Client navigations still stream it. The option applies to one loader, and unflagged siblings keep streaming behind their boundaries.
@@ -377,7 +380,7 @@ By default every loader streams, so nothing a slow loader produces is guaranteed
377380
- Intercept loaders reject the option, because intercepts only render on client navigations.
378381
- Every document load pays the flagged loader's latency before the first byte. Keep flagged loaders fast.
379382

380-
Without JavaScript, a browser sees only what the first flush carries. A boundary that isn't complete by then ships its fallback and swaps the content in with a script, which never runs without JavaScript. That includes a client component a loader's answer draws under an inline `<Suspense>`. A fast loader's answer usually makes the first flush, and `ssr: false` guarantees it. The dev server behaves like a production build here: before the first flush, it waits for the client components the document's payload has named so far.
383+
Without JavaScript, a browser sees only what the first flush carries. A boundary that isn't complete by then ships its fallback and swaps the content in with a script, which never runs without JavaScript. That includes a client component a loader's answer draws under an inline `<Suspense>`. A fast loader's answer usually makes the first flush, and `ssr: false` guarantees that the loader's data does. It doesn't cover the client component's module: the first document a freshly started production server renders can still be waiting for it. The dev server behaves like a production build here: before the first flush, it waits for the client components the document's payload has named so far.
381384

382385
### `prefetch: false`
383386

‎apps/docs/content/docs/rango/guides/server-actions.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -174,7 +174,7 @@ In production `error.message` is replaced with `"An error occurred"` (and `stack
174174

175175
`notFound()` thrown inside an action is handled like any other error: it renders the nearest `errorBoundary()` with `error.name === "DataNotFoundError"`. `notFoundBoundary()` handles `notFound()` from handlers and loaders, not from actions. For a recoverable "already gone" case, return a result the form can show (`{ error: "Post not found" }`) instead of throwing.
176176

177-
A loader that throws while it re-runs after the action is a different case: the action has already run and returned. With no `errorBoundary()` above the route, the action call rejects with the loader's error, nothing of that revalidation commits, and the page keeps its data and its React state. A `<form action>`, `useActionState`, or `useTransition` call hands that rejection to the nearest React error boundary above the form. An `errorBoundary()` above the route renders its fallback in place of the route instead. For a failure the user can retry, return it from the loader as data. See [A loader that fails on its re-run](/docs/rango/guides/client-urls#a-loader-that-fails-on-its-re-run), which applies to `urls()` routes and client groups alike.
177+
A loader that throws while it re-runs after the action is a different case: the action has already run and returned. On a route without `loading()`, and on any client group route, the action call rejects with the loader's error, nothing of that revalidation commits, and the page keeps its data and its React state; a `<form action>`, `useActionState`, or `useTransition` call hands that rejection to the nearest React error boundary above the form. On a `urls()` route with `loading()`, the call resolves and the loader's read throws to the nearest React error boundary when the page renders. An `errorBoundary()` above the route renders its fallback in place of the route instead. For a failure the user can retry, return it from the loader as data, keeping in mind that a cached or prerendered loader then stores that failure like any other value. See [A loader that fails on its re-run](/docs/rango/guides/client-urls#a-loader-that-fails-on-its-re-run).
178178

179179
## Choosing what revalidates
180180

‎packages/rangojs-router/docs/client-urls.md‎

Lines changed: 49 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -621,39 +621,59 @@ action commit renders into the mounted tree (`server-action-bridge.ts`, the
621621
### A loader that fails on its rerun after an action
622622

623623
The action has run and returned by the time its loaders rerun, so the failure
624-
cannot undo it. What the browser does depends on whether an `errorBoundary()`
625-
sits above the route, which for a group means around the `include()` mount:
626-
627-
| Above the route | Action called directly (`await action()`) | From `<form action>`, `useActionState`, `useTransition` |
628-
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
629-
| No `errorBoundary()` | The call rejects with the loader's error (`"An error occurred"` in a build); nothing of that revalidation commits; page data and React state stay | React hands the rejection to the nearest React error boundary above the form; with none of the app's, `RootErrorBoundary` replaces the page |
630-
| `errorBoundary()` around the mount | Its fallback replaces the route; the page and its form state unmount | The same |
631-
632-
Why the first row rejects: the action lane settles loader data before it
633-
commits (`renderSegments` with `isAction`, `server-action-bridge.ts:849`). A
634-
loader entry with `ok: false` and no fallback makes `decodeLoaderResults`
635-
throw (`decode-loader-results.ts:121`, called from `segment-system.tsx:745`),
636-
so `renderSegments` rejects before `onUpdate`, and the rejection becomes the
637-
action call's. With an `errorBoundary()`, `loader-resolution.ts` renders its
638-
fallback into the entry, `decodeLoaderResults` takes it as the segment's
639-
`errorFallback` (`decode-loader-results.ts:109`), and the commit renders it in
640-
place of the route. A `urls()` route takes the same path. One side effect to
641-
know about: the rejected action's entry is disposed without `complete()` or
642-
`fail()`, so it lingers uncompleted for its 100 ms settle window
643-
(`event-controller.ts`, `doSettle`), and an action started in that window
644-
counts it as concurrent and adds one consolidation refetch.
624+
cannot undo it. What the browser does depends on two things: whether an
625+
`errorBoundary()` sits above the route (for a group, around the `include()`
626+
mount), and, for a `urls()` route, whether the route has a `loading()`:
627+
628+
| The route | Action called directly (`await action()`) | From `<form action>`, `useActionState`, `useTransition` |
629+
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
630+
| A group route, or a `urls()` route without `loading()` | The call rejects with the loader's error (`"An error occurred"` in a build); nothing of that revalidation commits; page data and React state stay | React hands the rejection to the nearest React error boundary above the form; with none of the app's, `RootErrorBoundary` replaces the page |
631+
| A `urls()` route with `loading()` | The call resolves; the commit renders, the read throws, and the nearest React error boundary catches it (`RootErrorBoundary` if the app has none) | The same |
632+
| Under an `errorBoundary()` (for a group, around the mount) | Its fallback replaces the route; the page and its form state unmount | The same |
633+
634+
Why the rows differ. The action lane settles loader data before it commits
635+
(`renderSegments` with `isAction`, `server-action-bridge.ts:848`). Without
636+
`loading()` the segment's loaders take the aggregate path: a loader entry with
637+
`ok: false` and no fallback makes `decodeLoaderResults` throw
638+
(`decode-loader-results.ts:121`, called from `segment-system.tsx:745`), so
639+
`renderSegments` rejects before `onUpdate`, the commit is dropped, and the
640+
rejection becomes the action call's. With `loading()` on a `urls()` route the
641+
lane awaits the same data (`segment-system.tsx:651-662`) but hands it to
642+
`LoaderBoundary`, which decodes it while React renders
643+
(`route-content-wrapper.tsx:351`): `renderSegments` resolves, the action
644+
resolves, and the throw happens in the committed render. A group route never
645+
takes that branch (`segment-system.tsx:638`, `!clientGroup && loading`), so
646+
its `loading()` changes nothing here. With an `errorBoundary()`,
647+
`loader-resolution.ts` renders its fallback into the entry,
648+
`decodeLoaderResults` takes it as the segment's `errorFallback`
649+
(`decode-loader-results.ts:109`), and the commit renders it in place of the
650+
route.
651+
652+
The rejected call is the action's error for `useAction` too: the bridge's
653+
`catch` calls `handle.fail(error)`, and the event controller marks a disposed
654+
action completed, so an action started in its 100 ms settle window is not
655+
counted as concurrent (no consolidation refetch, #675).
645656

646657
The pattern to recommend for a failure the user can retry: return it from the
647658
loader as data (`{ ok: false, reason }`) and render it at the read. The action
648659
resolves, the page and its state stay, and the next rerun replaces the
649-
message. The skill carries the example.
660+
message. The skill carries the example. One caveat: the failure is then an
661+
ordinary value, so a `cache()` on the loader, a `ppr` bake of an `ssr: false`
662+
loader, or a prerender stores and serves it like any other. A thrown error is
663+
never stored: the miss path stores only what `execute()` returned
664+
(`cache/read-through-swr.ts:159`), and a background revalidation that throws
665+
keeps the stale entry. Cache the call the loader makes instead and convert the
666+
throw in an uncached loader.
650667

651668
Pinned dev+prod in `e2e/action-failure.test.ts` (router test-app) and
652669
`tests/cloudflare-basic/e2e/action-failure.test.ts`, body
653-
`tests/shared-e2e/src/action-failure-scenario.ts`: a group, its `urls()`
654-
twin, and the group under an `errorBoundary()`. The response itself is pinned
655-
through `serveShellRequest({ action })` in
656-
`src/testing/__tests__/client-urls-revalidate.rsc-test.tsx`.
670+
`tests/shared-e2e/src/action-failure-scenario.ts`: a group and its `urls()`
671+
twin, each with and without `loading()`, and the group under an
672+
`errorBoundary()`. The response itself is pinned through
673+
`serveShellRequest({ action })` in
674+
`src/testing/__tests__/client-urls-revalidate.rsc-test.tsx`; the settle-window
675+
fix in `src/__tests__/event-controller.test.ts` and
676+
`src/__tests__/server-action-bridge.test.ts`.
657677

658678
`intercept()` loaders inside `clientUrls()` do not apply their `revalidate()`
659679
yet (a known gap, left for a follow-up), so do not rely on it there. The build
@@ -681,7 +701,9 @@ A browser without JavaScript sees only what the first flush carries: a
681701
boundary that completes later ships its fallback and swaps the content in with
682702
a script that never runs. A client component a loader's answer draws under an
683703
inline `<Suspense>` is in the first flush when the loader settles before it
684-
(a fast loader usually does; `ssr: false` guarantees it). That used to differ in
704+
(a fast loader usually does; `ssr: false` guarantees the loader's data, not
705+
the module load a build's first render of a reference still waits for). That
706+
used to differ in
685707
dev. plugin-rsc tags client reference ids with a per-render cache tag in dev, so
686708
its SSR loader memo missed on every request and each reference loaded through
687709
the module runner again, an RPC per import on workerd; the boundary completed

‎packages/rangojs-router/e2e/test-app/src/router.named-routes.gen.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,13 @@ export const NamedRoutes = {
33
"actionCtxSet.index": "/action-ctx-set",
44
"actionFailureBounded.data": "/action-failure-bounded/data",
55
"actionFailureBounded.throw": "/action-failure-bounded/throw",
6+
"actionFailureBounded.throwLoading": "/action-failure-bounded/throw-loading",
67
"actionFailureClient.data": "/action-failure-client/data",
78
"actionFailureClient.throw": "/action-failure-client/throw",
9+
"actionFailureClient.throwLoading": "/action-failure-client/throw-loading",
810
"actionFailureServer.data": "/action-failure-server/data",
911
"actionFailureServer.throw": "/action-failure-server/throw",
12+
"actionFailureServer.throwLoading": "/action-failure-server/throw-loading",
1013
"actionRedirectRevalidation.index": "/action-redirect-revalidation",
1114
"actionRedirectRevalidation.login": "/action-redirect-revalidation/login",
1215
"actionRouteMw.index": "/action-route-mw",

‎packages/rangojs-router/e2e/test-app/src/urls/action-failure.client-urls.tsx‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
import { clientUrls } from "@rangojs/router/client";
44
import {
55
ActionFailureDataPage,
6+
ActionFailureLoading,
67
ActionFailureThrowPage,
78
} from "./action-failure.client.js";
89
import {
@@ -11,11 +12,18 @@ import {
1112
} from "./action-failure.defs.js";
1213

1314
// A group loader that fails on its rerun after an action (action-failure.test.ts):
14-
// /throw throws, /data returns the failure as data.
15-
export default clientUrls(({ path, loader }) => [
15+
// /throw throws, /throw-loading throws under a loading(), /data returns the
16+
// failure as data.
17+
export default clientUrls(({ path, loader, loading }) => [
1618
path("/throw", ActionFailureThrowPage, { name: "throw" }, () => [
1719
loader(ActionFailureThrowLoader),
1820
]),
21+
path(
22+
"/throw-loading",
23+
ActionFailureThrowPage,
24+
{ name: "throwLoading" },
25+
() => [loader(ActionFailureThrowLoader), loading(<ActionFailureLoading />)],
26+
),
1927
path("/data", ActionFailureDataPage, { name: "data" }, () => [
2028
loader(ActionFailureDataLoader),
2129
]),

0 commit comments

Comments
 (0)