Melhores Práticas de Renderização do Next.js

Um resumo condensado das 25 melhores práticas mais importantes, extraídas de cada página desta seção.

1. Prefira Server Components por padrão: Todo componente no App Router é um Server Component, a menos que você opte por sair com "use client". Portanto, utilize Server Components primeiro e só adicione a diretiva quando realmente precisar de hooks, eventos ou APIs do navegador.
2. Use await diretamente em Componentes Assíncronos: Server Components podem ser async e chamar await fetch(...) ou await db.query(...) no corpo da função. Pule estados de carregamento useEffect, já que hooks não são permitidos no servidor de qualquer forma.
3. Serializar Props Através da Fronteira: Props passadas de um Server Component para um Client Component devem ser serializáveis em JSON (strings, números, objetos simples, arrays, Server Actions). Funções regulares, instâncias de classe, Refs e Símbolos falham silenciosamente ou lançam erros.
4. Use server-only para Segredos: import "server-only" no topo de módulos que leem AUTH_SECRET, URLs de banco de dados ou chaves de assinatura faz com que o build falhe no momento em que um Client Component os importa, prevenindo vazamento para o bundle do navegador.
5. Empurre os Limites de use client para Baixo: Marcar um componente de nível superior como "use client" puxa todo filho e toda utilidade importada para o bundle do cliente. Extraia apenas a folha interativa (como um LikeButton) para o Client Component e mantenha seus pais renderizados no servidor.
6. Proteja APIs do Navegador em useEffect: window, document, localStorage e IntersectionObserver não existem durante o SSR, então acesse-os dentro de useEffect (ou atrás de uma verificação typeof window !== "undefined") e inicialize o estado com um valor seguro para o servidor primeiro.
7. Evite Discrepâncias de Hidratação: Nunca chame Date.now(), Math.random() ou leia window durante a renderização – o HTML do servidor e a re-renderização do cliente discordarão. Mova valores variáveis para useEffect ou use suppressHydrationWarning para casos deliberados.
8. Passe Server Components como filhos: Um Client Component não pode import um Server Component (a importação se torna silenciosamente apenas para o cliente), mas pode receber um através de children ou props JSX nomeadas. Orquestre a composição a partir de um componente pai Server Component.
9. Isole Providers em um Arquivo "use client": O Contexto do React requer um Client Component, mas colocar providers no layout raiz clientificaria tudo. Em vez disso, coloque-os em app/providers.tsx com "use client" e renderize <Providers>{children}</Providers> a partir do layout Server Component.
10. Extraia Apenas a Peça Interativa: Em vez de converter um card inteiro em um Client Component para um único botão, mantenha o card como um Server Component e extraia o botão (por exemplo, LikeButton) para seu próprio pequeno arquivo "use client".
11. Saiba o Que Dispara a Dinâmica: cookies(), headers(), searchParams, connection(), qualquer fetch com cache: "no-store", ou export const dynamic = "force-dynamic" optam a rota inteira para renderização dinâmica – um único uso em qualquer componente é suficiente.
12. Use generateStaticParams para Caminhos Conhecidos: Pré-renderize todos os caminhos que você pode listar no momento do build retornando seus params de generateStaticParams, e deixe dynamicParams = true (o padrão) para que novos caminhos sejam renderizados na primeira solicitação e depois cacheados.
13. revalidate: 0 Significa Sempre Dinâmico: export const revalidate = 0 é equivalente a force-dynamic, não "revalidar imediatamente". Use um inteiro positivo (por exemplo, revalidate = 60) para ISR e reserve 0 ou "no-store" para dados verdadeiramente por solicitação.
14. Não Misture force-static com Funções Dinâmicas: export const dynamic = "force-static" faz o build falhar se a página chamar cookies()/headers()/searchParams. Remova a chamada dinâmica ou volte para dynamic = "auto".
15. Habilite PPR Incrementalmente: Defina experimental: { ppr: "incremental" } em next.config.ts e opte pelas rotas uma a uma com export const experimental_ppr = true para que você possa lançar PPR progressivamente e verificar cada rota.
16. Envolva Filhos Dinâmicos com Suspense: Limites de Suspense definem a divisão entre o shell estático e o buraco dinâmico. Um componente dinâmico sem um <Suspense> circundante puxa a rota PPR inteira de volta para a renderização dinâmica completa.
17. Consolide Buracos Dinâmicos: Cada buraco de Suspense custa computação do servidor no momento da solicitação, então agrupe dados relacionados em tempo de solicitação em menos limites em vez de espalhar uma dúzia de pequenos e anular o shell da CDN.
18. Sempre Forneça sizes com fill: Um <Image fill> sem a prop sizes faz o navegador solicitar a maior variante em cada dispositivo. Forneça uma string ciente de breakpoints como "(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw" que corresponda ao layout.
19. Configure remotePatterns: Qualquer host de imagem externo precisa de uma entrada em images.remotePatterns em next.config.ts. Sem isso, imagens remotas lançam um erro de build/runtime e next/image se recusa a otimizá-las.
20. Reserve priority para Imagens LCP: Adicione priority apenas para uma ou duas imagens LCP acima da dobra. Isso desabilita o lazy loading e injeta uma dica de pré-carregamento, então o uso excessivo disso atrasa a página em vez de acelerá-la.
21. width/height Definem a Proporção, Não o Tamanho: As props width e height em next/image travam uma proporção para prevenção de CLS. Use CSS (className, dimensionamento do wrapper) para controlar o tamanho real que a imagem renderiza.
22. Use next/font para Auto-Hospedagem: next/font/google e next/font/local baixam e servem fontes de sua própria origem com cabeçalhos de cache imutáveis, eliminando requisições externas, FOUT e CLS através de métricas de fallback geradas automaticamente.
23. Aplique className ou variable ao DOM: Fontes só ativam quando você anexa inter.className (ou inter.variable) a <html>, <body> ou ao contêiner relevante. Uma classe esquecida é o bug mais comum de "minha fonte não está carregando".
24. Omita o Peso para Fontes Variáveis: Passar weight: ["400", "700"] explícito para uma fonte que tem uma build variável força o Next.js a baixar múltiplos arquivos estáticos em vez de um arquivo variável. Remova weight quando a fonte suportar para manter o bundle pequeno.
25. Prefira display: swap: Use display: "swap" (o padrão recomendado) para que uma fonte de fallback apareça imediatamente e seja substituída quando a fonte customizada carregar. display: "optional" pode deixar o texto invisível se a fonte não chegar em cerca de 100ms.