From 5a8ca822a3ce0762c23ca00a4e24561bee2c3e49 Mon Sep 17 00:00:00 2001 From: JJ Kasper Date: Tue, 3 Mar 2020 11:46:43 -0600 Subject: [PATCH 1/9] Add docs for static 404 and pages/404 --- docs/advanced-features/custom-error-page.md | 22 ++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/advanced-features/custom-error-page.md b/docs/advanced-features/custom-error-page.md index 828ecf789a23606..83c1086ebf71aed 100644 --- a/docs/advanced-features/custom-error-page.md +++ b/docs/advanced-features/custom-error-page.md @@ -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. ## Reusing the built-in error page @@ -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`. + +## 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 new convention of a `pages/404` file that takes priority over `_error` for 404s specifically. This new 404 page is specifically meant for creating a static 404 page and strictly does not allow `getInitialProps` or `getServerSideProps` to be used. + +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 () => +``` + +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. From afbf18a9c2a6b0b36d36aa43ddc006523aae07eb Mon Sep 17 00:00:00 2001 From: JJ Kasper Date: Tue, 3 Mar 2020 11:49:32 -0600 Subject: [PATCH 2/9] Remove new from docs --- docs/advanced-features/custom-error-page.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced-features/custom-error-page.md b/docs/advanced-features/custom-error-page.md index 83c1086ebf71aed..6e41815d1821058 100644 --- a/docs/advanced-features/custom-error-page.md +++ b/docs/advanced-features/custom-error-page.md @@ -62,7 +62,7 @@ When you don't need to create a custom `_error` page and would prefer to use the ## 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 new convention of a `pages/404` file that takes priority over `_error` for 404s specifically. This new 404 page is specifically meant for creating a static 404 page and strictly does not allow `getInitialProps` or `getServerSideProps` to be used. +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. 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: From 712754f571f81d1fd847a420a385a0623aa08d99 Mon Sep 17 00:00:00 2001 From: JJ Kasper Date: Tue, 3 Mar 2020 18:27:26 -0600 Subject: [PATCH 3/9] Apply suggestions from code review Co-Authored-By: Shu Uesugi --- docs/advanced-features/custom-error-page.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced-features/custom-error-page.md b/docs/advanced-features/custom-error-page.md index 6e41815d1821058..852cfed5f4db91f 100644 --- a/docs/advanced-features/custom-error-page.md +++ b/docs/advanced-features/custom-error-page.md @@ -74,4 +74,4 @@ export default () => 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. +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. You can avoid this by making 404 pages static. From 03aaf87b5a84743affe825f701d339fcb9929e1b Mon Sep 17 00:00:00 2001 From: JJ Kasper Date: Tue, 3 Mar 2020 18:49:01 -0600 Subject: [PATCH 4/9] Rework using suggestions from review --- docs/advanced-features/custom-error-page.md | 53 +++++++++++---------- 1 file changed, 29 insertions(+), 24 deletions(-) diff --git a/docs/advanced-features/custom-error-page.md b/docs/advanced-features/custom-error-page.md index 852cfed5f4db91f..a885d2a482b9776 100644 --- a/docs/advanced-features/custom-error-page.md +++ b/docs/advanced-features/custom-error-page.md @@ -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. + +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

404 - Page Not Found

