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' ...@@ -208,10 +208,10 @@ import { useEffect } from 'react'
export default function ErrorPage({ export default function ErrorPage({
error, error,
reset, unstable_retry,
}: { }: {
error: Error & { digest?: string } error: Error & { digest?: string }
reset: () => void unstable_retry: () => void
}) { }) {
useEffect(() => { useEffect(() => {
// Log the error to an error reporting service // Log the error to an error reporting service
...@@ -223,8 +223,8 @@ export default function ErrorPage({ ...@@ -223,8 +223,8 @@ export default function ErrorPage({
<h2>Something went wrong!</h2> <h2>Something went wrong!</h2>
<button <button
onClick={ onClick={
// Attempt to recover by trying to re-render the segment // Attempt to recover by re-fetching and re-rendering the segment
() => reset() () => unstable_retry()
} }
> >
Try again Try again
...@@ -239,7 +239,7 @@ export default function ErrorPage({ ...@@ -239,7 +239,7 @@ export default function ErrorPage({
import { useEffect } from 'react' import { useEffect } from 'react'
export default function ErrorPage({ error, reset }) { export default function ErrorPage({ error, unstable_retry }) {
useEffect(() => { useEffect(() => {
// Log the error to an error reporting service // Log the error to an error reporting service
console.error(error) console.error(error)
...@@ -250,8 +250,8 @@ export default function ErrorPage({ error, reset }) { ...@@ -250,8 +250,8 @@ export default function ErrorPage({ error, reset }) {
<h2>Something went wrong!</h2> <h2>Something went wrong!</h2>
<button <button
onClick={ onClick={
// Attempt to recover by trying to re-render the segment // Attempt to recover by re-fetching and re-rendering the segment
() => reset() () => unstable_retry()
} }
> >
Try again Try again
...@@ -338,17 +338,17 @@ While less common, you can handle errors in the root layout using the [`global-e ...@@ -338,17 +338,17 @@ While less common, you can handle errors in the root layout using the [`global-e
export default function GlobalError({ export default function GlobalError({
error, error,
reset, unstable_retry,
}: { }: {
error: Error & { digest?: string } error: Error & { digest?: string }
reset: () => void unstable_retry: () => void
}) { }) {
return ( return (
// global-error must include html and body tags // global-error must include html and body tags
<html> <html>
<body> <body>
<h2>Something went wrong!</h2> <h2>Something went wrong!</h2>
<button onClick={() => reset()}>Try again</button> <button onClick={() => unstable_retry()}>Try again</button>
</body> </body>
</html> </html>
) )
...@@ -358,13 +358,13 @@ export default function GlobalError({ ...@@ -358,13 +358,13 @@ export default function GlobalError({
```jsx filename="app/global-error.js" switcher ```jsx filename="app/global-error.js" switcher
'use client' // Error boundaries must be Client Components 'use client' // Error boundaries must be Client Components
export default function GlobalError({ error, reset }) { export default function GlobalError({ error, unstable_retry }) {
return ( return (
// global-error must include html and body tags // global-error must include html and body tags
<html> <html>
<body> <body>
<h2>Something went wrong!</h2> <h2>Something went wrong!</h2>
<button onClick={() => reset()}>Try again</button> <button onClick={() => unstable_retry()}>Try again</button>
</body> </body>
</html> </html>
) )
......
...@@ -24,10 +24,10 @@ import { useEffect } from 'react' ...@@ -24,10 +24,10 @@ import { useEffect } from 'react'
export default function Error({ export default function Error({
error, error,
reset, unstable_retry,
}: { }: {
error: Error & { digest?: string } error: Error & { digest?: string }
reset: () => void unstable_retry: () => void
}) { }) {
useEffect(() => { useEffect(() => {
// Log the error to an error reporting service // Log the error to an error reporting service
...@@ -39,8 +39,8 @@ export default function Error({ ...@@ -39,8 +39,8 @@ export default function Error({
<h2>Something went wrong!</h2> <h2>Something went wrong!</h2>
<button <button
onClick={ onClick={
// Attempt to recover by trying to re-render the segment // Attempt to recover by re-fetching and re-rendering the segment
() => reset() () => unstable_retry()
} }
> >
Try again Try again
...@@ -55,7 +55,7 @@ export default function Error({ ...@@ -55,7 +55,7 @@ export default function Error({
import { useEffect } from 'react' import { useEffect } from 'react'
export default function Error({ error, reset }) { export default function Error({ error, unstable_retry }) {
useEffect(() => { useEffect(() => {
// Log the error to an error reporting service // Log the error to an error reporting service
console.error(error) console.error(error)
...@@ -66,8 +66,8 @@ export default function Error({ error, reset }) { ...@@ -66,8 +66,8 @@ export default function Error({ error, reset }) {
<h2>Something went wrong!</h2> <h2>Something went wrong!</h2>
<button <button
onClick={ onClick={
// Attempt to recover by trying to re-render the segment // Attempt to recover by re-fetching and re-rendering the segment
() => reset() () => unstable_retry()
} }
> >
Try again Try again
...@@ -111,26 +111,26 @@ An instance of an [`Error`](https://developer.mozilla.org/docs/Web/JavaScript/Re ...@@ -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. 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. 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 ```tsx filename="app/dashboard/error.tsx" switcher
'use client' // Error boundaries must be Client Components 'use client' // Error boundaries must be Client Components
export default function Error({ export default function Error({
error, error,
reset, unstable_retry,
}: { }: {
error: Error & { digest?: string } error: Error & { digest?: string }
reset: () => void unstable_retry: () => void
}) { }) {
return ( return (
<div> <div>
<h2>Something went wrong!</h2> <h2>Something went wrong!</h2>
<button onClick={() => reset()}>Try again</button> <button onClick={() => unstable_retry()}>Try again</button>
</div> </div>
) )
} }
...@@ -139,16 +139,20 @@ export default function Error({ ...@@ -139,16 +139,20 @@ export default function Error({
```jsx filename="app/dashboard/error.js" switcher ```jsx filename="app/dashboard/error.js" switcher
'use client' // Error boundaries must be Client Components 'use client' // Error boundaries must be Client Components
export default function Error({ error, reset }) { export default function Error({ error, unstable_retry }) {
return ( return (
<div> <div>
<h2>Something went wrong!</h2> <h2>Something went wrong!</h2>
<button onClick={() => reset()}>Try again</button> <button onClick={() => unstable_retry()}>Try again</button>
</div> </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 ## Examples
### Global Error ### Global Error
...@@ -162,17 +166,17 @@ While less common, you can handle errors in the root layout or template using `g ...@@ -162,17 +166,17 @@ While less common, you can handle errors in the root layout or template using `g
export default function GlobalError({ export default function GlobalError({
error, error,
reset, unstable_retry,
}: { }: {
error: Error & { digest?: string } error: Error & { digest?: string }
reset: () => void unstable_retry: () => void
}) { }) {
return ( return (
// global-error must include html and body tags // global-error must include html and body tags
<html> <html>
<body> <body>
<h2>Something went wrong!</h2> <h2>Something went wrong!</h2>
<button onClick={() => reset()}>Try again</button> <button onClick={() => unstable_retry()}>Try again</button>
</body> </body>
</html> </html>
) )
...@@ -182,13 +186,13 @@ export default function GlobalError({ ...@@ -182,13 +186,13 @@ export default function GlobalError({
```jsx filename="app/global-error.js" switcher ```jsx filename="app/global-error.js" switcher
'use client' // Error boundaries must be Client Components 'use client' // Error boundaries must be Client Components
export default function GlobalError({ error, reset }) { export default function GlobalError({ error, unstable_retry }) {
return ( return (
// global-error must include html and body tags // global-error must include html and body tags
<html> <html>
<body> <body>
<h2>Something went wrong!</h2> <h2>Something went wrong!</h2>
<button onClick={() => reset()}>Try again</button> <button onClick={() => unstable_retry()}>Try again</button>
</body> </body>
</html> </html>
) )
...@@ -319,6 +323,7 @@ export default GracefullyDegradingErrorBoundary ...@@ -319,6 +323,7 @@ export default GracefullyDegradingErrorBoundary
| Version | Changes | | Version | Changes |
| --------- | ------------------------------------------- | | --------- | ------------------------------------------- |
| `v16.2.0` | `unstable_retry` prop added. |
| `v15.2.0` | Also display `global-error` in development. | | `v15.2.0` | Also display `global-error` in development. |
| `v13.1.0` | `global-error` introduced. | | `v13.1.0` | `global-error` introduced. |
| `v13.0.0` | `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