Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update rendering error page #22523

Merged
merged 15 commits into from Aug 9, 2023
31 changes: 29 additions & 2 deletions docs/1.getting-started/8.error-handling.md
Expand Up @@ -57,9 +57,36 @@ You can change this behavior by setting `experimental.emitRouteChunkError` to `f

## Rendering an Error Page

When Nuxt encounters a fatal error, whether during the server lifecycle, or when rendering your Vue application (both SSR and SPA), it will either render a JSON response (if requested with `Accept: application/json` header) or an HTML error page.
When Nuxt encounters a fatal error (error which can’t be passed) it will either render a JSON response (if requested with `Accept: application/json` header) or trigger a full-screen error page.
mihul87 marked this conversation as resolved.
Show resolved Hide resolved

This error may occur during the server lifecycle when:
β€’ Vue app instance is initialized (`app:created` hook)
β€’ it is rendered into HTML (`app:rendered` hook).
mihul87 marked this conversation as resolved.
Show resolved Hide resolved

The same case will happen on the client side in SPA when the initial vueApp instance is created (`app:created` hook).

mihul87 marked this conversation as resolved.
Show resolved Hide resolved
On the client side for both, SSR and SPA, the fatal error can occur:
β€’ before mounting the application (`app:beforemount` hook)
β€’ on mounting process if the error was not handled with `onErrorCaptured` or `vue:error` hook
β€’ the Vue app is initialized and mounted in browser (`app:mounted`).
mihul87 marked this conversation as resolved.
Show resolved Hide resolved

The lifecycle hooks are listed in
::{link="/docs/api/advanced/hooks"}::
danielroe marked this conversation as resolved.
Show resolved Hide resolved

You can customize this error page by adding `~/error.vue` in the source directory of your application, alongside `app.vue` (not in the not in pages directory). This page has a single prop - `error` which contains an error for you to handle.
mihul87 marked this conversation as resolved.
Show resolved Hide resolved

The `error` object provides the fields: `url`, `statusCode`, `statusMessage`, `message`, `description` and `data`. In case you have an error with custom fields they will be lost. For custom errors we highly recommend to use `onErrorCaptured` composable than can be called in a page/component setup function or `vue:error` runtime nuxt hook that should be configured in a nuxt plugin.
danielroe marked this conversation as resolved.
Show resolved Hide resolved

### Example

danielroe marked this conversation as resolved.
Show resolved Hide resolved
```ts
export default defineNuxtPlugin(nuxtApp => {
nuxtApp.hook('vue:error', (err) => {
//
})
})
```

You can customize this error page by adding `~/error.vue` in the source directory of your application, alongside `app.vue`. This page has a single prop - `error` which contains an error for you to handle.

When you are ready to remove the error page, you can call the `clearError` helper function, which takes an optional path to redirect to (for example, if you want to navigate to a 'safe' page).

Expand Down
1 change: 1 addition & 0 deletions playground/app.vue
Expand Up @@ -11,3 +11,4 @@
<style scoped>

</style>