Guia rápido do Next.js 16: 75 padrões do App Router para produção

Criar um projeto App Router

create-next-app configura Next.js, React, TypeScript e as ferramentas escolhidas. Registre package-lock.json junto do projeto.

npx create-next-app@latest my-app --ts --app --src-dir

Usar a versão mínima atual do Node.js

Next.js 16 exige Node.js 20.9 ou posterior. Fixe uma versão compatível no desenvolvimento local e na CI para que as compilações não dependam do padrão variável do runner.

Conheça os quatro scripts normais

next dev inicia o desenvolvimento, next build gera a saída de produção, next start serve essa saída e o linter configurado executa separadamente.

"scripts": {
  "dev": "next dev",
  "build": "next build",
  "start": "next start",
  "lint": "eslint ."
}

Instalar de forma reproduzível na CI

Use npm ci quando package-lock.json estiver no repositório. Ele rejeita divergências no arquivo de lock e instala a árvore resolvida de dependências sem reescrevê-lo.

npm ci && npm run build

Usar Turbopack por padrão

No Next.js 16, next dev e next build usam Turbopack por padrão. Remova opções --turbo antigas, a menos que o script precise dar suporte a outra versão.

Manter temporariamente uma compilação webpack

Um projeto com configuração webpack personalizada pode optar explicitamente por não usar o padrão enquanto migra essa configuração. Teste a saída e o desempenho antes de trocar a ferramenta de compilação de produção.

next build --webpack

Manter o código da aplicação em src

src/app e src/lib separam o código da aplicação da configuração raiz. O diretório public e arquivos como next.config.ts permanecem na raiz do projeto.

Usar um alias de importação

Um alias estável evita caminhos relativos longos quando o código muda de pasta de rota. Mantenha-o em tsconfig.json ou jsconfig.json.

import { getUser } from "@/lib/data";

Criar uma página

page.tsx torna a rota da pasta publicamente acessível. A exportação padrão define a interface daquela URL.

export default function Page() {
  return <h1>About</h1>;
}

Criar o layout raiz obrigatório

app/layout.tsx envolve todas as rotas e deve renderizar html e body. Coloque ali CSS global, idioma, providers globais e metadados padrão.

Aninhar layouts por segmento de rota

Um layout em app/dashboard envolve a página do painel e seus descendentes. Layouts persistem durante a navegação cliente dentro de sua subárvore.

Agrupar rotas sem alterar a URL

Parênteses criam um grupo de rotas. app/(marketing)/pricing/page.tsx continua resolvendo para /pricing.

app/(marketing)/pricing/page.tsx

Criar um segmento dinâmico

Colchetes capturam um segmento de URL. No Next.js 16, aguarde params antes de ler o valor.

export default async function Page({ params }) {
  const { slug } = await params;
  return <h1>{slug}</h1>;
}

Capturar vários segmentos

[...parts] é um catch-all obrigatório e [[...parts]] é opcional. Use-os para documentação hierárquica ou outros caminhos cuja profundidade depende dos dados.

Pré-gerar caminhos dinâmicos conhecidos

generateStaticParams retorna objetos de parâmetros para as rotas que Next.js deve gerar na compilação.

export function generateStaticParams() {
  return posts.map((post) => ({ slug: post.slug }));
}

Rejeitar caminhos dinâmicos desconhecidos

Defina dynamicParams como false quando somente os valores retornados por generateStaticParams devem ser resolvidos. Os demais valores retornam 404.

export const dynamicParams = false;

Renderizar um recurso ausente

Chame notFound quando a rota existe, mas a entidade solicitada não. Next.js renderiza o limite not-found.tsx mais próximo.

if (!post) notFound();

Redefinir o estado com um template

template.tsx parece um layout, mas é remontado na navegação. Use-o para reiniciar estado e efeitos; mantenha estruturas persistentes nos layouts.

Renderizar slots de rotas simultâneos

Pastas como @team e @analytics definem slots de rotas paralelas passados ao layout pai. Forneça conteúdo de fallback em default.tsx para slots sem correspondência em uma navegação completa.

