Construir Uma App Next.js Com o Claude Code

Problema: configurar o Next.js 16 do zero leva mesmo o seu tempo. O App Router muda de forma incompatível a cada versão maior, os params assíncronos tramam-te logo no primeiro dia, e os dados de treino do Claude ficam desatualizados mais depressa do que a framework lança versões. Acabas a corrigir o Claude mais do que ele te ajuda.

Ganho Rápido: arranca o Claude Code a partir de um projeto create-next-app acabado de criar e deixa o AGENTS.md fazer o briefing. O Claude lê os docs do Next.js 16 que vêm incluídos antes de tocar num único ficheiro:

npx create-next-app@latest my-app --typescript --tailwind --app --turbopack
cd my-app
claude

Antes de Começar

Precisas de ter três coisas no sítio.

Node.js 20.9.0 ou mais recente. O Next.js 16 deixou cair o suporte ao Node 18. Verifica a tua versão:

node --version

Claude Code instalado globalmente:

npm install -g @anthropic-ai/claude-code

Uma subscrição Claude Pro ou Team. O Claude Code usa a tua conta Anthropic. O escalão gratuito não serve.

TypeScript 5.1+. O Next.js 16 exige-o. Correr create-next-app@latest com --typescript instala-te a versão certa.

O Git e um repo no GitHub fazem do deploy na Vercel um único passo. Não é estritamente obrigatório, mas a secção do deploy assume que tens os dois.

Criar o Projeto

O create-next-app@latest faz o scaffold de um projeto Next.js 16 com o Turbopack, o TypeScript e o Tailwind CSS v4 já ligados. O Turbopack é agora o bundler por omissão, em substituição do Webpack. O Fast Refresh corre até 10x mais depressa do que a configuração anterior, e os builds a frio são 2-5x mais rápidos.

Corre o scaffold:

npx create-next-app@latest my-app --typescript --tailwind --app --turbopack
cd my-app

Dois ficheiros na raiz do projeto interessam ao Claude Code: o AGENTS.md e o CLAUDE.md. A versão canary gera os dois automaticamente. Na versão estável, talvez tenhas de os criar à mão.

Se faltarem, cria o AGENTS.md na raiz do projeto com uma linha para carregar os docs incluídos:

node_modules/next/dist/docs/

Depois cria o CLAUDE.md que o importa. A secção seguinte cobre o que acrescentar para lá disso.

Porque é que o AGENTS.md importa: aponta o Claude para a documentação incluída em node_modules/next/dist/docs/. O Claude lê esses docs no início da sessão em vez de depender dos dados de treino. Em benchmarks de Next.js, os agentes com os docs incluídos atingem 100% nos evals de Next.js. Os agentes sem eles falham as mudanças de API incompatíveis introduzidas no Next.js 16.

O CLAUDE.md usa a sintaxe de import @AGENTS.md para puxar essas regras sem as copiar:

@AGENTS.md

O Claude lê os dois ficheiros antes de escrever qualquer código.

Personalizar o CLAUDE.md

O CLAUDE.md gerado automaticamente cobre as convenções do Next.js. Acrescenta-lhe por cima a stack do teu projeto:

@AGENTS.md

## Stack

- Next.js 16 with App Router (TypeScript)
- Tailwind CSS v4 with shadcn/ui components
- PostgreSQL via Supabase (use server-side client for Server Components)
- oRPC with Zod for type-safe API routes

## File Conventions

- Server Components by default. Add "use client" only when you need browser APIs or interactivity.
- Route handlers go in app/api/[route]/route.ts
- Database queries run in lib/db.ts, never inline in components

## Commands

- Dev server: npm run dev
- Type check: npx tsc --noEmit
- Build: npm run build

## Proxy

- Middleware logic lives in proxy.ts, not middleware.ts (Next.js 16)

A nota sobre o proxy.ts vale a pena acrescentar explicitamente. O Claude ainda recorre ao middleware.ts por omissão. Uma linha no CLAUDE.md evita esse erro todas as vezes.

Mantém o CLAUDE.md específico. Instruções vagas ("escreve código limpo") não mudam o comportamento do Claude. Caminhos de ficheiro concretos, comandos e convenções de nomes, sim.

