mirror of
https://github.com/hanzoai/next.js.git
synced 2026-09-24 17:00:51 +00:00
c2b4c0815c
This PRs unifies the caching story across the docs, making Cache Components the happy path, while still providing guidance to users in the old model. However, instead of explaining the old model and its caching layers, we've created a new guide focusing on what APIs to use and when. This follow-up PR aligns terminology across the docs: https://github.com/vercel/next.js/pull/90589 ## IA updates Getting Started section: - Improves Getting Started progression: - **Before:** CC → Fetching Data → Updating Data → Caching and Revalidating (old and new model mixed) - **After:** Fetching Data (Dynamic) → Mutating Data (Dynamic) → Caching with CC (Prerendering) → Revalidating with CC. - New: `caching.mdx` (CC-first) - Structure: - Enabling Cache Components - Data vs UI-level caching - Working with request time APIs - Passing request values to cached functions - Working with non-deterministic operations - Working with synchronous operations - How rendering works (PPR and static shell story) - New: `revalidating.mdx` (CC-first) - Explains how to use `cacheLife` and `cacheTag` Guides Section: - New: `caching-and-revalidating.mdx` (Previous Model) - For users who are not using CC, includes `fetch` options and route segment config - Moves route segment config options that don't apply to CC from API reference to this guide (for easy archiving in the future). - New: `migrating-to-cache-components.mdx` (WIP) - Del: `caching.mdx` 😌 ## Terminology We should remove caching layers from the docs. Users only needed to be exposed to them when they were configured independently, but the new CC APIs work across layers. To make it easier to review this PR, I'm consolidating terminology and fixing broken links in a new PR: https://github.com/vercel/next.js/pull/90589 --------- Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com> Co-authored-by: Joseph <[email protected]>
66 lines
2.9 KiB
Plaintext
66 lines
2.9 KiB
Plaintext
---
|
|
title: unstable_rethrow
|
|
description: API Reference for the unstable_rethrow function.
|
|
version: unstable
|
|
---
|
|
|
|
`unstable_rethrow` can be used to avoid catching internal errors thrown by Next.js when attempting to handle errors thrown in your application code.
|
|
|
|
For example, calling the `notFound` function will throw an internal Next.js error and render the [`not-found.js`](/docs/app/api-reference/file-conventions/not-found) component. However, if used inside the `try` block of a `try/catch` statement, the error will be caught, preventing `not-found.js` from rendering:
|
|
|
|
```tsx filename="@/app/ui/component.tsx"
|
|
import { notFound } from 'next/navigation'
|
|
|
|
export default async function Page() {
|
|
try {
|
|
const post = await fetch('https://.../posts/1').then((res) => {
|
|
if (res.status === 404) notFound()
|
|
if (!res.ok) throw new Error(res.statusText)
|
|
return res.json()
|
|
})
|
|
} catch (err) {
|
|
console.error(err)
|
|
}
|
|
}
|
|
```
|
|
|
|
You can use `unstable_rethrow` API to re-throw the internal error and continue with the expected behavior:
|
|
|
|
```tsx filename="@/app/ui/component.tsx"
|
|
import { notFound, unstable_rethrow } from 'next/navigation'
|
|
|
|
export default async function Page() {
|
|
try {
|
|
const post = await fetch('https://.../posts/1').then((res) => {
|
|
if (res.status === 404) notFound()
|
|
if (!res.ok) throw new Error(res.statusText)
|
|
return res.json()
|
|
})
|
|
} catch (err) {
|
|
unstable_rethrow(err)
|
|
console.error(err)
|
|
}
|
|
}
|
|
```
|
|
|
|
The following Next.js APIs rely on throwing an error which should be rethrown and handled by Next.js itself:
|
|
|
|
- [`notFound()`](/docs/app/api-reference/functions/not-found)
|
|
- [`redirect()`](/docs/app/guides/redirecting#redirect-function)
|
|
- [`permanentRedirect()`](/docs/app/guides/redirecting#permanentredirect-function)
|
|
|
|
If a route segment is marked to throw an error unless it's static, a Request-time API call will also throw an error that should similarly not be caught by the developer. Note that Partial Prerendering (PPR) affects this behavior as well. These APIs are:
|
|
|
|
- [`cookies`](/docs/app/api-reference/functions/cookies)
|
|
- [`headers`](/docs/app/api-reference/functions/headers)
|
|
- [`searchParams`](/docs/app/api-reference/file-conventions/page#searchparams-optional)
|
|
- `fetch(..., { cache: 'no-store' })`
|
|
- `fetch(..., { next: { revalidate: 0 } })`
|
|
|
|
> **Good to know**:
|
|
>
|
|
> - This method should be called at the top of the catch block, passing the error object as its only argument. It can also be used within a `.catch` handler of a promise.
|
|
> - You may be able to avoid using `unstable_rethrow` if you encapsulate your API calls that throw and let the **caller** handle the exception.
|
|
> - Only use `unstable_rethrow` if your caught exceptions may include both application errors and framework-controlled exceptions (like `redirect()` or `notFound()`).
|
|
> - Any resource cleanup (like clearing intervals, timers, etc) would have to either happen prior to the call to `unstable_rethrow` or within a `finally` block.
|