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

Add docs for static 404 and pages/404 #10811

Merged
merged 10 commits into from Mar 4, 2020
31 changes: 28 additions & 3 deletions docs/advanced-features/custom-error-page.md
Expand Up @@ -2,9 +2,34 @@
description: Override and extend the built-in Error page to handle custom errors.
---

# Custom Error Page
## 404 Page

**404** or **500** errors are handled both client-side and server-side by the `Error` component. If you wish to override it, define the file `pages/_error.js` and add the following code:
A 404 page may be accessed very often. Rendering the `_error` page for every visit increases the load for your server or the invocations for serverless functions. This can result in increased costs and slow experiences.
ijjk marked this conversation as resolved.
Show resolved Hide resolved

To avoid the above pitfalls, Next.js provides a static 404 page by default without having to add any additional files.

The static 404 page is automatically statically optimized at build time and used with `next start` and when deploying on [ZEIT Now](https://zeit.co).

If you have a custom `pages/_app.js` with `getInitialProps`, the automatic static optimization will not be able to be applied since you are defining a global data dependency.

### Customizing The 404 Page

To create a custom 404 page you can create a `pages/404.js` file. This file is meant to allow customizing the 404 page while keeping the page static and doesn't allow using any data-fetching methods like `getStaticProps`, `getServerSideProps`, or `getInitialProps`.

```jsx
// pages/404.js
export default function custom404() {
return <h1>404 - Page Not Found</h1>
}
```

## 500 Page

By default Next.js provides an error page that matches the default 404 page's style. This page is not statically optimized like the 404 page and is why we allow creating a separate `pages/404.js` file to enable you to report 500 errors without de-optimizing your 404 page.
ijjk marked this conversation as resolved.
Show resolved Hide resolved

### Customizing The Error Page

**500** errors are handled both client-side and server-side by the `Error` component. If you wish to override it, define the file `pages/_error.js` and add the following code:

```jsx
function Error({ statusCode }) {
Expand All @@ -27,7 +52,7 @@ export default Error

> `pages/_error.js` is only used in production. In development you'll get an error with the call stack to know where the error originated from.

## Reusing the built-in error page
### Reusing the built-in error page

If you want to render the built-in error page you can by importing the `Error` component:

Expand Down