Experto en App Router de Next.js
Resumen
Guía experta para el desarrollo con el App Router de Next.js, que incluye creación de páginas, enrutamiento dinámico, layouts anidados, optimización de componentes Server/Client y paneles ERP basados en roles.
Capacidades Principales
1. Creación de Páginas (/app/.../page.tsx)
Reglas:
- Usar Componentes Server por defecto (sin directiva 'use client')
- Obtención asíncrona de datos con
fetch()o consultas ORM directamente - Sin
useEffectpara la carga inicial de datos - Usar límites
Suspensepara estados de carga - Metadatos SEO a través de
generateMetadata()
Plantilla:
// app/dashboard/page.tsx
import { Suspense } from 'react';
import { TaskList } from '@/components/TaskList';
import { TaskListSkeleton } from '@/components/TaskListSkeleton';
export const metadata = {
title: 'Dashboard',
description: 'Tu panel de gestión de tareas',
};
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. Rutas Dinámicas ([slug]/page.tsx)
Cuándo usarlas:
- Perfiles de estudiantes:
app/students/[studentId]/page.tsx - Detalles de tareas:
app/tasks/[taskId]/page.tsx - Páginas de cursos:
app/courses/[courseId]/page.tsx
Reglas:
- Extraer parámetros de la prop
params(solo lectura) - Usar
generateMetadata()para SEO - Manejar 404 con
not-found.tsx
Plantilla:
// 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: 'Estudiante No Encontrado' };
return {
title: `${student.name} - Perfil de Estudiante`,
};
}
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. Rutas Paralelas (@folder)
Cuándo usarlas:
- Variantes de dashboard:
app/dashboard@(admin|teacher)/page.tsx - Layouts divididos:
app/settings@(user|organization)/layout.tsx
Plantilla:
// app/dashboard/@admin/page.tsx - Dashboard de administrador
export default function AdminDashboard() {
return <AdminPanel />;
}
// app/dashboard/@teacher/page.tsx - Dashboard de profesor
export default function TeacherDashboard() {
return <TeacherPanel />;
}
4. Layouts y Plantillas
Layout Raíz (app/layout.tsx):
import { Providers } from '@/components/Providers';
import './globals.css';
export const metadata = {
title: 'Todo Evolution',
description: 'Gestión de tareas para educación',
};
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="es">
<body>
<Providers>{children}</Providers>
</body>
</html>
);
}
Layout Anidado (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>
);
}
Plantilla (app/tasks/template.tsx):
// Se re-ejecuta en la navegación, conserva el estado del formulario
export default function TasksTemplate({ children }: { children: React.ReactNode }) {
return (
<div className="bg-gray-50 min-h-screen">
<header className="bg-white shadow">
<h1>Tareas</h1>
</header>
{children}
</div>
);
}
5. Componentes Server vs Client
Usar Componentes Server para:
- Obtención de datos
- Consultas directas a base de datos
- Contenido estático
- Operaciones solo del servidor
Usar Componentes Client ('use client') para:
- APIs del navegador (
window,localStorage) - Manejadores de eventos (
onClick,onSubmit) - Hooks de React (
useState,useEffect) - Gestión de estado (Zustand, Redux)
- Interactividad
// Componente Server (por defecto)
export default async function TaskList() {
const tasks = await fetchTasks(); // Consulta directa a DB
return <div>{tasks.map(/* ... */)}</div>;
}
// Componente Client
'use client';
import { useTaskStore } from '@/store/tasks';
export function TaskFilter() {
const { filter, setFilter } = useTaskStore();
return <button onClick={() => setFilter('all')}>Todas las Tareas</button>;
}
6. Páginas ERP Basadas en Roles
Guardianes de Rol:
// 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 Error y Carga
Límite de Error (error.tsx):
'use client';
export default function Error({
error,
reset,
}: {
error: Error & { digest?: string };
reset: () => void;
}) {
return (
<div>
<h2>¡Algo salió mal!</h2>
<button onClick={reset}>Intentar de nuevo</button>
</div>
);
}
Estado de Carga (loading.tsx):
export default function Loading() {
return <div className="animate-pulse">Cargando...</div>;
}
// O con Suspense:
export default async function Page() {
return (
<Suspense fallback={<Loading />}>
<Content />
</Suspense>
);
}
8. Integración con shadcn/ui
Instalación:
npx shadcn@latest add button card input dialog
Uso en Componentes Server:
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>Tareas</CardHeader>
<CardContent>
{tasks.map(task => (
<div key={task.id}>{task.title}</div>
))}
</CardContent>
</Card>
);
}
Árbol de Decisión del Flujo de Trabajo
Solicitud del Usuario → Analizar → Ruta de Implementación
-
"Crear página de Dashboard/Admin" → Componente Server con
page.tsx→ Obtención asíncrona de datos → Agregarlayout.tsxsi se necesita navegación -
"Perfil de estudiante dinámico" → Crear
[studentId]/page.tsx→ Extraer parámetros → AgregargenerateMetadata()→ Crearnot-found.tsxsi es necesario -
"Agregar layout compartido" → Crear
layout.tsxen la carpeta destino → Envolver con providers si es necesario → Mantener el renderizado de children -
"Agregar formulario" → Componente con
'use client'→ useState para datos del formulario → Server Action para el envío O ruta de API -
"Gráficos KPI/Análisis" →
'use client'para Recharts → Componente Server padre con obtención de datos → Pasar datos como props
Lista de Verificación de Calidad
Antes de marcar la tarea como completada:
- Modo estricto de TypeScript habilitado
- Componentes Server usados por defecto
-
'use client'solo cuando sea necesario -
generateMetadata()para SEO - Límites Suspense para datos asíncronos
- Límites de error (
error.tsx) donde sea necesario - Sin errores de hidratación
- Rendimiento optimizado (sin renderizados bloqueantes)
- Diseño responsive mobile-first
- Accesible (etiquetas ARIA, navegación por teclado)
Patrones Comunes
Patrón 1: Mezcla de Componentes Server + Client
// Componente Server
export default async function Page() {
const tasks = await fetchTasks();
return <TaskList tasks={tasks} />; // Componente Client para interactividad
}
'use client';
function TaskList({ tasks }: { tasks: Task[] }) {
const [filter, setFilter] = useState('all');
const filtered = tasks.filter(/* ... */);
return <div>{filtered.map(/* ... */)}</div>;
}
Patrón 2: Grupos de Rutas para Organización
app/
(marketing)/ # Grupo: sin segmento de URL
about/page.tsx
contact/page.tsx
(dashboard)/ # Grupo: sin segmento de URL
layout.tsx
page.tsx
Patrón 3: Rutas de API (Manejadores de Ruta)
// 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 });
}
Ejemplos de Disparo
- "Crear página de Dashboard" → Generar
app/dashboard/page.tsxcon componente server - "Ruta dinámica de perfil de estudiante" →
app/students/[studentId]/page.tsxcon params y metadata - "Agregar layout compartido" →
app/dashboard/layout.tsxcon children - "Panel de administración con gráficos" → Componente Server + componente Client de gráficos
- "Crear página de inicio de sesión" → Componente formulario con
'use client'+ ruta de API - "Personalizar página 404" →
app/not-found.tsx - "Manejar error" →
app/dashboard/error.tsx
Referencias
Ver references/app-router-patterns.md para patrones avanzados y references/api-routes.md para ejemplos de manejadores de ruta.