Abrir uma rota como modal

Rotas de interceptação podem mostrar outra rota dentro do layout atual na navegação interna, preservando a página completa para atualizações e links compartilhados.

Manter as páginas no servidor por padrão

Um Server Component pode aguardar dados, usar variáveis de ambiente privadas e renderizar sem enviar seu código ao navegador.

Declarar um Client Component

Coloque a diretiva antes dos imports. O limite do cliente inclui o módulo e o grafo de dependências cliente que ele importa.

"use client";

import { useState } from "react";

Usar componentes cliente para interação

Estado, efeitos, handlers de eventos, hooks personalizados, window, localStorage e outras APIs do navegador pertencem a Client Components.

Usar servidores para trabalho privado

Consultas ao banco, credenciais de serviços, bibliotecas grandes exclusivas do servidor e a maior parte da renderização de conteúdo pertencem a Server Components ou módulos server-only.

Passar props serializáveis aos clientes

Strings, números, booleanos, arrays, objetos simples e valores React compatíveis podem atravessar o limite. Restrinja os dados e não envie registros privados completos.

Marcar módulos privados com server-only

O import por efeito colateral faz um import cliente falhar na compilação, protegendo o código de acesso a dados do uso acidental no navegador.

import "server-only";

Descer o limite do cliente na árvore

Mantenha página e layout renderizados no servidor e isole uma busca, menu, seletor ou gráfico no menor Client Component viável.

Passar a interface servidor pelos children do cliente

Um Client Component pode receber um Server Component como filho ou outra prop. Isso mantém a subárvore renderizada no servidor fora do grafo de módulos do cliente.

Posicionar os providers o mais fundo possível na árvore

Context não está disponível em Server Components. Renderize um provider específico em um Client Component apenas ao redor da subárvore que o usa, sem envolver todo o documento por padrão.

Buscar dados em um Server Component assíncrono

Chame uma API, ORM ou banco de dados no componente que renderiza o resultado. Não é preciso um Route Handler interno apenas para chamar seu próprio servidor.

export default async function Page() {
  const products = await getProducts();
  return <ProductList products={products} />;
}

Iniciar operações independentes juntas

Promise.all evita uma sequência desnecessária de requisições quando nenhuma operação depende do resultado da outra.

const [user, projects] = await Promise.all([
  getUser(),
  getProjects(),
]);

Transmitir com um arquivo de carregamento de rota

loading.tsx envolve o segmento em um limite Suspense e mostra uma interface provisória imediata durante a navegação e a renderização a cada requisição.

Transmitir uma região lenta por streaming

Coloque Suspense ao redor do componente lento para o restante da página renderizar primeiro. Faça o conteúdo provisório ocupar dimensões semelhantes às finais.

<Suspense fallback={<ActivitySkeleton />}>
  <RecentActivity />
</Suspense>

Memoizar uma renderização

React cache deduplica a mesma função de dados servidor com os mesmos argumentos durante uma renderização. Não é um cache persistente de dados da aplicação.

import { cache } from "react";

export const getUser = cache(async (id) => db.user.findUnique({ where: { id } }));

Habilitar Cache Components

As APIs use cache do Next.js 16 exigem a configuração cacheComponents. Planeje a migração porque ela muda o comportamento de renderização e cache.

const nextConfig = { cacheComponents: true };
export default nextConfig;

Armazenar uma função assíncrona em cache

Com Cache Components habilitado, coloque use cache no início de uma função assíncrona ou do corpo do componente. Argumentos serializáveis passam a fazer parte da chave de cache.

export async function getProducts() {
  "use cache";
  return db.product.findMany();
}

Definir a duração do cache

cacheLife aceita um perfil nomeado ou tempos personalizados. Escolha a duração conforme o tempo em que o conteúdo pode ficar desatualizado, não por conveniência.

"use cache";
cacheLife("hours");

Associar tags a operações relacionadas em cache

