getStaticPaths

Core Idea

getStaticPaths, exported from a dynamic-route page, tells Next.js which paths to statically prerender at build time, and how to handle paths not in that list via fallback.

Key Concepts

• paths: array of { params: {...}, locale? } objects; params keys must match the dynamic segment names (including arrays for catch-all routes, null/[]/false for optional catch-all root).
• fallback: false: any path not returned results in a 404; must re-run next build to add paths.
• fallback: true: ungenerated paths serve a fallback UI first (router.isFallback === true), then swap to the real page once getStaticProps finishes in the background; client-side navigations instead behave like 'blocking'.
• fallback: 'blocking': ungenerated paths SSR on first request (like SSR), then are cached for subsequent requests; no fallback flash.
• router.isFallback: from useRouter, detects the fallback render state.
• params case sensitivity: values are case-sensitive and should be normalized.

Code Examples

export const getStaticPaths = (async () => {
  return {
    paths: [{ params: { name: 'next.js' } }],
    fallback: true, // false or "blocking"
  }
}) satisfies GetStaticPaths

• O que demonstra: minimal getStaticPaths shape with fallback: true.

export async function getStaticPaths() {
  const res = await fetch('https://.../posts')
  const posts = await res.json()
  const paths = posts.map((post) => ({ params: { id: post.id } }))
  return { paths, fallback: false }
}

• O que demonstra: generating paths dynamically from a CMS with fallback: false.

import { useRouter } from 'next/router'

function Post({ post }) {
  const router = useRouter()
  if (router.isFallback) return <div>Loading...</div>
  // Render post...
}

• O que demonstra: rendering a loading state while fallback: true regenerates a page.

Reference Tables

fallback value	Ungenerated path behavior	Client-side nav behavior	Updates existing pages?
false	404	404	No — needs rebuild
true	fallback UI, then swap once ready	acts like 'blocking'	No — pair with ISR revalidate
'blocking'	SSR on first request, then cached	SSR on first request	No — pair with ISR revalidate

Anti-patterns

• fallback: true/'blocking' with output: 'export': not supported for static exports.
• Expecting fallback: true/'blocking' to auto-update pages: they only generate missing pages once; use Incremental Static Regeneration (revalidate) to refresh existing ones.
• Mismatched params casing: WoRLD only matches the literal path WoRLD, not world.

Key Takeaways

1. Use fallback: false for small, rarely-changing path sets; true/'blocking' for very large catalogs where prebuilding everything is too slow.
2. Web crawlers never see the fallback state, they get 'blocking'-like SSR behavior even under fallback: true.
3. Always pair getStaticPaths with a corresponding getStaticProps on the same page.
4. App Router's generateStaticParams() is the stable successor since v13.4.0.

Connects To

• getStaticProps: required companion function that actually fetches the data for each path.
• useRouter: source of router.isFallback.
• Incremental Static Regeneration: mechanism to refresh pages generated via fallback.