Especialista em Next.js App Router
Visão Geral
Orientação especializada para desenvolvimento com Next.js App Router, incluindo criação de páginas, roteamento dinâmico, layouts aninhados, otimização de componentes Server/Client e painéis baseados em papéis ERP.
Capacidades Principais
1. Criação de Páginas (/app/.../page.tsx)
Regras:
- Use Server Components por padrão (sem diretiva 'use client')
- Busca de dados assíncrona com
fetch()ou consultas ORM diretamente - Sem
useEffectpara carregamento inicial de dados - Use limites
Suspensepara estados de carregamento - Metadados SEO via
generateMetadata()
Modelo:
// app/dashboard/page.tsx
import { Suspense } from 'react';
import { TaskList } from '@/components/TaskList';
import { TaskListSkeleton } from '@/components/TaskListSkeleton';
export const metadata = {
title: 'Dashboard',
description: 'Seu painel de gerenciamento de tarefas',
};
export default async function DashboardPage() {
const tasks = await fetchTasks();
return (
<main className="p-4">
<h1>Dashboard</h1>
<Suspense fallback={<TaskListSkeleton />}>
<TaskList initialTasks={tasks} />
</Suspense>
</main>
);
}
2. Rotas Dinâmicas ([slug]/page.tsx)
Quando usar:
- Perfis de estudante:
app/students/[studentId]/page.tsx - Detalhes de tarefa:
app/tasks/[taskId]/page.tsx - Páginas de curso:
app/courses/[courseId]/page.tsx
Regras:
- Extraia parâmetros da prop
params(somente leitura) - Use
generateMetadata()para SEO - Trate 404 com
not-found.tsx
Modelo:
// app/students/[studentId]/page.tsx
import { notFound } from 'next/navigation';
type Params = Promise<{ studentId: string }>;
export async function generateMetadata({ params }: { params: Params }) {
const { studentId } = await params;
const student = await getStudent(studentId);
if (!student) return { title: 'Estudante Não Encontrado' };
return {
title: `${student.name} - Perfil do Estudante`,
};
}
export default async function StudentProfile({ params }: { params: Params }) {
const { studentId } = await params;
const student = await getStudent(studentId);
if (!student) notFound();
return <StudentProfileView student={student} />;
}
3. Rotas Paralelas (@folder)
Quando usar:
- Variantes de dashboard:
app/dashboard@(admin|teacher)/page.tsx - Layouts divididos:
app/settings@(user|organization)/layout.tsx
Modelo:
// app/dashboard/@admin/page.tsx - Dashboard do admin
export default function AdminDashboard() {
return <AdminPanel />;
}
// app/dashboard/@teacher/page.tsx - Dashboard do professor
export default function TeacherDashboard() {
return <TeacherPanel />;
}
4. Layouts e Modelos
Layout Raiz (app/layout.tsx):
import { Providers } from '@/components/Providers';
import './globals.css';
export const metadata = {
title: 'Todo Evolution',
description: 'Gerenciamento de tarefas para educação',
};
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<Providers>{children}</Providers>
</body>
</html>
);
}
Layout Aninhado (app/dashboard/layout.tsx):
import { DashboardNav } from '@/components/DashboardNav';
export default function DashboardLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<div className="flex min-h-screen">
<DashboardNav />
<main className="flex-1 p-6">{children}</main>
</div>
);
}
Modelo (app/tasks/template.tsx):
// Reexecuta na navegação, preserva o estado do formulário
export default function TasksTemplate({ children }: { children: React.ReactNode }) {
return (
<div className="bg-gray-50 min-h-screen">
<header className="bg-white shadow">
<h1>Tarefas</h1>
</header>
{children}
</div>
);
}
5. Componentes Server vs Client
Use Server Components para:
- Busca de dados
- Consultas diretas ao banco de dados
- Conteúdo estático
- Operações exclusivas do servidor
Use Client Components ('use client') para:
- APIs do navegador (
window,localStorage) - Manipuladores de eventos (
onClick,onSubmit) - Hooks React (
useState,useEffect) - Gerenciamento de estado (Zustand, Redux)
- Interatividade
// Server Component (padrão)
export default async function TaskList() {
const tasks = await fetchTasks(); // Consulta direta ao BD
return <div>{tasks.map(/* ... */)}</div>;
}
// Client Component
'use client';
import { useTaskStore } from '@/store/tasks';
export function TaskFilter() {
const { filter, setFilter } = useTaskStore();
return <button onClick={() => setFilter('all')}>Todas as Tarefas</button>;
}
6. Páginas Baseadas em Papéis ERP
Guardas de Papel:
// app/admin/page.tsx
import { requireRole } from '@/lib/auth';
import { redirect } from 'next/navigation';
export default async function AdminPage() {
const session = await getSession();
if (session?.role !== 'admin') {
redirect('/unauthorized');
}
return <AdminDashboard />;
}
Dashboard KPI (Recharts):
'use client';
import { BarChart, Bar, XAxis, YAxis, Tooltip } from 'recharts';
export function TaskKPIChart({ data }: { data: TaskStats[] }) {
return (
<BarChart width={600} height={300} data={data}>
<XAxis dataKey="date" />
<YAxis />
<Tooltip />
<Bar dataKey="completed" fill="#22c55e" />
</BarChart>
);
}
7. Estados de Erro e Carregamento
Limite de Erro (error.tsx):
'use client';
export default function Error({
error,
reset,
}: {
error: Error & { digest?: string };
reset: () => void;
}) {
return (
<div>
<h2>Algo deu errado!</h2>
<button onClick={reset}>Tentar novamente</button>
</div>
);
}
Estado de Carregamento (loading.tsx):
export default function Loading() {
return <div className="animate-pulse">Carregando...</div>;
}
// Ou com Suspense:
export default async function Page() {
return (
<Suspense fallback={<Loading />}>
<Content />
</Suspense>
);
}
8. Integração shadcn/ui
Instalação:
npx shadcn@latest add button card input dialog
Uso em Server Components:
import { Button } from '@/components/ui/button';
import { Card, CardContent, CardHeader } from '@/components/ui/card';
export default async function TaskPage() {
const tasks = await getTasks();
return (
<Card>
<CardHeader>Tarefas</CardHeader>
<CardContent>
{tasks.map(task => (
<div key={task.id}>{task.title}</div>
))}
</CardContent>
</Card>
);
}
Árvore de Decisão do Fluxo de Trabalho
Solicitação do Usuário → Analisar → Caminho de Implementação
-
"Criar página Dashboard/Admin" → Server Component com
page.tsx→ Busca de dados assíncrona → Adicionarlayout.tsxse necessário para navegação -
"Perfil dinâmico de estudante" → Criar
[studentId]/page.tsx→ Extrair parâmetros → AdicionargenerateMetadata()→ Criarnot-found.tsxse necessário -
"Adicionar layout compartilhado" → Criar
layout.tsxna pasta alvo → Envolver com providers se necessário → Manter a renderização de children -
"Adicionar formulário" → Componente
'use client'→ useState para dados do formulário → Server Action para envio OU rota de API -
"Gráficos KPI / Analytics" →
'use client'para Recharts → Parent Server Component com busca de dados → Passar dados como props
Lista de Verificação de Qualidade
Antes de marcar a tarefa como concluída:
- Modo estrito TypeScript ativado
- Server Components usados por padrão
-
'use client'somente quando necessário -
generateMetadata()para SEO - Limites Suspense para dados assíncronos
- Limites de erro (
error.tsx) onde necessário - Sem incompatibilidades de hidratação
- Performance otimizada (sem renderizações bloqueantes)
- Design responsivo mobile-first
- Acessível (rótulos ARIA, navegação por teclado)
Padrões Comuns
Padrão 1: Mistura de Server Component + Client Component
// Server Component
export default async function Page() {
const tasks = await fetchTasks();
return <TaskList tasks={tasks} />; // Client component para interatividade
}
'use client';
function TaskList({ tasks }: { tasks: Task[] }) {
const [filter, setFilter] = useState('all');
const filtered = tasks.filter(/* ... */);
return <div>{filtered.map(/* ... */)}</div>;
}
Padrão 2: Grupos de Rotas para Organização
app/
(marketing)/ # Grupo: sem segmento de URL
about/page.tsx
contact/page.tsx
(dashboard)/ # Grupo: sem segmento de URL
layout.tsx
page.tsx
Padrão 3: Rotas de API (Route Handlers)
// app/api/tasks/route.ts
import { NextResponse } from 'next/server';
export async function GET() {
const tasks = await db.query.tasks.findMany();
return NextResponse.json(tasks);
}
export async function POST(request: Request) {
const body = await request.json();
const task = await createTask(body);
return NextResponse.json(task, { status: 201 });
}
Exemplos de Disparo
- "Criar página Dashboard" → Gerar
app/dashboard/page.tsxcom server component - "Rota dinâmica de perfil de estudante" →
app/students/[studentId]/page.tsxcom parâmetros e metadados - "Adicionar layout compartilhado" →
app/dashboard/layout.tsxcom children - "Painel admin com gráficos" → Server component + Client component de gráfico
- "Criar página de login" → Componente formulário
'use client'+ rota de API - "Personalizar página 404" →
app/not-found.tsx - "Tratar erro" →
app/dashboard/error.tsx
Referências
Consulte references/app-router-patterns.md para padrões avançados e references/api-routes.md para exemplos de route handlers.