You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 892663b
Browse filesBrowse the repository at this point in the historyBrowse files
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.
| 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`|
| 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. |
341
342
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:
343
344
344
345
```tsx
345
346
// src/catalog/stock.loader.ts
@@ -369,6 +370,8 @@ function Stock() {
369
370
370
371
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.
371
372
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
+
372
375
### `ssr: false`
373
376
374
377
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
377
380
- Intercept loaders reject the option, because intercepts only render on client navigations.
378
381
- Every document load pays the flagged loader's latency before the first byte. Keep flagged loaders fast.
379
382
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.
Copy file name to clipboardExpand all lines: apps/docs/content/docs/rango/guides/server-actions.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -174,7 +174,7 @@ In production `error.message` is replaced with `"An error occurred"` (and `stack
174
174
175
175
`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.
176
176
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).
| 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`|
| 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).
645
656
646
657
The pattern to recommend for a failure the user can retry: return it from the
647
658
loader as data (`{ ok: false, reason }`) and render it at the read. The action
648
659
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.
650
667
651
668
Pinned dev+prod in `e2e/action-failure.test.ts` (router test-app) and
652
669
`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
0 commit comments