Capítulo 356 de 456

getStaticPaths

Core Idea

Define, em build time, a lista de paths a prerenderizar para uma página de rota dinâmica que usa getStaticProps no Pages Router.

Key Concepts

  • getStaticPaths: função async exportada de uma página dinâmica (pages/repo/[name].js); retorna { paths, fallback }.
  • paths: array de objetos { params: { ... } } com os valores dos segmentos dinâmicos a prerenderizar.
  • fallback: false | true | 'blocking' — controla o comportamento de rotas não geradas no build.
  • Regra de dependência: getStaticPaths deve ser usada junto com getStaticProps; não pode ser combinada com getServerSideProps.
  • Only in pages: não pode ser exportada de components/ ou qualquer arquivo não-página; deve ser standalone export.

Code Examples

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

export const getStaticProps = (async (context) => {
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const repo = await res.json()
  return { props: { repo } }
}) satisfies GetStaticProps<{ repo: Repo }>
  • O que demonstra: getStaticPaths define os paths e getStaticProps busca os dados para cada um.
export async function getStaticPaths() {
  if (process.env.SKIP_BUILD_STATIC_GENERATION) {
    return { paths: [], fallback: 'blocking' }
  }
  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: gerar zero páginas no build (paths: [] + fallback: 'blocking') para builds de preview mais rápidos, versus gerar tudo em produção.

Reference Tables

fallbackComportamento
falserotas fora de paths retornam 404
truegetStaticProps roda em background; página inicial serve versão fallback até estar pronta
'blocking'getStaticProps é chamada antes do render inicial (sem fallback intermediário)

Anti-patterns

  • Combinar getStaticPaths com getServerSideProps: não suportado; são mutuamente exclusivos.
  • Gerar todas as páginas no build para ambientes de preview: causa builds lentos em sites com centenas/milhares de páginas; usar paths: [] + fallback para deferir geração.

Key Takeaways

  1. getStaticPaths roda só durante next build em produção (nunca em runtime); em dev roda a cada request.
  2. Gerar mais páginas no build = builds mais lentos; considerar geração on-demand via fallback para reduzir tempo de build.
  3. Precedência: rota exigida por getStaticPaths sempre acompanha getStaticProps no mesmo arquivo de página dinâmica.

Connects To

  • getstaticprops: par obrigatório de getStaticPaths.
  • dynamic-routes: convenção de arquivos [param].js, [...slug].js, [[...slug]].js.
  • incremental-static-regeneration: fallback: true/'blocking' como estratégias de geração incremental.
AnteriorgetStaticPropsPróximogetServerSideProps