Unverified Commit cbb2f90e authored by Jiwon Choi's avatar Jiwon Choi Committed by GitHub

docs: error component `unstable_retry()` (#89732)

Adding docs for https://github.com/vercel/next.js/pull/89685
parent 9c17e9e7
......@@ -208,10 +208,10 @@ import { useEffect } from 'react'
export default function ErrorPage({
error,
reset,
unstable_retry,
}: {
error: Error & { digest?: string }
reset: () => void
unstable_retry: () => void
}) {
useEffect(() => {
// Log the error to an error reporting service
......@@ -223,8 +223,8 @@ export default function ErrorPage({
<h2>Something went wrong!</h2>
<button
onClick={
// Attempt to recover by trying to re-render the segment
() => reset()
// Attempt to recover by re-fetching and re-rendering the segment
() => unstable_retry()
}
>
Try again
......@@ -239,7 +239,7 @@ export default function ErrorPage({
import { useEffect } from 'react'
export default function ErrorPage({ error, reset }) {
export default function ErrorPage({ error, unstable_retry }) {
useEffect(() => {
// Log the error to an error reporting service
console.error(error)
......@@ -250,8 +250,8 @@ export default function ErrorPage({ error, reset }) {
<h2>Something went wrong!</h2>
<button
onClick={
// Attempt to recover by trying to re-render the segment
() => reset()
// Attempt to recover by re-fetching and re-rendering the segment
() => unstable_retry()
}
>
Try again
......@@ -338,17 +338,17 @@ While less common, you can handle errors in the root layout using the [`global-e
export default function GlobalError({
error,
reset,
unstable_retry,
}: {
error: Error & { digest?: string }
reset: () => void
unstable_retry: () => void
}) {
return (
// global-error must include html and body tags
<html>
<body>
<h2>Something went wrong!</h2>
<button onClick={() => reset()}>Try again</button>
<button onClick={() => unstable_retry()}>Try again</button>
</body>
</html>
)
......@@ -358,13 +358,13 @@ export default function GlobalError({
```jsx filename="app/global-error.js" switcher
'use client' // Error boundaries must be Client Components
export default function GlobalError({ error, reset }) {
export default function GlobalError({ error, unstable_retry }) {
return (
// global-error must include html and body tags
<html>
<body>
<h2>Something went wrong!</h2>
<button onClick={() => reset()}>Try again</button>
<button onClick={() => unstable_retry()}>Try again</button>
</body>
</html>
)
......
......@@ -24,10 +24,10 @@ import { useEffect } from 'react'
export default function Error({
error,
reset,
unstable_retry,
}: {
error: Error & { digest?: string }
reset: () => void
unstable_retry: () => void
}) {
useEffect(() => {
// Log the error to an error reporting service
......@@ -39,8 +39,8 @@ export default function Error({
<h2>Something went wrong!</h2>
<button
onClick={
// Attempt to recover by trying to re-render the segment
() => reset()
// Attempt to recover by re-fetching and re-rendering the segment
() => unstable_retry()
}
>
Try again
......@@ -55,7 +55,7 @@ export default function Error({
import { useEffect } from 'react'
export default function Error({ error, reset }) {
export default function Error({ error, unstable_retry }) {
useEffect(() => {
// Log the error to an error reporting service
console.error(error)
......@@ -66,8 +66,8 @@ export default function Error({ error, reset }) {
<h2>Something went wrong!</h2>
<button
onClick={
// Attempt to recover by trying to re-render the segment
() => reset()
// Attempt to recover by re-fetching and re-rendering the segment
() => unstable_retry()
}
>
Try again
......@@ -111,26 +111,26 @@ An instance of an [`Error`](https://developer.mozilla.org/docs/Web/JavaScript/Re
An automatically generated hash of the error thrown. It can be used to match the corresponding error in server-side logs.
#### `reset`
#### `unstable_retry`
The cause of an error can sometimes be temporary. In these cases, trying again might resolve the issue.
An error component can use the `reset()` function to prompt the user to attempt to recover from the error. When executed, the function will try to re-render the error boundary's contents. If successful, the fallback error component is replaced with the result of the re-render.
An error component can use the `unstable_retry()` function to prompt the user to attempt to recover from the error. When executed, the function will try to re-fetch and re-render the error boundary's contents. If successful, the fallback error component is replaced with the result of the re-render.
```tsx filename="app/dashboard/error.tsx" switcher
'use client' // Error boundaries must be Client Components
export default function Error({
error,
reset,
unstable_retry,
}: {
error: Error & { digest?: string }
reset: () => void
unstable_retry: () => void
}) {
return (
<div>
<h2>Something went wrong!</h2>
<button onClick={() => reset()}>Try again</button>
<button onClick={() => unstable_retry()}>Try again</button>
</div>
)
}
......@@ -139,16 +139,20 @@ export default function Error({
```jsx filename="app/dashboard/error.js" switcher
'use client' // Error boundaries must be Client Components
export default function Error({ error, reset }) {
export default function Error({ error, unstable_retry }) {
return (
<div>
<h2>Something went wrong!</h2>
<button onClick={() => reset()}>Try again</button>
<button onClick={() => unstable_retry()}>Try again</button>
</div>
)
}
```
#### `reset`
In most cases, you should use [`unstable_retry()`](#unstable_retry) instead. However, if you have a specific reason to clear the error state and re-render the error boundary's contents without re-fetching the contents, you can use the `reset()` function.
## Examples
### Global Error
......@@ -162,17 +166,17 @@ While less common, you can handle errors in the root layout or template using `g
export default function GlobalError({
error,
reset,
unstable_retry,
}: {
error: Error & { digest?: string }
reset: () => void
unstable_retry: () => void
}) {
return (
// global-error must include html and body tags
<html>
<body>
<h2>Something went wrong!</h2>
<button onClick={() => reset()}>Try again</button>
<button onClick={() => unstable_retry()}>Try again</button>
</body>
</html>
)
......@@ -182,13 +186,13 @@ export default function GlobalError({
```jsx filename="app/global-error.js" switcher
'use client' // Error boundaries must be Client Components
export default function GlobalError({ error, reset }) {
export default function GlobalError({ error, unstable_retry }) {
return (
// global-error must include html and body tags
<html>
<body>
<h2>Something went wrong!</h2>
<button onClick={() => reset()}>Try again</button>
<button onClick={() => unstable_retry()}>Try again</button>
</body>
</html>
)
......@@ -319,6 +323,7 @@ export default GracefullyDegradingErrorBoundary
| Version | Changes |
| --------- | ------------------------------------------- |
| `v16.2.0` | `unstable_retry` prop added. |
| `v15.2.0` | Also display `global-error` in development. |
| `v13.1.0` | `global-error` introduced. |
| `v13.0.0` | `error` 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