Melhores Práticas de Dados do Next.js

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

1. Busque Dentro de Server Components async: Coloque await fetch(...) diretamente no corpo do Server Component em vez de usar useEffect - sem estado de carregamento, sem cascata do cliente e os dados são enviados como HTML.
2. Aguarde params e searchParams: No Next.js 15+, ambos são Promises, então desestruturar sem await retorna um objeto Promise (frequentemente renderizado como [object Promise]); sempre faça const { slug } = await params.
3. Paralelize Buscas Independentes Com Promise.all: Envolva leituras independentes - const [user, posts] = await Promise.all([getUser(id), getPosts(id)]) - para que a latência total seja igual à chamada mais lenta em vez da soma, e deixe o TypeScript inferir a tupla de resultado gratuitamente.
4. Evite Cascatas Acidentais: Nunca encadeie const a = await getA(); const b = await getB(); para dados independentes - as promises começam na criação, mas cada await ainda bloqueia a linha seguinte, produzindo latência sequencial.
5. Use Promise.allSettled para Dados Opcionais: Quando uma fonte não é crítica (recomendações, análises), Promise.allSettled evita que uma única rejeição descarte os outros resultados bem-sucedidos e permite que você renderize uma página parcial.
6. Envolva Chamadas que Não sejam fetch Com React.cache: A memoização de requisições cobre apenas a API fetch, então envolva funções de banco de dados e ORM - const getUser = cache((id: string) => db.user.findUnique({ where: { id } })) - para obter deduplicação por renderização em layouts e páginas.
7. Isole Buscas no-store Atrás de Suspense: Um único cache: "no-store" em qualquer lugar de uma rota opta a rota inteira para renderização dinâmica; mova-o para um componente separado envolvido em <Suspense> para que o restante possa permanecer estático.
8. Seja Explícito Sobre as Opções de Cache do fetch: O padrão do Next.js 15 é cache: "auto" (não force-cache), então defina cache ou next.revalidate em cada fetch em vez de confiar no que o framework infere.
9. Nomeie Tags de Revalidação Especificamente: As tags são globais - fetch(url, { next: { tags: ["product-abc123"] } }) - use strings com namespace em vez de "data" genérico para que revalidateTag("product-abc123") não apague silenciosamente caches não relacionados.
10. Entenda Stale-While-Revalidate: revalidatePath/revalidateTag marcam o cache como obsoleto para a próxima requisição - a resposta atual ainda retorna dados obsoletos, então use cache: "no-store" quando precisar de atualidade imediata.
11. Use "layout" para Atualizar Páginas Aninhadas: revalidatePath("/") atualiza apenas a página raiz; passe "layout" - revalidatePath("/dashboard", "layout") - para invalidar o layout mais todas as páginas filhas sob ele.
12. Use unstable_cache Com Chaves Únicas: Para fontes que não são fetch e precisam de cache persistente, unstable_cache(fn, keyParts, { tags, revalidate }) é a ferramenta - mas dê a cada chamada keyParts distintas e descritivas ou você retornará dados corrompidos de colisões de chaves.
13. Chame router.refresh Após Mutações do Cliente: Após uma Server Action atualizar dados, o Cache do Router do lado do cliente pode continuar servindo páginas obsoletas no back/forward, então acione router.refresh() (ou ajuste experimental.staleTimes) para limpá-lo.
14. Valide Entradas de Server Actions no Servidor: Server Actions são endpoints POST alcançáveis cujos argumentos podem ser valores fechados enviados ao cliente, então valide cada campo dentro da action e nunca confie em closures para esconder segredos.
15. Chame redirect Fora de try/catch: redirect() lança um erro sentinela que o Next.js captura para realizar a navegação; envolver em try/catch engole o redirect, então coloque-o após sua mutação e fora de qualquer manipulador de erro.
16. Retorne Erros Via useActionState: Quando um formulário precisa de feedback de validação, digite a action como (prevState, formData) => Promise<State> e conecte-a através de useActionState para que o estado pendente e as mensagens de erro fluam pelo React de forma limpa.
17. Combine useOptimistic Com useTransition: Para UIs responsivas, chame addOptimistic dentro de startTransition - startTransition(async () => { addOptimistic(newItem); await saveItem(newItem) }) - para que os usuários vejam a mudança instantaneamente e o sinalizador pendente ainda controle os estados desabilitados.
18. Use Limites de Suspense Granulares: Envolva cada fonte de dados independente em seu próprio <Suspense> para que os widgets sejam transmitidos à medida que resolvem; um único limite no nível superior bloqueia a página inteira na consulta mais lenta e derrota o streaming.
19. Dimensiona Esqueletos Para Corresponder ao Conteúdo Final: Fallbacks devem compartilhar a proporção ou as dimensões fixas do conteúdo real, caso contrário, o layout salta quando os dados chegam e você sofre um impacto evitável de CLS.
20. Combine Suspense Com error.tsx: Se qualquer filho async lançar um erro, o erro borbulha para além do Suspense; cada limite de Suspense deve ter um limite de erro correspondente (error.tsx ou <ErrorBoundary>) no mesmo nível.
21. Envolva useSearchParams em Suspense: No cliente, useSearchParams() lança um erro durante a pré-renderização estática, então o componente que o lê deve estar dentro de um limite <Suspense> ou a compilação falhará.
22. Prefira router.replace para Atualizações de Filtro: Filtros, ordenação e digitação de pesquisa criam entradas de histórico barulhentas com router.push; use router.replace para que o botão voltar retorne a uma página anterior significativa e também redefina page=1 sempre que a consulta mudar.
23. Aguarde cookies() e headers(): Ambos são assíncronos no Next.js 15+ - const token = (await cookies()).get("session")?.value - e tocar em qualquer um deles torna a rota dinâmica; leia-os em um pequeno componente folha sob <Suspense> quando quiser que o restante da rota permaneça estático.
24. Defina Cookies Apenas em Actions ou Middleware: cookies() é somente leitura em Server Components, então as escritas devem ocorrer em uma Server Action, Route Handler ou Middleware - (await cookies()).set("session", token, { httpOnly: true, secure: true, sameSite: "lax" }).
25. Transmita Grandes Conjuntos de Dados Com Geradores Assíncronos: Para APIs paginadas, exportações CSV ou endpoints SSE, use async function* mais for await...of para manter apenas um lote em memória, compor com helpers de map/filter/take e lembre-se que geradores são apenas para servidor e de uso único.