Compreender o App Router Com o Claude Code

O App Router separa os componentes em duas categorias. Os Server Components correm no servidor e podem ir buscar dados diretamente. Os Client Components correm no browser e tratam da interatividade.

O Claude lê as regras do App Router a partir do AGENTS.md e acerta na fronteira sem que lhe tenhas de explicar. O padrão é Server Component. Só adicionas "use client" no topo de um ficheiro quando precisas de useState, useEffect, APIs do browser ou handlers de eventos.

O Next.js 16 vem com o React 19.2. Isso inclui as View Transitions, o useEffectEvent e o componente <Activity />. São suficientemente recentes para que os dados de treino do Claude possam não os cobrir bem. Para tudo o que use APIs do React 19, acrescenta exemplos explícitos ao CLAUDE.md ou descreve o que queres em termos de comportamento em vez de nomes de API.

Pede ao Claude para construir uma página de dashboard e ele coloca o fetch dos dados no Server Component e passa os resultados como props para qualquer parte interativa:

claude "build a /dashboard page that fetches user stats from the database and shows them in a summary card with a refresh button"

O Claude gera o Server Component no topo da árvore, cria um Client Component para o botão de refresh e liga-os. Não especificas qual é qual. O Claude lê as regras do AGENTS.md e percebe.

Construir Uma Funcionalidade de Ponta a Ponta

Aqui vai um percurso concreto: uma página de perfil de utilizador com dados do lado do servidor e um formulário de edição do lado do cliente.

Começa em Plan mode antes de se escrever qualquer código:

claude --plan "add a /profile page with server-fetched user data and an editable display name form"

O Claude mapeia os ficheiros de que precisa: um componente de página, uma Server Action para a submissão do formulário, um helper de query à base de dados e um Client Component para o formulário. Revês o plano. Depois ele constrói.

O ficheiro da página usa params assíncronos, como exigido no Next.js 16:

// app/profile/[id]/page.tsx
import { ProfileForm } from "@/components/profile-form";
import { getUser } from "@/lib/db";

interface PageProps {
  params: Promise<{ id: string }>;
}

export default async function ProfilePage({ params }: PageProps) {
  const { id } = await params;
  const user = await getUser(id);

  return (
    <main className="max-w-lg mx-auto py-12">
      <h1 className="text-2xl font-bold mb-6">Your Profile</h1>
      <ProfileForm user={user} />
    </main>
  );
}

O objeto params é uma Promise no Next.js 16. O await params é obrigatório. O Claude trata disto corretamente quando o AGENTS.md está no sítio. Sem ele, o Claude escreve o velho padrão síncrono e o build falha com um erro de tipo.

A Server Action do formulário vive num ficheiro separado:

// app/profile/actions.ts
"use server";

import { updateUser } from "@/lib/db";

export async function updateDisplayName(userId: string, name: string) {
  await updateUser(userId, { displayName: name });
}

Armadilhas do Next.js 16 Que o Claude Trata

Algumas mudanças incompatíveis vindas do Next.js 14/15 tramam o Claude sem o AGENTS.md. Com ele, funcionam corretamente.

Cache Components e a diretiva "use cache". O Next.js 16 substitui o experimental.dynamicIO pela diretiva "use cache". Adiciona-a no topo de qualquer componente ou função que queiras em cache:

// app/stats/page.tsx
"use cache";

import { getStats } from "@/lib/db";

export default async function StatsPage() {
  const stats = await getStats();
  return <pre>{JSON.stringify(stats, null, 2)}</pre>;
}

O Claude gera a diretiva corretamente para ficheiros novos. Para código migrado do Next.js 15, diz ao Claude explicitamente: "migrate this file from experimental.dynamicIO to the use cache directive."

Turbopack por omissão. O npm run dev usa o Turbopack. A config de Webpack em next.config.ts é, na maioria dos casos, irrelevante, a não ser que tenhas loaders personalizados. O Claude sabe disto a partir do AGENTS.md e não vai gerar config específica de Webpack.

O MCP do Next.js DevTools

O Next.js 16 traz um servidor Model Context Protocol para debugging assistido por IA. Dá ao Claude contexto de routing, logs unificados de browser e servidor, e acesso automático aos stack traces de erro dentro da sessão.