cacheTag associa várias entradas a um rótulo compartilhado de invalidação, como products ou post-42.

"use cache";
cacheTag("products");

Expirar um caminho

Chame revalidatePath em uma Server Function ou Route Handler quando uma alteração deixar uma página ou layout desatualizado.

revalidatePath("/blog");

Revalidar por tag

Use revalidateTag quando o conteúdo associado a tags puder usar stale-while-revalidate. Escolha o perfil de cache conforme o requisito de atualidade dos dados.

Ver a própria gravação com updateTag

Chame updateTag em uma Server Action quando o usuário da ação precisar ver imediatamente os dados atualizados associados à tag após a alteração.

await savePost(input);
updateTag("posts");

Declarar uma Server Action

Coloque use server no início de uma função assíncrona ou módulo de ações. Server Actions exportadas devem ser tratadas como endpoints de alteração que podem ser chamados remotamente.

"use server";

export async function createPost(formData: FormData) {
  // validate, authorize, mutate, invalidate
}

Associar uma ação a um formulário

Um formulário pode chamar uma Server Action sem um handler personalizado de envio no cliente. O comportamento nativo do formulário também permite aprimoramento progressivo.

<form action={createPost}>...</form>

Validar FormData no servidor

Trate nomes, IDs, arquivos, campos ocultos e validação cliente como não confiáveis. Valide-os com um esquema explícito antes de gravar.

Retornar erros esperados de formulário

Use um resultado serializável e useActionState para erros de validação ou negócio que o usuário possa corrigir. Não lance exceções para todo resultado esperado.

Mostrar que o envio do formulário está pendente

useFormStatus lê o estado de envio do formulário pai. Desabilite envios repetidos e mostre no botão um rótulo que indique a pendência real.

Criar um Route Handler

route.ts exporta funções de verbos HTTP e usa as APIs Web Request e Response. Não pode compartilhar o mesmo segmento com page.tsx.

export async function GET() {
  return Response.json({ status: "ok" });
}

Leia um parâmetro dinâmico de Route Handler

Os params do contexto da rota são assíncronos no Next.js atual. Aguarde-os antes de consultar o recurso.

export async function GET(request, { params }) {
  const { id } = await params;
  return Response.json(await getItem(id));
}

Redirecionar após uma alteração

Use redirect para navegação temporária após criar ou atualizar com sucesso, e permanentRedirect somente quando o recurso tiver uma nova URL canônica duradoura.

redirect("/dashboard");

Manter as tentativas seguras

Webhooks e requisições podem chegar mais de uma vez. Armazene IDs de eventos dos provedores ou chaves de idempotência antes de repetir pagamentos, e-mails ou outros efeitos colaterais.

Usar Link para navegação interna

next/link permite transições cliente e pode pré-carregar rotas quando entram na área visível. Use links nativos para downloads e para links cujo comportamento você não quer que Next.js gerencie.

<Link href="/pricing">Pricing</Link>

Navegar após um evento

Em um Client Component, use useRouter de next/navigation para executar imperativamente push, replace, refresh, back ou forward.

const router = useRouter();
router.push("/dashboard");

Ler o caminho atual

usePathname é um hook de Client Component. Use-o para marcar a navegação ativa, não para substituir parâmetros de rota do servidor.

Ler parâmetros de consulta

Uma página recebe searchParams no servidor. Controles interativos no cliente podem usar useSearchParams e atualizar a URL pelo roteador.

Capturar erros de rota não tratados

error.tsx é um limite de erro Client Component da subárvore de rotas. Registre o erro e ofereça uma nova tentativa útil ou uma navegação segura.

Lidar com falhas na raiz

global-error.tsx captura erros no layout raiz e deve renderizar seus próprios html e body porque a estrutura raiz normal falhou.

Distinguir dados vazios, recursos ausentes e falhas

Uma lista vazia é dado válido; uma entidade ausente é 404; uma entrada rejeitada de forma esperada é um resultado normal; e uma exceção não tratada pertence a um limite de erro.

Definir metadados estáticos

