Customizing App, Document and Error Pages in NextJS

Next.js uses the App component to initialize pages. You can override it creating a ./pages/_app.js file if, for example. you want to do some of the following things:

Persisting layout between page changes
Keeping state when navigating pages
Custom error handling using componentDidCatch
Inject additional data into pages
Add global CSS

1
function MyApp({ Component, pageProps }) {
2
  return <Component {...pageProps} />
3
}
4

5
export default MyApp

The Component prop is the active page, so whenever you navigate between routes, Component will change to the new page.

Customizing Document

You can create a ./pages/_document.js to augment your application’s and tags.

1
import Document, { Html, Head, Main, NextScript } from 'next/document'
2

3
class MyDocument extends Document {
4
  render() {
5
    return (
6
      <Html>
7
        <Head />
8
        <body>
9
          <Main />
10
          <NextScript />
11
        </body>
12
      </Html>
13
    )
14
  }
15
}
16

17
export default MyDocument

, , and are required for the page to be properly rendered. The component used here is not the same one from [`next/head`](https://nextjs.org/docs/api-reference/next/head). To set individual tags, you should use next/head in your pages or components.

Document is only rendered in the server, event handlers like onClick won’t work.

Custom Error pages

Next.js provides a static 404 page by default without having to add any additional files. To create a custom 404 page you can create a pages/404.js file. This file is statically generated at build time.

1
export default function Custom404() {
2
  return <h1>404 - Page Not Found</h1>
3
}

Same goes for 500 error page

1
export default function Custom500() {
2
  return <h1>500 - Server-side error occurred</h1>
3
}

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:

1
function Error({ statusCode }) {
2
  return (
3
    <p>
4
      {statusCode
5
        ? `An error ${statusCode} occurred on server`
6
        : 'An error occurred on client'}
7
    </p>
8
  )
9
}
10

11
Error.getInitialProps = ({ res, err }) => {
12
  const statusCode = res ? res.statusCode : err ? err.statusCode : 404
13
  return { statusCode }
14
}
15

16
export default Error