getStaticPaths

When exporting a function calledgetStaticPaths from a page that usesDynamic Routes, Next.js will statically pre-render all the paths specified bygetStaticPaths.

importtype {  InferGetStaticPropsType,  GetStaticProps,  GetStaticPaths,}from'next'typeRepo= {  name:string  stargazers_count:number}exportconstgetStaticPaths= (async ()=> {return {    paths: [      {        params: {          name:'next.js',        },      },// See the "paths" section below    ],    fallback:true,// false or "blocking"  }})satisfiesGetStaticPathsexportconstgetStaticProps= (async (context)=> {constres=awaitfetch('https://api.github.com/repos/vercel/next.js')constrepo=awaitres.json()return { props: {repo } }})satisfiesGetStaticProps<{repo:Repo}>exportdefaultfunctionPage({repo,}:InferGetStaticPropsType<typeof getStaticProps>) {returnrepo.stargazers_count}

getStaticPaths return values

ThegetStaticPaths function should return an object with the followingrequired properties:

paths

Thepaths key determines which paths will be pre-rendered. For example, suppose that you have a page that usesDynamic Routes namedpages/posts/[id].js. If you exportgetStaticPaths from this page and return the following forpaths:

return {  paths: [    { params: { id:'1' }},    {      params: { id:'2' },// with i18n configured the locale for the path can be returned as well      locale:"en",    },  ],  fallback:...}

Then, Next.js will statically generate/posts/1 and/posts/2 duringnext build using the page component inpages/posts/[id].js.

The value for eachparams object must match the parameters used in the page name:

• If the page name ispages/posts/[postId]/[commentId], thenparams should containpostId andcommentId.
• If the page name usescatch-all routes likepages/[...slug], thenparams should containslug (which is an array). If this array is['hello', 'world'], then Next.js will statically generate the page at/hello/world.
• If the page uses anoptional catch-all route, usenull,[],undefined orfalse to render the root-most route. For example, if you supplyslug: false forpages/[[...slug]], Next.js will statically generate the page/.

Theparams strings arecase-sensitive and ideally should be normalized to ensure the paths are generated correctly. For example, ifWoRLD is returned for a param it will only match ifWoRLD is the actual path visited, notworld orWorld.

Separate of theparams object alocale field can be returned wheni18n is configured, which configures the locale for the path being generated.

fallback: false

Iffallback isfalse, then any paths not returned bygetStaticPaths will result in a404 page.

Whennext build is run, Next.js will check ifgetStaticPaths returnedfallback: false, it will then buildonly the paths returned bygetStaticPaths. This option is useful if you have a small number of paths to create, or new page data is not added often. If you find that you need to add more paths, and you havefallback: false, you will need to runnext build again so that the new paths can be generated.

The following example pre-renders one blog post per page calledpages/posts/[id].js. The list of blog posts will be fetched from a CMS and returned bygetStaticPaths. Then, for each page, it fetches the post data from a CMS usinggetStaticProps.

functionPost({ post }) {// Render post...}// This function gets called at build timeexportasyncfunctiongetStaticPaths() {// Call an external API endpoint to getpostsconstres=awaitfetch('https://.../posts')constposts=awaitres.json()// Get the paths we want to pre-render based onpostsconstpaths=posts.map((post)=> ({    params: { id:post.id },  }))// We'll pre-render only these paths at build time.// { fallback: false } means other routes should 404.return { paths, fallback:false }}// This also gets called at build timeexportasyncfunctiongetStaticProps({ params }) {// params contains the post `id`.// If the route is like /posts/1, then params.id is 1constres=awaitfetch(`https://.../posts/${params.id}`)constpost=awaitres.json()// Pass post data to the page via propsreturn { props: { post } }}exportdefault Post

fallback: true

Iffallback istrue, then the behavior ofgetStaticProps changes in the following ways:

• The paths returned fromgetStaticPaths will be rendered toHTML at build time bygetStaticProps.
• The paths that have not been generated at build time willnot result in a 404 page. Instead, Next.js will serve a“fallback” version of the page on the first request to such a path. Web crawlers, such as Google, won't be served a fallback and instead the path will behave as infallback: 'blocking'.
• When a page withfallback: true is navigated to throughnext/link ornext/router (client-side) Next.js willnot serve a fallback and instead the page will behave asfallback: 'blocking'.
• In the background, Next.js will statically generate the requested pathHTML andJSON. This includes runninggetStaticProps.
• When complete, the browser receives theJSON for the generated path. This will be used to automatically render the page with the required props. From the user’s perspective, the page will be swapped from the fallback page to the full page.
• At the same time, Next.js adds this path to the list of pre-rendered pages. Subsequent requests to the same path will serve the generated page, like other pages pre-rendered at build time.

Good to know:fallback: true is not supported when usingoutput: 'export'.

When isfallback: true useful?

fallback: true is useful if your app has a very large number of static pages that depend on data (such as a very large e-commerce site). If you want to pre-render all product pages, the builds would take a very long time.

Instead, you may statically generate a small subset of pages and usefallback: true for the rest. When someone requests a page that is not generated yet, the user will see the page with a loading indicator or skeleton component.

Shortly after,getStaticProps finishes and the page will be rendered with the requested data. From now on, everyone who requests the same page will get the statically pre-rendered page.

This ensures that users always have a fast experience while preserving fast builds and the benefits of Static Generation.

fallback: true will notupdate generated pages, for that take a look atIncremental Static Regeneration.

fallback: 'blocking'

Iffallback is'blocking', new paths not returned bygetStaticPaths will wait for theHTML to be generated, identical to SSR (hence whyblocking), and then be cached for future requests so it only happens once per path.

getStaticProps will behave as follows:

• The paths returned fromgetStaticPaths will be rendered toHTML at build time bygetStaticProps.
• The paths that have not been generated at build time willnot result in a 404 page. Instead, Next.js will SSR on the first request and return the generatedHTML.
• When complete, the browser receives theHTML for the generated path. From the user’s perspective, it will transition from "the browser is requesting the page" to "the full page is loaded". There is no flash of loading/fallback state.
• At the same time, Next.js adds this path to the list of pre-rendered pages. Subsequent requests to the same path will serve the generated page, like other pages pre-rendered at build time.

fallback: 'blocking' will notupdate generated pages by default. To update generated pages, useIncremental Static Regeneration in conjunction withfallback: 'blocking'.

Good to know:fallback: 'blocking' is not supported when usingoutput: 'export'.

Fallback pages

In the “fallback” version of a page:

• The page’s props will be empty.
• Using therouter, you can detect if the fallback is being rendered,router.isFallback will betrue.

The following example showcases usingisFallback:

import { useRouter }from'next/router'functionPost({ post }) {constrouter=useRouter()// If the page is not yet generated, this will be displayed// initially until getStaticProps() finishes runningif (router.isFallback) {return <div>Loading...</div>  }// Render post...}// This function gets called at build timeexportasyncfunctiongetStaticPaths() {return {// Only `/posts/1` and `/posts/2` are generated at build time    paths: [{ params: { id:'1' } }, { params: { id:'2' } }],// Enable statically generating additional pages// For example: `/posts/3`    fallback:true,  }}// This also gets called at build timeexportasyncfunctiongetStaticProps({ params }) {// params contains the post `id`.// If the route is like /posts/1, then params.id is 1constres=awaitfetch(`https://.../posts/${params.id}`)constpost=awaitres.json()// Pass post data to the page via propsreturn {    props: { post },// Re-generate the post at most once per second// if a request comes in    revalidate:1,  }}exportdefault Post

Version History