Unverified Commit 66bbcb58 authored by Jiwon Choi's avatar Jiwon Choi Committed by GitHub

docs: `unstable_catchError()` (#89847)

Docs for https://github.com/vercel/next.js/pull/89688
parent 23fa2787
...@@ -7,6 +7,7 @@ related: ...@@ -7,6 +7,7 @@ related:
links: links:
- app/api-reference/functions/redirect - app/api-reference/functions/redirect
- app/api-reference/file-conventions/error - app/api-reference/file-conventions/error
- app/api-reference/functions/catchError
- app/api-reference/functions/not-found - app/api-reference/functions/not-found
- app/api-reference/file-conventions/not-found - app/api-reference/file-conventions/not-found
--- ---
...@@ -271,7 +272,66 @@ Errors will bubble up to the nearest parent error boundary. This allows for gran ...@@ -271,7 +272,66 @@ Errors will bubble up to the nearest parent error boundary. This allows for gran
height="687" height="687"
/> />
Error boundaries don’t catch errors inside event handlers. They’re designed to catch errors [during rendering](https://react.dev/reference/react/Component#static-getderivedstatefromerror) to show a **fallback UI** instead of crashing the whole app. For component-level error recovery, the [`unstable_catchError`](/docs/app/api-reference/functions/catchError) function lets you create error boundaries that can wrap any part of your component tree:
```tsx filename="app/custom-error-boundary.tsx" switcher
'use client'
import { unstable_catchError as catchError, type ErrorInfo } from 'next/error'
function ErrorFallback(
props: { title: string },
{ error, unstable_retry: retry }: ErrorInfo
) {
return (
<div>
<h2>{props.title}</h2>
<p>{error.message}</p>
<button onClick={() => retry()}>Try again</button>
</div>
)
}
export default catchError(ErrorFallback)
```
```jsx filename="app/custom-error-boundary.js" switcher
'use client'
import { unstable_catchError as catchError } from 'next/error'
function ErrorFallback(props, { error, unstable_retry: retry }) {
return (
<div>
<h2>{props.title}</h2>
<p>{error.message}</p>
<button onClick={() => retry()}>Try again</button>
</div>
)
}
export default catchError(ErrorFallback)
```
Then use the returned component as a wrapper in any layout or page:
```tsx filename="app/some-component.tsx" switcher
import ErrorBoundary from './custom-error-boundary'
export default function Component({ children }: { children: React.ReactNode }) {
return <ErrorBoundary title="Dashboard Error">{children}</ErrorBoundary>
}
```
```jsx filename="app/some-component.js" switcher
import ErrorBoundary from './custom-error-boundary'
export default function Component({ children }) {
return <ErrorBoundary title="Dashboard Error">{children}</ErrorBoundary>
}
```
Error boundaries don't catch errors inside event handlers. They're designed to catch errors [during rendering](https://react.dev/reference/react/Component#static-getderivedstatefromerror) to show a **fallback UI** instead of crashing the whole app.
In general, errors in event handlers or async code aren’t handled by error boundaries because they run after rendering. In general, errors in event handlers or async code aren’t handled by error boundaries because they run after rendering.
......
...@@ -91,6 +91,7 @@ export default function Error({ error, unstable_retry }) { ...@@ -91,6 +91,7 @@ export default function Error({ error, unstable_retry }) {
> >
> - The [React DevTools](https://react.dev/learn/react-developer-tools) allow you to toggle error boundaries to test error states. > - The [React DevTools](https://react.dev/learn/react-developer-tools) allow you to toggle error boundaries to test error states.
> - If you want errors to bubble up to the parent error boundary, you can `throw` when rendering the `error` component. > - If you want errors to bubble up to the parent error boundary, you can `throw` when rendering the `error` component.
> - For component-level error recovery that aren't tied to route segments like [`error.js`](/docs/app/api-reference/file-conventions/error), use the [`unstable_catchError`](/docs/app/api-reference/functions/catchError) function.
In the [component hierarchy](/docs/app/getting-started/project-structure#component-hierarchy), `error.js` wraps `loading.js`, `not-found.js`, `page.js`, and nested `layout.js` files in a React error boundary. It does **not** wrap the `layout.js` or `template.js` above it in the same segment. To handle errors in the root layout, use [`global-error.js`](/docs/app/api-reference/file-conventions/error#global-error). In the [component hierarchy](/docs/app/getting-started/project-structure#component-hierarchy), `error.js` wraps `loading.js`, `not-found.js`, `page.js`, and nested `layout.js` files in a React error boundary. It does **not** wrap the `layout.js` or `template.js` above it in the same segment. To handle errors in the root layout, use [`global-error.js`](/docs/app/api-reference/file-conventions/error#global-error).
......
---
title: unstable_catchError
description: API Reference for the unstable_catchError function.
related:
title: Learn more about error handling
links:
- app/getting-started/error-handling
- app/api-reference/file-conventions/error
---
The `unstable_catchError` function creates a component that wraps its children in an error boundary. It provides a programmatic alternative to the [`error.js`](/docs/app/api-reference/file-conventions/error) file convention, enabling component-level error recovery anywhere in your component tree.
`unstable_catchError` can be called from [Client Components](/docs/app/getting-started/server-and-client-components).
```tsx filename="app/custom-error-boundary.tsx" switcher
'use client'
import { unstable_catchError } from 'next/error'
function ErrorFallback(
props: { title: string },
{ error, unstable_retry: retry }: { error: Error; unstable_retry: () => void }
) {
return (
<div>
<h2>{props.title}</h2>
<p>{error.message}</p>
<button onClick={() => retry()}>Try again</button>
</div>
)
}
export default unstable_catchError(ErrorFallback)
```
```jsx filename="app/custom-error-boundary.js" switcher
'use client'
import { unstable_catchError } from 'next/error'
function ErrorFallback(props, { error, unstable_retry: retry }) {
return (
<div>
<h2>{props.title}</h2>
<p>{error.message}</p>
<button onClick={() => retry()}>Try again</button>
</div>
)
}
export default unstable_catchError(ErrorFallback)
```
## Reference
### Parameters
`unstable_catchError` accepts a single argument:
```ts
const ErrorWrapper = unstable_catchError(fallback)
```
#### `fallback`
A function that renders the error UI when an error is caught. It receives two arguments:
- `props` — The props passed to the wrapper component (excluding `children`).
- `errorInfo` — An object containing information about the error:
| Property | Type | Description |
| ---------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `error` | [`Error`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error) | The error instance that was caught. |
| `unstable_retry` | `() => void` | Re-fetches and re-renders the error boundary's contents. If successful, the fallback is replaced with the re-rendered result. |
| `reset` | `() => void` | Resets the error state and re-renders without re-fetching. Use [`retry()`](/docs/app/api-reference/file-conventions/error#unstable_retry) in most cases. |
The `fallback` function must be a Client Component (or defined in a `'use client'` module).
### Returns
`unstable_catchError` returns a React component that:
- Accepts the same props as your fallback's first argument, plus `children`.
- Wraps `children` in an error boundary.
- Renders the `fallback` when an error is caught in `children`.
## Examples
### Client Component
Define a fallback and use the returned component to wrap parts of your UI:
```tsx filename="app/some-component.tsx" switcher
import ErrorWrapper from '../custom-error-boundary'
export default function Component({ children }: { children: React.ReactNode }) {
return <ErrorWrapper title="Dashboard Error">{children}</ErrorWrapper>
}
```
```jsx filename="app/some-component.js" switcher
import ErrorWrapper from '../custom-error-boundary'
export default function Component({ children }) {
return <ErrorWrapper title="Dashboard Error">{children}</ErrorWrapper>
}
```
### Recovering from errors
Use `retry()` to prompt the user to recover from the error. When called, the function re-fetches and re-renders the error boundary's contents. If successful, the fallback is replaced with the re-rendered result.
In most cases, use `retry()` instead of `reset()`. The `reset()` function only clears the error state and re-renders without re-fetching, which means it won't recover from Server Component errors.
```tsx filename="app/custom-error-boundary.tsx" highlight={9,12} switcher
'use client'
import { unstable_catchError } from 'next/error'
function ErrorFallback(
props: {},
{
error,
unstable_retry: retry,
reset,
}: { error: Error; unstable_retry: () => void; reset: () => void }
) {
return (
<div>
<p>{error.message}</p>
<button onClick={() => retry()}>Try again</button>
<button onClick={() => reset()}>Reset</button>
</div>
)
}
export default unstable_catchError(ErrorFallback)
```
```jsx filename="app/custom-error-boundary.js" highlight={7,10} switcher
'use client'
import { unstable_catchError } from 'next/error'
function ErrorFallback(props, { error, unstable_retry: retry, reset }) {
return (
<div>
<p>{error.message}</p>
<button onClick={() => retry()}>Try again</button>
<button onClick={() => reset()}>Reset</button>
</div>
)
}
export default unstable_catchError(ErrorFallback)
```
### Server-rendered error fallback
You can pass server-rendered content as a prop to display data-driven fallback UI. This works by rendering a Server Component as a `React.ReactNode` prop that the fallback displays when an error is caught.
> **Good to know**: This pattern eagerly renders the fallback on every page render, even when no error occurs. For most use cases, a simpler client-side fallback is sufficient.
```tsx filename="app/error-boundary.tsx" switcher
'use client'
import { unstable_catchError } from 'next/error'
import type { ErrorInfo } from 'next/error'
function ErrorFallback(
props: { fallback: React.ReactNode },
errorInfo: ErrorInfo
) {
return props.fallback
}
export default unstable_catchError(ErrorFallback)
```
```jsx filename="app/error-boundary.js" switcher
'use client'
import { unstable_catchError } from 'next/error'
function ErrorFallback(props, errorInfo) {
return props.fallback
}
export default unstable_catchError(ErrorFallback)
```
```tsx filename="app/some-component.tsx" switcher
import ErrorBoundary from '../error-boundary'
async function ErrorFallback() {
const data = await getData()
return <div>{data.message}</div>
}
export default function Component({ children }: { children: React.ReactNode }) {
return <ErrorBoundary fallback={<ErrorFallback />}>{children}</ErrorBoundary>
}
```
```jsx filename="app/some-component.js" switcher
import ErrorBoundary from '../error-boundary'
async function ErrorFallback() {
const data = await getData()
return <div>{data.message}</div>
}
export default function Component({ children }) {
return <ErrorBoundary fallback={<ErrorFallback />}>{children}</ErrorBoundary>
}
```
> **Good to know**:
>
> - Unlike the `error.js` file convention which is scoped to route segments, `unstable_catchError` can be used to wrap any part of your component tree for component-level error recovery.
> - Props passed to the wrapper component are forwarded to the fallback function, making it easy to create reusable error UIs with different configurations.
> - You don't need to wrap `error.js` default exports with `unstable_catchError`. The [`error.js`](/docs/app/api-reference/file-conventions/error) file convention already renders inside a built-in error boundary provided by Next.js.
## Version History
| Version | Changes |
| --------- | --------------------------------- |
| `v16.2.0` | `unstable_catchError` introduced. |
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment