Expert de l'App Router Next.js
Aperçu
Guide d'expertise pour le développement avec l'App Router Next.js, incluant la création de pages, le routage dynamique, les layouts imbriqués, l'optimisation des composants Server/Client et les tableaux de bord ERP basés sur les rôles.
Capacités principales
1. Création de pages (/app/.../page.tsx)
Règles :
- Utiliser les Server Components par défaut (pas de directive 'use client')
- Récupération asynchrone des données avec
fetch()ou requêtes ORM directement - Pas de
useEffectpour le chargement initial des données - Utiliser des limites
Suspensepour les états de chargement - Métadonnées SEO via
generateMetadata()
Modèle :
// app/dashboard/page.tsx
import { Suspense } from 'react';
import { TaskList } from '@/components/TaskList';
import { TaskListSkeleton } from '@/components/TaskListSkeleton';
export const metadata = {
title: 'Tableau de bord',
description: 'Votre tableau de bord de gestion des tâches',
};
export default async function DashboardPage() {
const tasks = await fetchTasks();
return (
<main className="p-4">
<h1>Tableau de bord</h1>
<Suspense fallback={<TaskListSkeleton />}>
<TaskList initialTasks={tasks} />
</Suspense>
</main>
);
}
2. Routes dynamiques ([slug]/page.tsx)
Quand les utiliser :
- Profils étudiants :
app/students/[studentId]/page.tsx - Détails d'une tâche :
app/tasks/[taskId]/page.tsx - Pages de cours :
app/courses/[courseId]/page.tsx
Règles :
- Extraire les paramètres de la prop
params(en lecture seule) - Utiliser
generateMetadata()pour le SEO - Gérer les erreurs 404 avec
not-found.tsx
Modèle :
// 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: 'Étudiant non trouvé' };
return {
title: `${student.name} - Profil étudiant`,
};
}
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. Routes parallèles (@dossier)
Quand les utiliser :
- Variantes du tableau de bord :
app/dashboard@(admin|teacher)/page.tsx - Layouts scindés :
app/settings@(user|organization)/layout.tsx
Modèle :
// app/dashboard/@admin/page.tsx - Tableau de bord admin
export default function AdminDashboard() {
return <AdminPanel />;
}
// app/dashboard/@teacher/page.tsx - Tableau de bord enseignant
export default function TeacherDashboard() {
return <TeacherPanel />;
}
4. Layouts et Templates
Layout racine (app/layout.tsx) :
import { Providers } from '@/components/Providers';
import './globals.css';
export const metadata = {
title: 'Todo Evolution',
description: 'Gestion de tâches pour l\'éducation',
};
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="fr">
<body>
<Providers>{children}</Providers>
</body>
</html>
);
}
Layout imbriqué (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>
);
}
Template (app/tasks/template.tsx) :
// Se réexécute lors de la navigation, préserve l'état du formulaire
export default function TasksTemplate({ children }: { children: React.ReactNode }) {
return (
<div className="bg-gray-50 min-h-screen">
<header className="bg-white shadow">
<h1>Tâches</h1>
</header>
{children}
</div>
);
}
5. Composants Server vs Client
Utiliser les Server Components pour :
- La récupération de données
- Les requêtes directes à la base de données
- Le contenu statique
- Les opérations exclusives au serveur
Utiliser les Client Components ('use client') pour :
- Les API du navigateur (
window,localStorage) - Les gestionnaires d'événements (
onClick,onSubmit) - Les hooks React (
useState,useEffect) - La gestion d'état (Zustand, Redux)
- L'interactivité
// Server Component (par défaut)
export default async function TaskList() {
const tasks = await fetchTasks(); // Requête DB directe
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')}>Toutes les tâches</button>;
}
6. Pages ERP basées sur les rôles
Gardes de rôle :
// 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 />;
}
Tableau de bord 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. États d'erreur et de chargement
Boundaire d'erreur (error.tsx) :
'use client';
export default function Error({
error,
reset,
}: {
error: Error & { digest?: string };
reset: () => void;
}) {
return (
<div>
<h2>Une erreur est survenue !</h2>
<button onClick={reset}>Réessayer</button>
</div>
);
}
État de chargement (loading.tsx) :
export default function Loading() {
return <div className="animate-pulse">Chargement...</div>;
}
// Ou avec Suspense :
export default async function Page() {
return (
<Suspense fallback={<Loading />}>
<Content />
</Suspense>
);
}
8. Intégration shadcn/ui
Installation :
npx shadcn@latest add button card input dialog
Utilisation dans les 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>Tâches</CardHeader>
<CardContent>
{tasks.map(task => (
<div key={task.id}>{task.title}</div>
))}
</CardContent>
</Card>
);
}
Arbre de décision du workflow
Requête utilisateur → Analyser → Chemin d'implémentation
-
"Crée une page tableau de bord/admin" → Server Component avec
page.tsx→ Récupération asynchrone des données → Ajouterlayout.tsxsi la navigation est nécessaire -
"Profil étudiant dynamique" → Créer
[studentId]/page.tsx→ Extraire les paramètres → AjoutergenerateMetadata()→ Créernot-found.tsxsi nécessaire -
"Ajouter un layout partagé" → Créer
layout.tsxdans le dossier cible → Envelopper avec des providers si nécessaire → Conserver le rendu des enfants -
"Ajouter un formulaire" → Composant
'use client'→ useState pour les données du formulaire → Server Action pour la soumission OU route API -
"Graphiques KPI / Analytics" →
'use client'pour Recharts → Parent Server Component avec récupération des données → Transmettre les données en tant que props
Checklist qualité
Avant de marquer la tâche comme terminée :
- Mode strict TypeScript activé
- Server Components utilisés par défaut
-
'use client'uniquement lorsque nécessaire -
generateMetadata()pour le SEO - Limites Suspense pour les données asynchrones
- Boundaries d'erreur (
error.tsx) si nécessaire - Pas de divergences d'hydratation
- Performances optimisées (aucun rendu bloquant)
- Design responsive mobile-first
- Accessible (labels ARIA, navigation clavier)
Schémas courants
Schéma 1 : Mélange Server Component + Client Component
// Server Component
export default async function Page() {
const tasks = await fetchTasks();
return <TaskList tasks={tasks} />; // Client component pour l'interactivité
}
'use client';
function TaskList({ tasks }: { tasks: Task[] }) {
const [filter, setFilter] = useState('all');
const filtered = tasks.filter(/* ... */);
return <div>{filtered.map(/* ... */)}</div>;
}
Schéma 2 : Groupes de routes pour l'organisation
app/
(marketing)/ # Groupe : aucun segment d'URL
about/page.tsx
contact/page.tsx
(dashboard)/ # Groupe : aucun segment d'URL
layout.tsx
page.tsx
Schéma 3 : Routes 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 });
}
Exemples de déclencheurs
- "Crée une page de tableau de bord" → Générer
app/dashboard/page.tsxavec un server component - "Route de profil étudiant dynamique" →
app/students/[studentId]/page.tsxavec paramètres et métadonnées - "Ajouter un layout partagé" →
app/dashboard/layout.tsxavec enfants - "Panneau d'administration avec graphiques" → Server component + composant graphique Client
- "Crée une page de connexion" → Composant formulaire
'use client'+ route API - "Personnaliser la page 404" →
app/not-found.tsx - "Gérer les erreurs" →
app/dashboard/error.tsx
Références
Voir references/app-router-patterns.md pour les schémas avancés et references/api-routes.md pour les exemples de route handlers.