From 9b6c8d6f3af138525d3ce3834758e356bb385f4d Mon Sep 17 00:00:00 2001
From: William Johnston <will@wwj.dev>
Date: Mon, 11 Oct 2021 12:53:18 -0700
Subject: [PATCH] doc: (#519) adding examples for getStaticPaths

---
 docs/next/guides/ssr-ssg.mdx | 59 ++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/docs/next/guides/ssr-ssg.mdx b/docs/next/guides/ssr-ssg.mdx
index 80a1ecceb..1812c0f18 100644
--- a/docs/next/guides/ssr-ssg.mdx
+++ b/docs/next/guides/ssr-ssg.mdx
@@ -56,6 +56,65 @@ The reason `MyPage` and `client` are passed to `getNextStaticProps` is because u
 
 This allows the developer to not have to think about batching/constructing queries, or data fetching. You are able to write your page as if you will be using Client-side Rendering (CSR). Then, you add the `getStaticProps` function above and can take advantage of SSG!
 
+### How To Handle `getStaticPaths`
+
+Next.js supports [SSG with `getStaticPaths`](https://nextjs.org/docs/basic-features/data-fetching#getstaticpaths-static-generation) as well. This function is used to build a list of paths that can be used to statically generate your site. This function should be used when you have a dynamic page that needs to be statically generated (e.g. `[postSlug].tsx`). In the `getStaticPaths` function you have the option to return the paths that you have several options that inform Next.js how you want to statically generate your pages. Consider the following examples:
+
+#### Statically Generate All Your Pages Upon Request
+
+If you don't know exactly how you want to statically generate your site, a good option for `getStaticPaths` is to inform Next.js not to generate any HTML at build time, but to generated it on-the-fly as new requests come in. You can do this as follows:
+
+```tsx title=src/pages/posts/[postSlug]/index.tsx
+export function getStaticPaths() {
+  return {
+    paths: [],
+    fallback: 'blocking',
+  };
+}
+```
+
+The above code will tell Next.js not to generate any pages up front. Then, as requests come in they will be generated server-side and stored for subsequent requests. Read more about [`fallback: 'blocking'`](https://nextjs.org/docs/basic-features/data-fetching#fallback-blocking).
+
+#### Statically Generate **Some** Of Your Pages At Build Time Based On A Query
+
+Maybe you want to generate a specific set of posts during build time. Perhaps you want to generate the most recent posts, or maybe you want to generate posts that receive a lot of traffic. You can do this by providing paths to Next.js that are based on a query as follows:
+
+```tsx title=src/pages/posts/[postSlug]/index.tsx
+import { client } from 'client';
+
+export async function getStaticPaths() {
+  const values = await client.client.inlineResolved(() => {
+    return client.client.query
+      .posts({
+        first: 5,
+      })
+      ?.nodes?.map((node) => node?.uri);
+  });
+  const paths = [];
+
+  if (Array.isArray(values)) {
+    paths.push(
+      ...values
+        .filter((value) => {
+          return typeof value === 'string';
+        }),
+    );
+  }
+
+  return {
+    paths,
+    fallback: 'blocking',
+  };
+```
+
+> **NOTE**: The code above assumes you have your permalink structure set to `/posts/%postname%/` in WordPress. You can add additional logic here to format the proper URL if that is not the case.
+
+The code above will perform an inline query to WordPress in order to get the 5 most recent posts. Then it will create a list of paths based on the post URIs. In this case we are not rendering all the post pages up front, so some will be dynamically generated on-the-fly using the `fallback: 'blocking'` feature in Next.js.
+
+
+The above scenarios are most common, but there are other options for [`getStaticPaths`](https://nextjs.org/docs/basic-features/data-fetching#getstaticpaths-static-generation) that might be useful depending upon your needs.
+
+
 ## SSR Using `getNextServerSideProps`
 
 This helper function lets you server side render your page with WordPress data. The function should be returned from `getServerSideProps`: