Aplicações Next.js 16
Construa aplicações Next.js 16 corretamente com design diferenciado.
Mudanças Significativas Críticas (Next.js 16)
1. params e searchParams Agora São Promises
ESTE É O ERRO MAIS COMUM.
// ERRADO - Padrão Next.js 15 (IRÁ FALHAR)
export default function Page({ params }: { params: { id: string } }) {
return <div>ID: {params.id}</div>
}
// CORRETO - Padrão Next.js 16
export default async function Page({
params,
}: {
params: Promise<{ id: string }>
}) {
const { id } = await params
return <div>ID: {id}</div>
}
2. Componentes Cliente Precisam do Hook use()
"use client"
import { use } from "react"
export default function ClientPage({
params,
}: {
params: Promise<{ id: string }>
}) {
const { id } = use(params)
return <div>ID: {id}</div>
}
3. searchParams Também Assíncrono
export default async function Page({
searchParams,
}: {
searchParams: Promise<{ page?: string }>
}) {
const { page } = await searchParams
return <div>Página: {page ?? "1"}</div>
}
Padrões Principais
Configuração do Projeto
npx create-next-app@latest my-app --typescript --tailwind --eslint
cd my-app
# Adicionar shadcn/ui
npx shadcn@latest init
npx shadcn@latest add button form dialog table sidebar
Layout do App Router
// app/layout.tsx
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="pt">
<body className="min-h-screen">
{children}
</body>
</html>
)
}
Rotas Dinâmicas
// app/tasks/[id]/page.tsx
export default async function TaskPage({
params,
}: {
params: Promise<{ id: string }>
}) {
const { id } = await params
const task = await getTask(id)
return (
<main>
<h1>{task.title}</h1>
</main>
)
}
Ações do Servidor
// app/actions.ts
"use server"
import { revalidatePath } from "next/cache"
export async function createTask(formData: FormData) {
const title = formData.get("title") as string
await db.insert(tasks).values({ title })
revalidatePath("/tasks")
}
// Uso no componente
<form action={createTask}>
<input name="title" />
<button type="submit">Criar</button>
</form>
Rotas de API
// app/api/tasks/route.ts
import { NextResponse } from "next/server"
export async function GET() {
const tasks = await db.select().from(tasksTable)
return NextResponse.json(tasks)
}
export async function POST(request: Request) {
const body = await request.json()
const task = await db.insert(tasksTable).values(body).returning()
return NextResponse.json(task, { status: 201 })
}
Middleware → proxy.ts
// proxy.ts (substitui middleware.ts no Next.js 16)
import { NextRequest } from "next/server"
export function proxy(request: NextRequest) {
// Verificação de autenticação
const token = request.cookies.get("token")
if (!token && request.nextUrl.pathname.startsWith("/dashboard")) {
return Response.redirect(new URL("/login", request.url))
}
}
export const config = {
matcher: ["/dashboard/:path*"],
}
Busca de Dados
Componente Servidor (Padrão)
// Isso é executado no servidor - pode usar async/await diretamente
async function TaskList() {
const tasks = await fetch("https://api.example.com/tasks", {
cache: "no-store", // SSR, ou
// next: { revalidate: 60 } // ISR
}).then(r => r.json())
return (
<ul>
{tasks.map(task => <li key={task.id}>{task.title}</li>)}
</ul>
)
}
Componente Cliente
"use client"
import useSWR from "swr"
const fetcher = (url: string) => fetch(url).then(r => r.json())
export function ClientTaskList() {
const { data, error, isLoading } = useSWR("/api/tasks", fetcher)
if (isLoading) return <div>Carregando...</div>
if (error) return <div>Erro ao carregar tarefas</div>
return (
<ul>
{data.map(task => <li key={task.id}>{task.title}</li>)}
</ul>
)
}
Estrutura do Projeto
app/
├── layout.tsx # Layout raiz
├── page.tsx # Página inicial
├── globals.css # Estilos globais
├── api/ # Rotas de API
│ └── tasks/route.ts
├── tasks/
│ ├── page.tsx # /tasks
│ └── [id]/page.tsx # /tasks/:id
├── actions.ts # Ações do servidor
└── proxy.ts # Proxy de requisição (middleware)
components/
├── ui/ # Componentes shadcn/ui
└── task-list.tsx # Componentes da aplicação
lib/
├── db.ts # Conexão com banco de dados
└── utils.ts # Utilitários
Next.js DevTools MCP
Use o servidor next-devtools-mcp para diagnósticos em tempo de execução e automação de desenvolvimento.
Configuração
claude mcp add next-devtools npx next-devtools-mcp@latest
Ou em settings.json:
{
"mcpServers": {
"next-devtools": {
"type": "stdio",
"command": "npx",
"args": ["next-devtools-mcp@latest"]
}
}
}
Ferramentas Disponíveis
| Ferramenta | Propósito |
|---|---|
init | Estabelecer contexto com ferramentas e melhores práticas disponíveis |
nextjs_docs | Pesquisar e buscar documentação oficial do Next.js |
browser_eval | Automatizar testes de navegador com Playwright |
nextjs_index | Descobrir servidores de desenvolvimento Next.js em execução |
nextjs_call | Executar ferramentas MCP em servidores de desenvolvimento em execução |
upgrade_nextjs_16 | Atualização automatizada com codemods |
enable_cache_components | Configurar Cache Components para Next.js 16 |
Principais Casos de Uso
1. Obter Erros em Tempo Real
"Quais erros de build existem na minha aplicação Next.js?"
"Mostre-me erros TypeScript no projeto atual"
2. Depurar Problemas em Tempo de Execução
"Verifique os logs do servidor de desenvolvimento em busca de erros"
"Quais erros de runtime estão ocorrendo na página do dashboard?"
3. Auxílio para Atualização
"Atualize este projeto para Next.js 16"
"Ative os cache components para esta aplicação"
4. Consulta de Documentação
"Como usar o componente Image no Next.js 16?"
"Qual a maneira correta de lidar com rotas dinâmicas?"
Endpoint MCP do Next.js 16
O Next.js 16+ expõe um endpoint MCP embutido em http://localhost:3000/_next/mcp (ou na porta do seu servidor de desenvolvimento). O devtools MCP descobre e conecta-se automaticamente aos servidores em execução.
Verificação
Execute: python3 scripts/verify.py
Esperado: ✓ building-nextjs-apps skill ready
Se a Verificação Falhar
- Verifique: a pasta references/ contém nextjs-16-patterns.md
- Pare e relate se ainda estiver falhando
Habilidades Relacionadas
- styling-with-shadcn - Componentes de UI para aplicações Next.js
- fetching-library-docs - Documentação mais recente do Next.js:
--library-id /vercel/next.js --topic routing - configuring-better-auth - OAuth/SSO para aplicações Next.js
Referências
- references/nextjs-16-patterns.md - Padrões completos do Next.js 16
- references/frontend-design.md - Diretrizes estéticas para UI diferenciada
- references/datetime-patterns.md - Manipulação de UTC/fuso horário para inputs datetime-local