From 875e37fe16c711c70c38e117729cc0dda3c1fd32 Mon Sep 17 00:00:00 2001 From: William Johnston Date: Wed, 30 Jun 2021 16:26:54 -0700 Subject: [PATCH] doc: (#309) finishing 404 doc --- .../docs/next/reference/handle-404s.mdx | 44 +++++++++++++++++-- .../website/docs/next/reference/ssr-ssg.mdx | 2 +- 2 files changed, 41 insertions(+), 5 deletions(-) diff --git a/internal/website/docs/next/reference/handle-404s.mdx b/internal/website/docs/next/reference/handle-404s.mdx index 2864239eb..31b2ac6f1 100644 --- a/internal/website/docs/next/reference/handle-404s.mdx +++ b/internal/website/docs/next/reference/handle-404s.mdx @@ -7,17 +7,48 @@ description: Use a built-in Faust.js function to automatically determine if a pa # Handling 404s with `is404` +With Next.js you can return `{ notFound: true }` from `getServerSideProps` or `getStaticProps`, which will signal to Next.js that you want to send a `404 Not Found` response. When building a Headless WordPress site you would want to send a 404 in the following conditions: + +1. The user visits a `post` route for which no WordPress post exists. +1. The user visits a `page` route for which no associated WordPress page (or custom frontend page) exists. +1. The user visits a `category` route for which no associated WordPress category exists. + +To determine if you need to send a 404 you would need to make a request to WordPress for data and then determine if the response is enough to ensure you can render the page. Given that most of the time you will have dynamic Next.js pages for rendering `posts`, `pages`, and `categories`, you might think you have to do this work yourself. However, Faust.js makes this easy for you. + +Faust.js publishes an `is404` function that makes this easy for you. It functions similar to how the `usePost`, `usePage`, and `useCategory` hooks function, so it is able to determine the query you want to make based on URL params specified in your Next.js pages. The `is404` function has the following logic: + +### `is404` Logic For Posts: + +1. If `postId` is found in URL params, `is404` makes a request to retrieve a `post` from WordPress by `ID`. If no `post` is returned, `is404` returns `true`. +1. If `postSlug` is found in URL params, `is404` makes a request to retrieve a `post` from WordPress by `SLUG`. If no `post` is returned, `is404` returns `true`. +1. If `postUri` is found in URL params, `is404` makes a request to retrieve a `post` from WordPress by `URI`. If no `post` is returned, `is404` returns `true`. + +### `is404` Logic For Pages: + +1. If `pageId` is found in URL params, `is404` makes a request to retrieve a `page` from WordPress by `ID`. If no `page` is returned, `is404` returns `true`. +1. If `pageUri` is found in URL params, `is404` makes a request to retrieve a `page` from WordPress by `URI`. If no `page` is returned, `is404` returns `true`. + +### `is404` Logic For Categories: + +1. If `categoryId` is found in URL params, `is404` makes a request to retrieve a `category` from WordPress by `ID`. If no `category` is returned, `is404` returns `true`. +1. If `categorySlug` is found in URL params, `is404` makes a request to retrieve a `category` from WordPress by `SLUG`. If no `category` is returned, `is404` returns `true`. + +## How To Use `is404` + +`is404` should be called in either `getStaticProps` or `getServerSideProps`. The reason for this is that these are the server-side functions where you need to tell Next.js to send a `404 Not Found` server response. Below is some code in the a `post` page that utilizes `is404` to return a `{ notFound: true }` if necessary: + ```tsx title="src/pages/posts/[postSlug].tsx" -import { getNextStaticProps, client, is404 } from '@wpengine/headless-next'; +import { getNextStaticProps, is404 } from '@faust/next'; +import { client } from 'client'; -export default function MyPage() { - return( +export default function Page() { + return ( ... ) } export async function getStaticProps(context: GetStaticPropsContext) { - if (await is404(context)) { + if (await is404(client, context)) { return { notFound: true, }; @@ -25,6 +56,11 @@ export async function getStaticProps(context: GetStaticPropsContext) { return getNextStaticProps(context, { Page, + client, }); } ``` + +The above file name is `[postSlug].tsx` which will ensure that `postSlug` ends up in the URL params. When `is404` is invoked, it will find the `postSlug` URL param and make a request to WordPress to retrieve the `post` by `SLUG` using the `postSlug` param. If no `post` is returned, `is404` will return `true` and `getStaticProps` will subsequently return `{ notFound: true }`. + +> **NOTE:** `is404` does not have any relation to the `404.tsx` page you can define with Next.js. If you want to [customize your 404 page](https://nextjs.org/docs/advanced-features/custom-error-page#404-page) you can do that separately. diff --git a/internal/website/docs/next/reference/ssr-ssg.mdx b/internal/website/docs/next/reference/ssr-ssg.mdx index 3359e2c8a..651ccbd41 100644 --- a/internal/website/docs/next/reference/ssr-ssg.mdx +++ b/internal/website/docs/next/reference/ssr-ssg.mdx @@ -115,7 +115,7 @@ In order to properly facilitate SSR and SSG you must use the built-in component Using the `HeadlessProvider` component us easy, and if you are using an example `next` project published by Faust.js it will happen automatically. If you are adding `Faust.js` to your project, you will want to put `HeadlessProvider` at the top of your component tree. Typically in a Next.js app this means in your `pages/_app.tsx` file as follows: -```tsx {9,11} +```tsx title="src/pages/_app.tsx" {9,11} import React from 'react'; import { HeadlessProvider } from '@faustjs/next'; import { client } from 'client';