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 4d0e587
Browse filesBrowse the repository at this point in the historyBrowse files
fix(router): fail or skip a prerendered route whose component throws while the build encodes it
Prerender baked a Flight error row when the handler returned but a
component in its tree threw during the build-time encode (an async
server component whose fetch failed): the build logged OK and the route
served its error boundary until the next build. #587's policy only saw
handler throws, because Flight reports a component throw through
onError and completes normally. matchForPrerender and
renderStaticSegment now pass onError to every encode and re-throw the
first error, so prerender.onError decides exactly as for a handler
throw. serializeResult, encodeHandles and encodeHandleValue gain the
optional trailing onError.
Closes#914
Copy file name to clipboardExpand all lines: apps/docs/content/docs/rango/guides/prerender.mdx
+3Lines changed: 3 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -259,11 +259,14 @@ A handler that throws a non-`Skip` error is surfaced to the build — never bake
259
259
|`return ctx.passthrough()`| No entry, logged `PASS`| No entry, `PASS`|
260
260
|`throw new Skip("reason")`| No entry, logged `SKIP`, build goes on | No entry, `SKIP`, build goes on |
261
261
|`throw new Error("reason")`| Logged `FAIL`, the build stops | Logged `WARN`, URL left un-baked |
262
+
| A child component throws | Logged `FAIL`, the build stops | Logged `WARN`, URL left un-baked |
262
263
263
264
```ts
264
265
rango({ prerender: { onError: "warn" } });
265
266
```
266
267
268
+
The last row is a handler that returns fine while an async server component in its tree throws during the build-time render, for example because its fetch fails. It goes through the same policy instead of being baked as an error, and a `Skip` thrown there skips the URL.
269
+
267
270
`"warn"` is a build-unblock, not a runtime contract: the un-baked route falls through to normal resolution and may render live or 404 depending on the rest of the build. For defined runtime behavior use `Passthrough()` or `throw new Skip()`; otherwise keep the default. Both `Skip` and hard errors also reach the router's `onError` callback with phase `"prerender"` or `"static"`.
Copy file name to clipboardExpand all lines: docs/design/caching.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -121,8 +121,8 @@ Key points:
121
121
- Revival produces a React element identical to the original
122
122
- Cached elements render correctly in both RSC stream and HTML output
123
123
- A component that is still a promise (a route, parallel slot or intercept handler streamed under `loading()`) is awaited before encoding (`serializeSegments` in `src/cache/segment-codec.ts`); if it rejects, the serialize step throws and `cacheRoute` writes nothing, so a handler that fails after the 200 has gone out, which the MISS gate's `response.status !== 200` check in `withCacheStore` cannot see, never replaces an entry
124
-
- A component that throws while a segment is encoded (an async server component in a handler's tree) does not reject the encode: Flight reports it through `onError` and completes normally with an error row (`1:E{"digest":""}`) that throws wherever the decoded tree renders. `cacheRoute` passes an `onError` to `serializeSegments` (`src/cache/segment-codec.ts`) and, if it fires, writes nothing and reports the error as `cache-write`, so the next request is a MISS and a stale entry keeps serving. The encode re-runs the tree, so only a throw during the encode blocks the write. Prerender calls `serializeSegments` without `onError`and still stores the error row
125
-
- The item writers and handle values follow the same rule. Besides an async component that throws, Flight reports a rejected promise, a function, a class instance and a local symbol through `onError` and writes an error row, so `serializeResult`'s `null` never fires for them. `serializeResult` (`src/cache/segment-codec.ts`) and `encodeHandles` / `encodeHandleValue` (`src/cache/handle-snapshot.ts`) take the same optional `onError`, and each writer passes one collector to its value encode and its handle encode: `"use cache"` (`src/cache/cache-runtime.ts`, the miss leader and the stale-hit refresh), a loader's own `cache()` (`src/router/segment-resolution/loader-cache.ts`, whose `setItem` throws into `readThroughItem`'s report) and `cacheRoute`. If it fires, nothing is written and the error is reported as `cache-write` (miss) or `stale-revalidation` (background refresh), so the next call re-runs and a stale entry keeps serving. A handle value that fails to encode refuses the whole entry rather than dropping only the handle blob: a hit replays the blob in place of the body's pushes, so an entry without it would serve a page missing its title or breadcrumbs until expiry. The blob is still dropped, entry kept, when its encode passes the 5 s `HANDLE_ENCODE_TIMEOUT_MS`. Prerender calls both without `onError` and still stores the error row
124
+
- A component that throws while a segment is encoded (an async server component in a handler's tree) does not reject the encode: Flight reports it through `onError` and completes normally with an error row (`1:E{"digest":""}`) that throws wherever the decoded tree renders. `cacheRoute` passes an `onError` to `serializeSegments` (`src/cache/segment-codec.ts`) and, if it fires, writes nothing and reports the error as `cache-write`, so the next request is a MISS and a stale entry keeps serving. The encode re-runs the tree, so only a throw during the encode blocks the write. Prerender passes an `onError` the same way and hands the first error to the build's `prerender.onError`policy (see Render Errors in `packages/rangojs-router/docs/prerender-api-design.md`)
125
+
- The item writers and handle values follow the same rule. Besides an async component that throws, Flight reports a rejected promise, a function, a class instance and a local symbol through `onError` and writes an error row, so `serializeResult`'s `null` never fires for them. `serializeResult` (`src/cache/segment-codec.ts`) and `encodeHandles` / `encodeHandleValue` (`src/cache/handle-snapshot.ts`) take the same optional `onError`, and each writer passes one collector to its value encode and its handle encode: `"use cache"` (`src/cache/cache-runtime.ts`, the miss leader and the stale-hit refresh), a loader's own `cache()` (`src/router/segment-resolution/loader-cache.ts`, whose `setItem` throws into `readThroughItem`'s report) and `cacheRoute`. If it fires, nothing is written and the error is reported as `cache-write` (miss) or `stale-revalidation` (background refresh), so the next call re-runs and a stale entry keeps serving. A handle value that fails to encode refuses the whole entry rather than dropping only the handle blob: a hit replays the blob in place of the body's pushes, so an entry without it would serve a page missing its title or breadcrumbs until expiry. The blob is still dropped, entry kept, when its encode passes the 5 s `HANDLE_ENCODE_TIMEOUT_MS`. Prerender passes the same collector and hands the first error to its `prerender.onError` policy
Copy file name to clipboardExpand all lines: packages/rangojs-router/CHANGELOG.md
+22Lines changed: 22 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -64,6 +64,28 @@ these are now checked against it, as middleware reverse already was. Without
64
64
a generated map, any name except a dot-prefixed literal is accepted. Runtime
65
65
behavior is unchanged. Pass the fully qualified name and every param.
66
66
67
+
### Breaking: a component that throws while a route is prerendered fails the build ([#917](https://github.com/rangojs/rango/pull/917))
68
+
69
+
A `Prerender()` route or `Static()` handler could return normally while its
70
+
tree held a component that threw during the build-time render, such as an
71
+
async server component whose fetch failed. Flight encoded that component as an
72
+
error row, the build logged `OK`, and the route served its error boundary
73
+
until the next build. The error now takes the same path as a handler throw:
74
+
75
+
-`prerender.onError: "fail"` (the default) fails the build and names the URL
76
+
and the error.
77
+
-`"warn"` logs `WARN` and skips the URL.
78
+
- A `Skip` thrown by the component skips the URL.
79
+
- The router's `onError` receives it with phase `"prerender"` or `"static"`.
80
+
81
+
Intercept variants and handle values are checked the same way. In dev, the
82
+
`/__rsc_prerender` endpoint falls through to a live render for such a route
83
+
instead of serving a payload that holds the error row.
84
+
85
+
Migration: a build that passed with such a route now fails. Fix the component,
86
+
`throw new Skip()` for URLs that cannot render at build time, or set
87
+
`rango({ prerender: { onError: "warn" } })` to skip them.
88
+
67
89
### Added: `router.debugManifest()` on the public `Rango` type ([#874](https://github.com/rangojs/rango/pull/874))
68
90
69
91
`debugManifest()` was typed only on the internal router interface, so calling
0 commit comments