getStaticProps

Core Idea

Função async exportada de uma página do Pages Router que busca dados em build time e retorna props para prerenderizar HTML estático.

Key Concepts

• getStaticProps: roda só no servidor, nunca no client; nunca entra no bundle do browser (permite queries diretas a banco de dados).
• Quando usar: dado disponível em build time, vindo de CMS headless, precisa de SEO+performance máxima, e é publicamente cacheável (não específico por usuário).
• Quando roda: sempre durante next build; em background com fallback: true; antes do render inicial com fallback: blocking; em background com revalidate (ISR); on-demand com revalidate().
• HTML + JSON: build gera tanto o HTML da página quanto um JSON com o resultado de getStaticProps, usado em navegações client-side via next/link/next/router (sem re-executar a função).
• Onde pode ser usada: só em pages/* (página), nunca em _app, _document, _error ou arquivos não-página; deve ser export standalone, não propriedade do componente.
• Dev mode: roda em toda request durante next dev.
• Preview Mode: permite bypassar a geração estática e renderizar em request time.

Code Examples

import type { InferGetStaticPropsType, GetStaticProps } from 'next'

type Repo = { name: string; stargazers_count: number }

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 }>

export default function Page({
  repo,
}: InferGetStaticPropsType<typeof getStaticProps>) {
  return repo.stargazers_count
}

• O que demonstra: padrão TypeScript com satisfies GetStaticProps e InferGetStaticPropsType para tipagem inferida.

export async function loadPosts() {
  const res = await fetch('https://.../posts/')
  const data = await res.json()
  return data
}

import { loadPosts } from '../lib/load-posts'

export async function getStaticProps() {
  const posts = await loadPosts()
  return { props: { posts } }
}

• O que demonstra: compartilhar lógica de fetch server-only via lib/ em vez de chamar a própria API route (evita round-trip extra).

Anti-patterns

• Passar dados sensíveis via props: qualquer prop retornada é visível no HTML/JSON inicial no client, independente do método de rendering.
• Chamar a própria API route de dentro de getStaticProps: gera uma chamada de rede extra desnecessária; melhor extrair a lógica para lib/ e chamar direto.
• Exportar getStaticProps como propriedade do componente: só funciona como export standalone da página.
• Esquecer de repassar pageProps no _app customizado: sem isso, props de getStaticProps chegam vazias na página.

Key Takeaways

1. getStaticProps nunca vai para o bundle do client; pode fazer queries diretas a banco de dados com segurança.
2. Navegação client-side entre páginas com getStaticProps usa o JSON pré-computado, não re-executa a função.
3. Em dev, roda em toda request (diferente de produção, onde roda só no build ou em background via ISR).
4. Ferramenta next-code-elimination.vercel.app valida o que é removido do bundle client.

Connects To

• getstaticpaths: necessário junto com getStaticProps quando a página usa rota dinâmica.
• custom-app: exige repassar pageProps para a página funcionar.
• incremental-static-regeneration: revalidate e revalidate() on-demand.