Liga-o nas tuas definições do Claude Code apontando para o servidor MCP incluído:

{
  "mcpServers": {
    "nextjs-devtools": {
      "command": "node",
      "args": ["node_modules/next/dist/mcp/index.js"]
    }
  }
}

Com o MCP do DevTools ativo, o Claude consegue diagnosticar um problema de cache sem que lhe estejas a copiar e colar logs. Pergunta ao Claude porque é que uma rota está a servir dados desatualizados, e ele lê os logs do servidor diretamente, segue a chave de cache e diz-te qual a chamada revalidateTag() a adicionar.

Sem isto, o Claude diagnostica só a partir do código. Com isto, o Claude diagnostica a partir de dados de runtime ao vivo. Essa diferença pesa mais quando um bug só aparece em produção.

O MCP do DevTools dá também ao Claude acesso à árvore de routing em runtime. Se pedires ao Claude para adicionar uma rota nova e ela colidir com um segmento dinâmico existente, o MCP mostra isso de imediato em vez de te deixar descobri-lo em runtime. Para setups complexos de App Router, com layouts aninhados, rotas paralelas e rotas de interceção, vale a pena ter esse contexto em todas as sessões.

Quality Gates Antes de Lançar

Dois comandos correm antes de cada commit.

Verificação de tipos com zero erros:

npx tsc --noEmit

Build de produção limpo com o Turbopack:

npm run build

Pede ao Claude para correr ambos depois de qualquer mudança significativa:

claude "run tsc --noEmit and fix any type errors, then confirm the build passes"

O Claude lê o output de erro, corrige os problemas e volta a correr a verificação. É aqui que os erros de params assíncronos, as diretivas "use cache" em falta e as Server Actions mal configuradas aparecem antes de chegarem à produção.

Zero erros de tipo e um build limpo são o mínimo para lançar. Não é uma sugestão. A verificação corre todas as vezes.

Deploy na Vercel

A Vercel deteta o Next.js 16 automaticamente. Duas opções de deploy.

Integração com Git: dá push para a tua branch main e a Vercel faz o build. Define as variáveis de ambiente no dashboard da Vercel, em Settings > Environment Variables, antes do primeiro deploy. A Vercel lê o output do build e infere que rotas são estáticas, dinâmicas ou cacheadas.

Deploy por CLI: define primeiro as tuas variáveis de ambiente e depois dá push:

npx vercel env add DATABASE_URL production
npx vercel env add NEXT_PUBLIC_SUPABASE_URL production
npx vercel --prod

Os logs de build no Next.js 16 mostram a estratégia de render de cada rota juntamente com o tamanho do output. As rotas estáticas aparecem a verde, as dinâmicas a amarelo. Isto diz-te exatamente o que é pré-renderizado no momento do build e o que corre a cada pedido.

Se uma rota que esperavas estática aparecer como dinâmica, o MCP do DevTools ajuda a diagnosticar porquê. Muitas vezes é um fetch de dados sem cache que força a rota a correr no momento do pedido.

Como É Uma Pipeline Orquestrada

Uma única sessão do Claude Code lida bem com funcionalidades. Uma pipeline coordenada lida com produtos.

O Build This Now corre 32 agentes especialistas em planeamento, construção, avaliação e testes antes de uma funcionalidade ser lançada. Três agentes de planeamento trabalham em paralelo antes de se escrever qualquer código. Depois do build, avaliadores adversariais revêem o output e os builders corrigem o que eles assinalam. Dois agentes de teste correm em paralelo, um deles com um browser real. Cada funcionalidade sai da pipeline com zero erros de tipo, zero erros de lint e um build Turbopack limpo.

A verificação npx tsc --noEmit no fim deste guia é esse último gate. Numa pipeline orquestrada, corre automaticamente após cada passagem de testemunho entre agentes.

Configura o AGENTS.md, escreve um CLAUDE.md específico, usa o Plan mode antes de funcionalidades complexas e corre os quality gates antes de cada commit. Esses quatro hábitos cobrem a maior parte do que torna fiável um workflow de Claude Code com Next.js 16. A framework muda. O processo não.