Exporte metadados de uma página ou layout Server Component quando os valores não dependerem dos dados da rota.

export const metadata = {
  title: "Pricing",
  description: "Simple plans for growing teams.",
};

Gerar metadados dinâmicos

Use generateMetadata para títulos, descrições, URLs canônicas e imagens sociais específicos de cada entidade. Reutilize a função de acesso a dados da rota quando possível.

Definir metadataBase uma vez

metadataBase no layout raiz permite caminhos relativos em links canônicos e campos de imagem, enquanto Next.js resolve as URLs absolutas.

metadataBase: new URL("https://example.com")

Gerar um sitemap

app/sitemap.ts retorna URLs públicas e os campos opcionais lastModified, changeFrequency e priority. Gere-o a partir do catálogo real; o Google ignora changeFrequency e priority, então mantenha lastModified correto em vez de inventar atualizações.

Publicar regras de robôs

app/robots.ts retorna regras de exploração e a localização do sitemap. As regras robots orientam robôs de busca; não controlam o acesso a rotas privadas.

Usar imagens otimizadas

next/image exige dimensões intrínsecas ou um contêiner fill. Forneça alt preciso e sizes responsivos; use priority apenas em imagens realmente críticas na área inicialmente visível.

Carregar fontes com next/font

next/font hospeda os arquivos de fontes selecionados e reduz requisições externas. Limite pesos e subconjuntos aos estilos realmente usados na interface.

Agendar scripts de terceiros

next/script controla quando JavaScript externo é carregado. Escolha afterInteractive ou lazyOnload, a menos que a integração realmente faça parte do caminho crítico.

Manter os segredos no servidor

Os valores de ambiente são exclusivos do servidor, a menos que o nome comece com NEXT_PUBLIC_. Valores com esse prefixo são visíveis ao navegador e ficam fixados conforme o ambiente de compilação.

Autorizar cada ponto de entrada do servidor

Verifique a identidade atual e sua permissão nas Server Actions, nos Route Handlers e no acesso protegido aos dados. Um botão oculto ou redirecionamento Proxy não é uma barreira de segurança.

Usar Proxy para lógica de roteamento ligada à requisição

Next.js 16 usa proxy.ts para reescritas, redirecionamentos e verificações otimistas antes de a requisição chegar à rota. Mantenha também a autorização segura perto dos dados.

Usar cookies de sessão seguros

Defina os atributos HTTP-only, secure, same-site, path e expiry conforme o desenho da sessão. Rotacione e invalide sessões pelo sistema de autenticação.

Enviar dados restritos ao navegador

Converta registros em DTOs com apenas os campos necessários à interface. APIs de taint acrescentam defesa em profundidade, mas não substituem uma definição cuidadosa da saída.

Executar verificações separadamente

Next.js 16 não usa next build para executar lint. Separe lint, TypeScript, testes e compilação de produção em etapas da CI.

npm run lint
npx tsc --noEmit
npm test
npm run build

Testar o servidor de produção

Execute next build e next start localmente ou em uma prévia. O comportamento de desenvolvimento pode esconder problemas de imports, cache, ambiente e renderização exclusivos de produção.

Leia o resumo de compilação da rota

A saída de next build identifica rotas pré-renderizadas e renderizadas a cada requisição. Investigue uma rota que fique dinâmica ou cresça inesperadamente, em vez de tratar a compilação apenas como aprovada ou reprovada.

Expor uma rota de saúde fiel ao estado real

Retorne uma resposta curta de sucesso somente quando o processo estiver pronto para receber tráfego. Não inclua segredos nem detalhes das dependências no corpo público.

export function GET() {
  return Response.json({ status: "ok" });
}

Implantar o processo de produção normal

Uma implantação padrão instala as dependências pelo arquivo de lock, executa next build, inicia com next start, injeta segredos de execução, verifica a saúde e promove apenas uma versão saudável.

build_cmd: npm ci && npm run build
start_cmd: npm start

runtime:
  name: node@24
  port: 3000
  health_path: /api/health