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
22 changes: 21 additions & 1 deletion docs/advanced-features/custom-error-page.md
Expand Up @@ -25,7 +25,7 @@ Error.getInitialProps = ({ res, err }) => {
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.
> `pages/_error.js` is only used in production for non-404 errors. In development you'll get an error with the call stack to know where the error originated from.
ijjk marked this conversation as resolved.
Show resolved Hide resolved

## Reusing the built-in error page

Expand Down Expand Up @@ -55,3 +55,23 @@ export default Page
```

The `Error` component also takes `title` as a property if you want to pass in a text message along with a `statusCode`.

## Default Static 404 Page

When you don't need to create a custom `_error` page and would prefer to use the default Next.js provided one, we will automatically apply the static optimization to this file during a production build and use it when deploying on [Now](https://zeit.co) or with `next start`.
ijjk marked this conversation as resolved.
Show resolved Hide resolved

## Static `pages/404`

For the cases where you do want a custom `_error` page but still want the benefits of a static 404 page we have added a convention of a `pages/404` file that takes priority over `_error` for 404s specifically. This 404 page is specifically meant for creating a static 404 page and strictly does not allow `getInitialProps` or `getServerSideProps` to be used.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Maybe add .js (even though it could be TS, I think people will understand): pages/404.js
  • Earlier it said "pages/_error.js is only used in production for non-404 errors" but this paragraph says "takes priority over _error for 404s" - so 404 may be rendered by _error? In that case, the earlier sentence was incorrect?
  • specifically is used twice, I think the second one can be removed.
  • How about getStaticProps?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point, I reworked it using the above mentioned structure. Let me know if this seems better


In the case where you want to use the default 404 page provided by Next.js but still need a custom `_error` page to report any errors, you can achieve this with:

```jsx
// pages/404.js
import Error from 'next/error'
export default () => <Error statusCode={404} />
```

If you have a custom `_app` with `getInitialProps`, the automatic static optimization will not be able to be applied since you are defining a global data dependency. A `pages/404` file can still be added in this case even though the optimization will not be applied.

A 404 page can end up being visited very often, this means rendering the `_error` page every time it is visited which increases the load on your server or increases the invocations for serverless functions. This additional load on your infrastructure is not ideal as it costs more and is a slower experience. Using the two above strategies to ensure the 404 page is static allows you to achieve the above benefits and have a more optimal 404 page.
ijjk marked this conversation as resolved.
Show resolved Hide resolved