+} +``` + +## 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. + +### 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 }) { @@ -25,9 +50,9 @@ Error.getInitialProps = ({ res, err }) => { export default Error ``` -> `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. +> `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: @@ -55,23 +80,3 @@ 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`. - -## 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. - -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 () => -``` - -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 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. You can avoid this by making 404 pages static. From 57153f7ac44a84a6fd28886e89498b08255ada32 Mon Sep 17 00:00:00 2001 From: JJ Kasper Date: Wed, 4 Mar 2020 11:56:23 -0600 Subject: [PATCH 5/9] Apply suggestions from code review Co-Authored-By: Shu Uesugi --- docs/advanced-features/custom-error-page.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/advanced-features/custom-error-page.md b/docs/advanced-features/custom-error-page.md index a885d2a482b9776..b5b6bc35c1d1c05 100644 --- a/docs/advanced-features/custom-error-page.md +++ b/docs/advanced-features/custom-error-page.md @@ -4,7 +4,7 @@ description: Override and extend the built-in Error page to handle custom errors ## 404 Page -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. +A 404 page may be accessed very often. Server-rendering an 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. To avoid the above pitfalls, Next.js provides a static 404 page by default without having to add any additional files. @@ -25,7 +25,7 @@ export default function custom404() { ## 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. +By default Next.js provides a 500 error page that matches the default 404 page's style. Unlike the 404 page, the 500 page is not statically optimized because 500 errors happen dynamically. This is why we separate error handling for the 404 page and the 500 page. ### Customizing The Error Page From 44abf4757309e58d8f6db5dc753fe31d976a4d0c Mon Sep 17 00:00:00 2001 From: Tim Neutkens Date: Wed, 4 Mar 2020 19:34:19 +0100 Subject: [PATCH 6/9] Update custom-error-page.md --- docs/advanced-features/custom-error-page.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/docs/advanced-features/custom-error-page.md b/docs/advanced-features/custom-error-page.md index b5b6bc35c1d1c05..4c04dc22a26bb9e 100644 --- a/docs/advanced-features/custom-error-page.md +++ b/docs/advanced-features/custom-error-page.md @@ -4,17 +4,13 @@ description: Override and extend the built-in Error page to handle custom errors ## 404 Page -A 404 page may be accessed very often. Server-rendering an 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. +A 404 page may be accessed very often. Server-rendering an error page for every visit increases the load of the Next.js server.. This can result in increased costs and slow experiences. 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`. +To create a custom 404 page you can create a `pages/404.js` file. This file is statically generated at build time. ```jsx // pages/404.js @@ -23,13 +19,13 @@ export default function custom404() { } ``` -## 500 Page -By default Next.js provides a 500 error page that matches the default 404 page's style. Unlike the 404 page, the 500 page is not statically optimized because 500 errors happen dynamically. This is why we separate error handling for the 404 page and the 500 page. +## 500 Page +By default Next.js provides a 500 error page that matches the default 404 page’s style. This page is not statically optimized as it allows server-side errors to be reported. This is why 404 and 500 (other errors) are separated. ### 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: +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 }) { @@ -50,7 +46,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. In development you’ll get an error with the call stack to know where the error originated from. ### Reusing the built-in error page From 0899633eddd782558babc851321380e041a9a628 Mon Sep 17 00:00:00 2001 From: Tim Neutkens Date: Wed, 4 Mar 2020 19:34:46 +0100 Subject: [PATCH 7/9] Update custom-error-page.md --- docs/advanced-features/custom-error-page.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced-features/custom-error-page.md b/docs/advanced-features/custom-error-page.md index 4c04dc22a26bb9e..4c6489aa3f4a144 100644 --- a/docs/advanced-features/custom-error-page.md +++ b/docs/advanced-features/custom-error-page.md @@ -4,7 +4,7 @@ description: Override and extend the built-in Error page to handle custom errors ## 404 Page -A 404 page may be accessed very often. Server-rendering an error page for every visit increases the load of the Next.js server.. This can result in increased costs and slow experiences. +A 404 page may be accessed very often. Server-rendering an error page for every visit increases the load of the Next.js server. This can result in increased costs and slow experiences. To avoid the above pitfalls, Next.js provides a static 404 page by default without having to add any additional files. From 182129ebee55acd253933cd7d7a7ac20cca02a0b Mon Sep 17 00:00:00 2001 From: Tim Neutkens Date: Wed, 4 Mar 2020 19:39:06 +0100 Subject: [PATCH 8/9] Update custom-error-page.md --- docs/advanced-features/custom-error-page.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced-features/custom-error-page.md b/docs/advanced-features/custom-error-page.md index 4c6489aa3f4a144..e44ea17b63bcf33 100644 --- a/docs/advanced-features/custom-error-page.md +++ b/docs/advanced-features/custom-error-page.md @@ -14,7 +14,7 @@ To create a custom 404 page you can create a `pages/404.js` file. This file is ```jsx // pages/404.js -export default function custom404() { +export default function Custom404() { return

404 - Page Not Found

} ``` From 68ec4b5a5c2382572b3c5bd0e8ccb1eaa3b3a58e Mon Sep 17 00:00:00 2001 From: Tim Neutkens Date: Wed, 4 Mar 2020 19:43:58 +0100 Subject: [PATCH 9/9] Fix prettier --- docs/advanced-features/custom-error-page.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/advanced-features/custom-error-page.md b/docs/advanced-features/custom-error-page.md index e44ea17b63bcf33..24851e8df4014ee 100644 --- a/docs/advanced-features/custom-error-page.md +++ b/docs/advanced-features/custom-error-page.md @@ -10,7 +10,7 @@ To avoid the above pitfalls, Next.js provides a static 404 page by default witho ### Customizing The 404 Page -To create a custom 404 page you can create a `pages/404.js` file. This file is statically generated at build time. +To create a custom 404 page you can create a `pages/404.js` file. This file is statically generated at build time. ```jsx // pages/404.js @@ -19,8 +19,8 @@ export default function Custom404() { } ``` - ## 500 Page + By default Next.js provides a 500 error page that matches the default 404 page’s style. This page is not statically optimized as it allows server-side errors to be reported. This is why 404 and 500 (other errors) are separated. ### Customizing The Error Page