Spécialiste Next.js 15 + App Router
Référence complète Next.js 15 pour le développement Quetrex.
Cette compétence fournit des directives complètes sur tous les motifs de l'App Router Next.js 15, garantissant que les agents implémentent Next.js moderne correctement du premier coup.
RÈGLES CRITIQUES (NE JAMAIS VIOLER)
Ces règles sont NON-NÉGOCIABLES. Les violations casseront les builds.
1. Utilisez TOUJOURS <Image> de next/image - N'utilisez JAMAIS <img>
// ✅ À FAIRE TOUJOURS
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} />
// ❌ NE JAMAIS FAIRE CELA - LE BUILD ÉCHOUERA
<img src="/logo.png" alt="Logo" />
<img src={user.avatar} alt={user.name} />
Pourquoi : Le composant Image de Next.js fournit une optimisation automatique, un chargement paresseux et évite les décalages de mise en page. ESLint est configuré pour faire échouer les builds en cas d'utilisation de <img>.
2. Les Server Components sont la VALEUR PAR DÉFAUT - n'ajoutez 'use client' que lorsque c'est nécessaire
3. Ne créez jamais de Client Components asynchrones
4. Spécifiez toujours la stratégie de cache pour fetch()
Quand utiliser cette compétence
Utilisez cette compétence lorsque vous travaillez avec :
- Création de nouvelles routes ou pages
- Implémentation de récupération de données (Server Components vs Client Components)
- Décisions Server vs Client Components
- Server Actions et gestion de formulaires
- Streaming et Suspense
- Métadonnées et SEO
- Gestionnaires de routes (API routes)
- Stratégies de mise en cache
- Optimisation des performances
Documentation complète
Cette compétence comprend des guides complets couvrant chaque motif Next.js 15 :
📁 Guide complet de l'App Router
45+ exemples couvrant :
- Routage basé sur les fichiers (page.tsx, layout.tsx, route.ts)
- Routes dynamiques ([id], [...slug], [[...slug]])
- Groupes de routes ((group))
- Dossiers privés (_folder)
- Gestionnaires de routes (API routes)
- Layouts et templates
- UI de chargement (loading.tsx)
- Limites d'erreur (error.tsx, global-error.tsx)
- Pages non trouvées (not-found.tsx)
- Routes parallèles (@folder)
- Routes d'interception ((.)folder)
- Configuration de segment de route (dynamic, revalidate, runtime)
🔄 Guide complet de récupération de données
35+ exemples couvrant :
- Récupération de données dans les Server Components (async/await)
- Récupération de données dans les Client Components (useEffect, React Query, SWR)
- Récupération parallèle de données (Promise.all)
- Récupération séquentielle de données (prévention des cascades)
- Streaming de données (limites Suspense)
- Événements envoyés par le serveur (SSE pour la voix Quetrex)
- Mutations de données (Server Actions)
- Mises à jour optimistes (useOptimistic)
- Gestion de formulaires (useFormStatus, useActionState)
- Déduplication de requêtes
- Préchargement de données
💾 Guide des stratégies de mise en cache
35+ exemples couvrant :
- Mémoïsation de requêtes (déduplication automatique)
- Cache de données (comportement du cache de fetch)
- Cache de route complet (statique vs dynamique)
- Cache du routeur (cache côté client)
- Configuration du cache (force-cache, no-store, revalidate)
- Tags de cache (revalidateTag, revalidatePath)
- Revalidation à la demande
- Revalidation basée sur le temps (ISR)
- Techniques de débogage du cache
- Refus de mise en cache
⚡ Guide complet des Server Actions
31+ exemples couvrant :
- Motifs de base des Server Actions
- Actions de formulaire (amélioration progressive)
- Actions de bouton (appels programmatiques)
- Hook useFormStatus (états de chargement)
- Hook useActionState (gestion d'état)
- Hook useOptimistic (UI optimiste)
- Gestion d'erreurs dans les actions
- Validation avec Zod
- Retourner JSON vs redirection
- Sécurité (authentification, CSRF)
- Limitation de débit
- Transactions de base de données
🎯 Guide de l'API Metadata
26+ exemples couvrant :
- Métadonnées statiques (objet exporté)
- Métadonnées dynamiques (generateMetadata)
- Métadonnées basées sur des fichiers (icon.png, opengraph-image.png)
- Métadonnées Open Graph
- Twitter Cards
- Données structurées JSON-LD
- Configuration de la fenêtre d'affichage
- Manifeste PWA
- Robots.txt
- Génération de Sitemap
✅ Validateur de motifs
Script Python exécutable qui vérifie :
- Les Server Components n'utilisent pas d'API réservées au client
- Les Client Components ont la directive 'use client'
- La récupération de données utilise une stratégie de cache appropriée
- Les Server Actions sont marquées avec 'use server'
- L'API Metadata est utilisée correctement
- L'optimisation des images ( non )
- Les importations dynamiques pour les composants lourds
Exécutez avec : python validate-patterns.py /chemin/vers/src
Référence rapide
Arbre de décision Server vs Client Components
Avez-vous besoin d'interactivité (onClick, onChange, etc.) ?
├─ OUI → Client Component ('use client')
└─ NON → Server Component (par défaut)
Avez-vous besoin de hooks React (useState, useEffect) ?
├─ OUI → Client Component
└─ NON → Server Component
Avez-vous besoin d'API navigateur (window, localStorage) ?
├─ OUI → Client Component
└─ NON → Server Component
Avez-vous besoin de récupérer des données ?
├─ Utilisez un Server Component (recommandé)
└─ Utilisez un Client Component uniquement si les données doivent être côté client
Le composant est-il purement de présentation ?
└─ Server Component (meilleure performance)
Motifs courants
1. Récupération de données dans un Server Component
// app/projects/page.tsx
export default async function ProjectsPage() {
const projects = await db.project.findMany()
return <ProjectList projects={projects} />
}
2. Client Component avec interactivité
// 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}>
Supprimer
</button>
</div>
)
}
3. Server Action avec formulaire
// 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">Créer</button>
</form>
)
}
4. Streaming avec 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() // Requête lente
return <ProjectList projects={projects} />
}
5. Métadonnées dynamiques
// 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],
},
}
}
Bonnes pratiques pour Quetrex
1. Par défaut, utilisez les Server Components
// ✅ À FAIRE : Server Component (par défaut)
export default async function ProjectsPage() {
const projects = await fetchProjects()
return <ProjectList projects={projects} />
}
// ❌ À NE PAS FAIRE : Client Component quand ce n'est pas nécessaire
'use client'
export default function ProjectsPage() {
const [projects, setProjects] = useState([])
useEffect(() => {
fetchProjects().then(setProjects)
}, [])
return <ProjectList projects={projects} />
}
2. Utilisez une stratégie de cache appropriée
// Contenu statique (mis en cache pour toujours)
const categories = await fetch('https://api.example.com/categories', {
cache: 'force-cache',
}).then(r => r.json())
// Contenu dynamique (pas de cache)
const user = await fetch('https://api.example.com/me', {
cache: 'no-store',
}).then(r => r.json())
// ISR (revalidation toutes les heures)
const products = await fetch('https://api.example.com/products', {
next: { revalidate: 3600 },
}).then(r => r.json())
3. Implémentez des limites d'erreur appropriées
// app/dashboard/error.tsx
'use client'
export default function DashboardError({
error,
reset,
}: {
error: Error
reset: () => void
}) {
return (
<div>
<h2>Quelque chose s'est mal passé !</h2>
<button onClick={reset}>Réessayer</button>
</div>
)
}
4. Utilisez les états de chargement
// app/dashboard/loading.tsx
export default function DashboardLoading() {
return <DashboardSkeleton />
}
5. Optimisez les images
// ✅ À FAIRE : Utilisez next/image
import Image from 'next/image'
export function ProjectCard({ project }) {
return (
<Image
src={project.image}
alt={project.name}
width={400}
height={300}
/>
)
}
// ❌ À NE PAS FAIRE : Utilisez la balise <img>
export function ProjectCard({ project }) {
return <img src={project.image} alt={project.name} />
}
Erreurs courantes à éviter
❌ Erreur 1 : Client Component asynchrone
// ❌ À NE PAS FAIRE : Ceci est une erreur de syntaxe
'use client'
export default async function BadComponent() {
const data = await fetch('/api/data')
return <div>{data}</div>
}
// ✅ À FAIRE : Utilisez un Server Component ou useEffect
export default async function GoodComponent() {
const data = await fetch('/api/data')
return <div>{data}</div>
}
❌ Erreur 2 : API clientes dans un Server Component
// ❌ À NE PAS FAIRE : Les Server Components ne peuvent pas utiliser les API navigateur
export default function BadComponent() {
const [state, setState] = useState(false) // Erreur !
return <div>{state}</div>
}
// ✅ À FAIRE : Ajoutez la directive 'use client'
'use client'
export default function GoodComponent() {
const [state, setState] = useState(false)
return <div>{state}</div>
}
❌ Erreur 3 : Stratégie de cache manquante
// ❌ À NE PAS FAIRE : Comportement de cache flou
const data = await fetch('/api/data')
// ✅ À FAIRE : Stratégie de cache explicite
const data = await fetch('/api/data', {
cache: 'no-store', // ou 'force-cache', ou { next: { revalidate: 60 } }
})
❌ Erreur 4 : Ne pas utiliser
// ❌ À NE PAS FAIRE : Images non optimisées
<img src="/logo.png" alt="Logo" />
// ✅ À FAIRE : Utilisez l'optimisation d'images Next.js
<Image src="/logo.png" alt="Logo" width={200} height={100} />
Dépannage
Erreur : "You're importing a component that needs useState..."
Solution : Ajoutez 'use client' au fichier du composant.
Erreur : "async/await is not valid in Client Components"
Solution : Supprimez 'use client' ou utilisez useEffect au lieu d'un composant asynchrone.
Erreur : "process is not defined"
Solution : Les variables d'environnement dans les Client Components doivent avoir le préfixe NEXT_PUBLIC_.
Erreur : "Headers already sent"
Solution : N'utilisez pas headers() ou cookies() après avoir envoyé la réponse. Appelez-les avant tout streaming.
Documentation officielle
- Docs Next.js 15.5 : https://nextjs.org/docs
- App Router : https://nextjs.org/docs/app
- Récupération de données : 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
- Mise en cache : https://nextjs.org/docs/app/building-your-application/caching
- Métadonnées : https://nextjs.org/docs/app/building-your-application/optimizing/metadata
- Exemples : https://github.com/vercel/next.js/tree/canary/examples
Validation
Exécutez le validateur de motifs pour vérifier votre code :
python .claude/skills/nextjs-15-specialist/validate-patterns.py src/
Le validateur vérifie :
- ✅ Les Client Components asynchrones (interdits)
- ✅ Les API clientes dans les Server Components
- ✅ Le placement de la directive 'use client'
- ✅ Les fonctions asynchrones des Server Actions
- ✅ L'optimisation des images
- ✅ Les métadonnées dans les routes dynamiques
- ✅ Les importations dynamiques pour les composants lourds
- ✅ Les stratégies de cache de fetch
- ✅ La configuration des segments de route
Résumé
Cette compétence garantit que vous :
- Choisissez le type de composant correct (Server vs Client)
- Implémentez des motifs de récupération de données appropriés
- Utilisez des stratégies de mise en cache adéquates
- Gérez correctement les Server Actions
- Optimisez les métadonnées et le SEO
- Évitez les erreurs courantes de Next.js
- Suivez les directives d'architecture de Quetrex
En cas de doute :
- Lisez le guide spécifique (liens ci-dessus)
- Exécutez le validateur
- Consultez la documentation officielle Next.js 15
- Par défaut, utilisez les Server Components
Dernière mise à jour : 2025-11-23 Version Next.js : 15.5 Nombre total d'exemples : 150+ Lignes totales : 4 000+
