Especialista em Next.js 15 + App Router
Referência completa do Next.js 15 para desenvolvimento Quetrex.
Este skill fornece orientação abrangente sobre todos os padrões do App Router do Next.js 15, garantindo que os agentes implementem o Next.js moderno corretamente na primeira tentativa.
REGRAS CRÍTICAS (NUNCA VIOLAR)
Estas regras são INEGOCIÁVEIS. Violações quebrarão as builds.
1. SEMPRE use <Image> de next/image - NUNCA use <img>
// ✅ SEMPRE FAÇA ISSO
import Image from 'next/image'
<Image src="/logo.png" alt="Logo" width={200} height={100} />
<Image src={user.avatar} alt={user.name} width={40} height={40} />
// ❌ NUNCA FAÇA ISSO - A BUILD FALHARÁ
<img src="/logo.png" alt="Logo" />
<img src={user.avatar} alt={user.name} />
Por quê: O componente Image do Next.js fornece otimização automática, lazy loading e evita mudanças de layout. O ESLint está configurado para falhar nas builds ao usar <img>.
2. Server Components são PADRÃO - adicione 'use client' apenas quando necessário
3. Nunca crie Client Components assíncronos
4. Sempre especifique a estratégia de cache para fetch()
Quando Usar Este Skill
Use este skill ao trabalhar com:
- Criar novas rotas ou páginas
- Implementar busca de dados (Server Components vs Client Components)
- Decisões entre Server e Client Components
- Server Actions e manipulação de formulários
- Streaming e Suspense
- Metadados e SEO
- Manipuladores de rota (API routes)
- Estratégias de cache
- Otimização de desempenho
Documentação Completa
Este skill inclui guias abrangentes cobrindo todos os padrões do Next.js 15:
📁 Guia Completo do App Router
Mais de 45 exemplos cobrindo:
- Roteamento baseado em arquivos (page.tsx, layout.tsx, route.ts)
- Rotas dinâmicas ([id], [...slug], [[...slug]])
- Grupos de rotas ((group))
- Pastas privadas (_folder)
- Manipuladores de rota (API routes)
- Layouts e templates
- UI de carregamento (loading.tsx)
- Limites de erro (error.tsx, global-error.tsx)
- Páginas não encontradas (not-found.tsx)
- Rotas paralelas (@folder)
- Rotas de interceptação ((.)folder)
- Configuração de segmento de rota (dynamic, revalidate, runtime)
🔄 Guia Completo de Busca de Dados
Mais de 35 exemplos cobrindo:
- Busca de dados em Server Component (async/await)
- Busca de dados em Client Component (useEffect, React Query, SWR)
- Busca paralela de dados (Promise.all)
- Busca sequencial de dados (prevenção de waterfall)
- Streaming de dados (limites de Suspense)
- Server-Sent Events (SSE para voz Quetrex)
- Mutações de dados (Server Actions)
- Atualizações otimistas (useOptimistic)
- Manipulação de formulários (useFormStatus, useActionState)
- Desduplicação de requisições
- Pré-carregamento de dados
💾 Guia de Estratégias de Cache
Mais de 35 exemplos cobrindo:
- Memorização de requisições (desduplicação automática)
- Cache de Dados (comportamento do cache fetch)
- Cache de Rota Completa (estático vs dinâmico)
- Cache do Roteador (cache do lado do cliente)
- Configuração de cache (force-cache, no-store, revalidate)
- Tags de cache (revalidateTag, revalidatePath)
- Revalidação sob demanda
- Revalidação baseada em tempo (ISR)
- Técnicas de depuração de cache
- Optar por não usar cache
⚡ Guia Completo de Server Actions
Mais de 31 exemplos cobrindo:
- Padrões básicos de Server Actions
- Ações de formulário (melhoria progressiva)
- Ações de botão (chamadas programáticas)
- Hook useFormStatus (estados de carregamento)
- Hook useActionState (gerenciamento de estado)
- Hook useOptimistic (UI otimista)
- Tratamento de erros em ações
- Validação com Zod
- Retornar JSON vs redirecionar
- Segurança (autenticação, CSRF)
- Limitação de taxa
- Transações de banco de dados
🎯 Guia da API de Metadados
Mais de 26 exemplos cobrindo:
- Metadados estáticos (objeto exportado)
- Metadados dinâmicos (generateMetadata)
- Metadados baseados em arquivo (icon.png, opengraph-image.png)
- Metadados Open Graph
- Twitter Cards
- Dados estruturados JSON-LD
- Configuração de Viewport
- Manifest PWA
- Robots.txt
- Geração de Sitemap
✅ Validador de Padrões
Script Python executável que verifica:
- Server Components não usam APIs exclusivas do cliente
- Client Components têm a diretiva 'use client'
- A busca de dados usa a estratégia de cache adequada
- Server Actions são marcadas com 'use server'
- API de metadados usada corretamente
- Otimização de imagem ( não )
- Importações dinâmicas para componentes pesados
Execute com: python validate-patterns.py /caminho/para/src
Referência Rápida
Árvore de Decisão: Server vs Client Components
Você precisa de interatividade (onClick, onChange, etc.)?
├─ SIM → Client Component ('use client')
└─ NÃO → Server Component (padrão)
Você precisa de hooks do React (useState, useEffect)?
├─ SIM → Client Component
└─ NÃO → Server Component
Você precisa de APIs do navegador (window, localStorage)?
├─ SIM → Client Component
└─ NÃO → Server Component
Você precisa buscar dados?
├─ Use Server Component (preferido)
└─ Use Client Component apenas se os dados precisarem estar no lado do cliente
O componente é puramente de apresentação?
└─ Server Component (melhor desempenho)
Padrões Comuns
1. Busca de Dados em Server Component
// app/projects/page.tsx
export default async function ProjectsPage() {
const projects = await db.project.findMany()
return <ProjectList projects={projects} />
}
2. Client Component com Interatividade
// components/ProjectCard.tsx
'use client'
import { useState } from 'react'
export function ProjectCard({ project }: Props) {
const [loading, setLoading] = useState(false)
const handleDelete = async () => {
setLoading(true)
await deleteProject(project.id)
setLoading(false)
}
return (
<div>
<h2>{project.name}</h2>
<button onClick={handleDelete} disabled={loading}>
Delete
</button>
</div>
)
}
3. Server Action com Formulário
// app/actions.ts
'use server'
export async function createProject(formData: FormData) {
const name = formData.get('name') as string
const project = await db.project.create({ data: { name } })
revalidatePath('/projects')
return { success: true, project }
}
// app/projects/new/page.tsx
import { createProject } from '@/app/actions'
export default function NewProjectPage() {
return (
<form action={createProject}>
<input name="name" required />
<button type="submit">Create</button>
</form>
)
}
4. Streaming com Suspense
// app/dashboard/page.tsx
import { Suspense } from 'react'
export default function DashboardPage() {
return (
<div>
<Suspense fallback={<ProjectsSkeleton />}>
<ProjectsAsync />
</Suspense>
<Suspense fallback={<UsersSkeleton />}>
<UsersAsync />
</Suspense>
</div>
)
}
async function ProjectsAsync() {
const projects = await fetchProjects() // Consulta lenta
return <ProjectList projects={projects} />
}
5. Metadados Dinâmicos
// app/blog/[slug]/page.tsx
import type { Metadata } from 'next'
export async function generateMetadata({
params,
}: {
params: Promise<{ slug: string }>
}): Promise<Metadata> {
const { slug } = await params
const post = await fetchPost(slug)
return {
title: post.title,
description: post.excerpt,
openGraph: {
title: post.title,
description: post.excerpt,
images: [post.coverImage],
},
}
}
Melhores Práticas para Quetrex
1. Prefira Server Components
// ✅ FAÇA: Server Component (padrão)
export default async function ProjectsPage() {
const projects = await fetchProjects()
return <ProjectList projects={projects} />
}
// ❌ NÃO FAÇA: Client Component quando não necessário
'use client'
export default function ProjectsPage() {
const [projects, setProjects] = useState([])
useEffect(() => {
fetchProjects().then(setProjects)
}, [])
return <ProjectList projects={projects} />
}
2. Use Estratégia de Cache Adequada
// Conteúdo estático (cache para sempre)
const categories = await fetch('https://api.example.com/categories', {
cache: 'force-cache',
}).then(r => r.json())
// Conteúdo dinâmico (sem cache)
const user = await fetch('https://api.example.com/me', {
cache: 'no-store',
}).then(r => r.json())
// ISR (revalidar a cada hora)
const products = await fetch('https://api.example.com/products', {
next: { revalidate: 3600 },
}).then(r => r.json())
3. Implemente Limites de Erro Adequados
// app/dashboard/error.tsx
'use client'
export default function DashboardError({
error,
reset,
}: {
error: Error
reset: () => void
}) {
return (
<div>
<h2>Something went wrong!</h2>
<button onClick={reset}>Try again</button>
</div>
)
}
4. Use Estados de Carregamento
// app/dashboard/loading.tsx
export default function DashboardLoading() {
return <DashboardSkeleton />
}
5. Otimize Imagens
// ✅ FAÇA: Use next/image
import Image from 'next/image'
export function ProjectCard({ project }) {
return (
<Image
src={project.image}
alt={project.name}
width={400}
height={300}
/>
)
}
// ❌ NÃO FAÇA: Use tag <img>
export function ProjectCard({ project }) {
return <img src={project.image} alt={project.name} />
}
Erros Comuns a Evitar
❌ Erro 1: Client Component Assíncrono
// ❌ NÃO FAÇA: Isso é um erro de sintaxe
'use client'
export default async function BadComponent() {
const data = await fetch('/api/data')
return <div>{data}</div>
}
// ✅ FAÇA: Use Server Component ou useEffect
export default async function GoodComponent() {
const data = await fetch('/api/data')
return <div>{data}</div>
}
❌ Erro 2: APIs do Cliente em Server Component
// ❌ NÃO FAÇA: Server Components não podem usar APIs do navegador
export default function BadComponent() {
const [state, setState] = useState(false) // Erro!
return <div>{state}</div>
}
// ✅ FAÇA: Adicione a diretiva 'use client'
'use client'
export default function GoodComponent() {
const [state, setState] = useState(false)
return <div>{state}</div>
}
❌ Erro 3: Estratégia de Cache Ausente
// ❌ NÃO FAÇA: Comportamento de cache incerto
const data = await fetch('/api/data')
// ✅ FAÇA: Estratégia de cache explícita
const data = await fetch('/api/data', {
cache: 'no-store', // ou 'force-cache', ou { next: { revalidate: 60 } }
})
❌ Erro 4: Não Usar
// ❌ NÃO FAÇA: Imagens não otimizadas
<img src="/logo.png" alt="Logo" />
// ✅ FAÇA: Use a otimização de imagem do Next.js
<Image src="/logo.png" alt="Logo" width={200} height={100} />
Solução de Problemas
Erro: "You're importing a component that needs useState..."
Solução: Adicione 'use client' ao arquivo do componente.
Erro: "async/await is not valid in Client Components"
Solução: Remova 'use client' ou use useEffect em vez de um componente assíncrono.
Erro: "process is not defined"
Solução: Variáveis de ambiente em Client Components precisam do prefixo NEXT_PUBLIC_.
Erro: "Headers already sent"
Solução: Não use headers() ou cookies() após enviar a resposta. Chame-os antes de qualquer streaming.
Documentação Oficial
- Documentação Next.js 15.5: https://nextjs.org/docs
- App Router: https://nextjs.org/docs/app
- Busca de Dados: https://nextjs.org/docs/app/building-your-application/data-fetching
- Server Actions: https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations
- Cache: https://nextjs.org/docs/app/building-your-application/caching
- Metadados: https://nextjs.org/docs/app/building-your-application/optimizing/metadata
- Exemplos: https://github.com/vercel/next.js/tree/canary/examples
Validação
Execute o validador de padrões para verificar seu código:
python .claude/skills/nextjs-15-specialist/validate-patterns.py src/
O validador verifica:
- ✅ Client Components assíncronos (proibidos)
- ✅ APIs do cliente em Server Components
- ✅ Posicionamento da diretiva 'use client'
- ✅ Funções assíncronas de Server Actions
- ✅ Otimização de imagem
- ✅ Metadados em rotas dinâmicas
- ✅ Importações dinâmicas para componentes pesados
- ✅ Estratégias de cache fetch
- ✅ Configuração de segmento de rota
Resumo
Este skill garante que você:
- Escolha o tipo de componente correto (Server vs Client)
- Implemente padrões adequados de busca de dados
- Use estratégias de cache apropriadas
- Lide com Server Actions corretamente
- Otimize metadados e SEO
- Evite erros comuns do Next.js
- Siga as diretrizes de arquitetura do Quetrex
Em caso de dúvida:
- Leia o guia específico (links acima)
- Execute o validador
- Consulte a documentação oficial do Next.js 15
- Prefira Server Components
Última atualização: 2025-11-23 Versão do Next.js: 15.5 Total de Exemplos: 150+ Total de Linhas: 4.000+
