Version | Changes |
---|---|
v9.5.0 | Stable Incremental Static Regeneration |
v9.3.0 | getStaticPaths introduced. |
When exporting a function called getStaticPaths
from a page that uses Dynamic Routes, Next.js will statically pre-render all the paths specified by getStaticPaths
.
export async function getStaticPaths() {
return {
paths: [
{ params: { ... } } // See the "paths" section below
],
fallback: true, false or "blocking" // See the "fallback" section below
};
}
The getStaticPaths
function should return an object with the following required properties:
paths
The paths
key determines which paths will be pre-rendered. For example, suppose that you have a page that uses Dynamic Routes named pages/posts/[id].js
. If you export getStaticPaths
from this page and return the following for paths
:
return {
paths: [
{ params: { id: '1' } },
{ params: { id: '2' } }
],
fallback: ...
}
Then, Next.js will statically generate /posts/1
and /posts/2
during next build
using the page component in pages/posts/[id].js
.
The value for each params
object must match the parameters used in the page name:
pages/posts/[postId]/[commentId]
, then params
should contain postId
and commentId
.pages/[...slug]
, then params
should contain slug
(which is an array). If this array is ['hello', 'world']
, then Next.js will statically generate the page at /hello/world
.null
, []
, undefined
or false
to render the root-most route. For example, if you supply slug: false
for pages/[[...slug]]
, Next.js will statically generate the page /
.fallback: false
If fallback
is false
, then any paths not returned by getStaticPaths
will result in a 404 page.
When next build
is run, Next.js will check if getStaticPaths
returned fallback: false
, it will then build only the paths returned by getStaticPaths
. 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 have fallback: false
, you will need to run next build
again so that the new paths can be generated.
The following example pre-renders one blog post per page called pages/posts/[id].js
. The list of blog posts will be fetched from a CMS and returned by getStaticPaths
. Then, for each page, it fetches the post data from a CMS using getStaticProps
.
// pages/posts/[id].js
function Post({ post }) {
// Render post...
}
// This function gets called at build time
export async function getStaticPaths() {
// Call an external API endpoint to get posts
const res = await fetch('https://.../posts')
const posts = await res.json()
// Get the paths we want to pre-render based on posts
const paths = 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 time
export async function getStaticProps({ params }) {
// params contains the post `id`.
// If the route is like /posts/1, then params.id is 1
const res = await fetch(`https://.../posts/${params.id}`)
const post = await res.json()
// Pass post data to the page via props
return { props: { post } }
}
export default Post
fallback: true
If fallback
is true
, then the behavior of getStaticProps
changes in the following ways:
getStaticPaths
will be rendered to HTML
at build time by getStaticProps
.fallback: 'blocking'
.HTML
and JSON
. This includes running getStaticProps
.JSON
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.Note:
fallback: true
is not supported when usingnext export
.
fallback: 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 use fallback: 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 not update generated pages, for that take a look at Incremental Static Regeneration.
fallback: 'blocking'
If fallback
is 'blocking'
, new paths not returned by getStaticPaths
will wait for the HTML
to be generated, identical to SSR (hence why blocking), and then be cached for future requests so it only happens once per path.
getStaticProps
will behave as follows:
getStaticPaths
will be rendered to HTML
at build time by getStaticProps
.HTML
.HTML
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.fallback: 'blocking'
will not update generated pages by default. To update generated pages, use Incremental Static Regeneration in conjunction with fallback: 'blocking'
.
Note:
fallback: 'blocking'
is not supported when usingnext export
.
In the “fallback” version of a page:
router.isFallback
will be true
.The following example showcases using isFallback
:
// pages/posts/[id].js
import { useRouter } from 'next/router'
function Post({ post }) {
const router = useRouter()
// If the page is not yet generated, this will be displayed
// initially until getStaticProps() finishes running
if (router.isFallback) {
return <div>Loading...</div>
}
// Render post...
}
// This function gets called at build time
export async function getStaticPaths() {
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 time
export async function getStaticProps({ params }) {
// params contains the post `id`.
// If the route is like /posts/1, then params.id is 1
const res = await fetch(`https://.../posts/${params.id}`)
const post = await res.json()
// Pass post data to the page via props
return {
props: { post },
// Re-generate the post at most once per second
// if a request comes in
revalidate: 1,
}
}
export default Post
For TypeScript, you can use the GetStaticPaths
type from next
:
import { GetStaticPaths } from 'next'
export const getStaticPaths: GetStaticPaths = async () => {
// ...
}