# Claude Code Next.js : guide pratique pour développeurs

URL: https://agentvera.dev/fr/blog/claude-code-pour-nextjs/ · Publié: 2026-11-01

Guide pratique pour utiliser Claude Code sur un projet Next.js : configuration du CLAUDE.md, boucle de travail, tests et pièges à éviter.

**En bref:**

- Claude Code s’intègre bien aux projets Next.js à condition de lui fournir un CLAUDE.md précis avec les commandes de build, de test et de lint.
- Une boucle planifier, modifier, tester, relire le diff permet d’éviter les régressions sur les composants serveur et client.
- Surveillez les erreurs de frontière serveur/client, les routes API et les tests, puis utilisez plusieurs agents en parallèle pour accélérer.

[Claude Code](/fr/agents/claude-code/), lancé avec `claude` à la racine d’un projet Next.js, est un agent de codage qui lit le code, modifie des fichiers et exécute des commandes. Pour qu’il soit réellement efficace sur du Next.js, il lui faut un CLAUDE.md précis et une boucle de travail qui alterne petites modifications, tests et relecture du diff. Ce guide couvre ces points ainsi que les pièges spécifiques au framework.

## Pourquoi Claude Code convient au travail sur Next.js

Un projet Next.js mélange plusieurs responsabilités : composants serveur et client, routes API, fichiers de configuration, tests et rendu statique ou dynamique. Claude Code peut naviguer dans cette structure, proposer des modifications cohérentes entre plusieurs fichiers et exécuter les commandes du projet. Il comprend les idiomes de React et de Next.js : il sait générer un Route Handler, ajouter la directive `"use client"` ou extraire une Server Action. Mais cette polyvalence a un revers : sans règles claires, il peut déplacer du code entre frontières serveur et client ou modifier le comportement de cache. C’est pourquoi le cadrage initial compte autant que les compétences du modèle.

## Préparer le projet pour l’agent

Commencez par lancer `claude` dans le dossier du projet. L’agent lit automatiquement le fichier `CLAUDE.md` présent à la racine ; c’est là que vous devez décrire les commandes, l’arborescence et les règles Next.js. Le fichier doit rester court et factuel : pas de paraphrase, pas de promesses, uniquement ce que l’agent doit savoir pour éviter les erreurs.

Voici un exemple réaliste pour un projet App Router avec Vitest et Playwright :

```markdown
# CLAUDE.md

## Commandes
- `npm run dev` : démarre le serveur de développement Next.js sur le port 3000
- `npm run build` : build de production, exécute aussi le typage
- `npm run lint` : ESLint avec les règles Next.js
- `npm run test` : Vitest en mode run
- `npm run test:e2e` : Playwright pour les parcours utilisateur

## Conventions de dossiers
- `app/` : routes, layouts et Route Handlers de l’App Router
- `components/` : composants React réutilisables, souvent des Client Components
- `lib/` : fonctions pures, appels base de données, utilitaires serveur
- `tests/` : tests unitaires et de composants

## Règles Next.js
- Tout composant sans directive `"use client"` est un Server Component : pas de hooks, pas d’event handlers, pas d’API navigateur.
- Les Client Components doivent porter `"use client"` en première ligne ; ils ne peuvent pas importer directement des modules serveur-only.
- Les Route Handlers vivent dans `app/api/` ; ils s’exécutent côté serveur et ne doivent pas exposer de secrets.
- Utilise `fetch` avec les options `next: { revalidate }` pour la revalidation ISR ; ne mélange pas les stratégies de cache sans raison.
- Les variables d’environnement publiques sont préfixées `NEXT_PUBLIC_` ; les autres restent côté serveur.
```

Adaptez les dossiers si vous utilisez le Pages Router (`pages/`, `pages/api/`) ou Jest à la place de Vitest. Plus ce fichier reflète la réalité du dépôt, moins l’agent aura besoin de deviner.

## Une boucle de travail efficace

Ne demandez jamais une grosse fonctionnalité d’un bloc. Découpez le travail en étapes : planifier, modifier un fichier ou un petit ensemble, lancer les tests ciblés, relire le diff, puis itérer. Cette méthode réduit les corrections risquées et rend les erreurs plus faciles à attribuer. Pour une checklist complète, consultez les [bonnes pratiques Claude Code](/fr/blog/claude-code-best-practices/).

Exemples de prompts adaptés à Next.js :

- « Ajoute une page de connexion dans l’App Router avec un Server Component pour le formulaire et un Route Handler POST dans `app/api/auth/login/route.ts` qui valide les identifiants et crée un cookie de session HttpOnly. »
- « Transforme la liste de produits en Client Component pour ajouter un filtre par catégorie, sans casser le rendu serveur ni introduire de warning d’hydratation. »
- « Écris un test Vitest pour la fonction `formatPrice` de `lib/format.ts` et mets à jour les tests existants si le contrat change. »
- « Corrige le warning d’hydratation sur la page d’accueil : identifie la différence entre le rendu serveur et le rendu client, puis propose une correction minimale. »
- « Refactorise l’appel à l’API météo dans un Server Component pour utiliser `fetch` avec `next: { revalidate: 60 }`, et supprime l’ancien `useEffect` du Client Component. »

Après chaque réponse, lancez la commande concernée (`npm run lint`, `npm run test`, `npm run build`) et lisez le diff avec `git diff`. N’acceptez pas une modification qui passe les tests mais casse la frontière serveur/client.

## Tâches typiques et pièges à surveiller

Claude Code gère bien les tâches structurées de Next.js : créer un Route Handler, convertir un composant en Client Component, extraire une Server Action, ajouter des métadonnées, corriger des erreurs de typage ou écrire des tests. Il est aussi efficace pour refactoriser des appels `fetch` et mettre en place l’ISR.

Les pièges propres à Next.js sont précis :

- **Frontière serveur/client** : l’agent peut importer un module serveur dans un Client Component, ou ajouter `"use client"` plus haut que nécessaire, transformant toute une sous-arborescence en client.
- **Hydratation** : une valeur aléatoire, une date ou un accès au localStorage dans le rendu initial provoque des warnings ; l’agent peut les créer en voulant ajouter de l’interactivité.
- **Cache et rendu dynamique** : l’ajout d’un `fetch` sans option peut rendre une page statique de façon inattendue, ou l’inverse ; vérifiez toujours l’impact sur le build.
- **Route Handlers et secrets** : l’agent peut laisser des clés d’API dans du code client ou oublier de valider les entrées ; relisez attentivement tout ce qui touche à `app/api/`.
- **Tests insuffisants** : il peut modifier un composant sans mettre à jour le test associé ; exigez toujours l’exécution de la suite.

## Tests et vérification avec l’agent

Sur un projet Next.js, la vérification ne se limite pas aux tests unitaires : le build détecte les erreurs de frontière, le lint valide les règles React et Next.js, et les tests de bout en bout couvrent les parcours réels. Faites exécuter ces commandes à l’agent après chaque modification significative.

| Commande | Ce qu’elle vérifie |
|---|---|
| `npm run lint` | Respect des règles ESLint, y compris les règles spécifiques à React et Next.js |
| `npm run test` | Tests unitaires et de composants avec Vitest ou Jest |
| `npm run test:e2e` | Parcours utilisateur avec Playwright, notamment l’hydratation et les interactions |
| `npm run build` | Compilation, typage, génération des pages statiques et détection des erreurs serveur/client |

Demandez à l’agent d’interpréter les échecs : donnez-lui le message d’erreur exact et le fichier concerné. Pour les tests Playwright, faites-lui lancer un seul scénario avant la suite complète. Une fois les tests verts, relisez le diff final pour vérifier que les changements correspondent bien à l’intention initiale.

## Lancer plusieurs agents dans un projet Next.js avec AgentVera

Quand un chantier Next.js devient trop large pour un seul agent, l’application de bureau AgentVera exécute plusieurs agents Claude Code côte à côte, chacun dans son propre worktree Git. Ils modifient le même dépôt sans écraser les fichiers des autres. La revue de code automatique, déclenchée à la fin d’un tour, signale les problèmes avec des liens vers fichier:ligne, ce qui aide à repérer une mauvaise frontière serveur/client. Les checkpoints permettent d’annuler un tour en un clic et de rejouer la session, tandis que les budgets de jetons évitent qu’un agent dépasse la limite. Pour en savoir plus, voir [Lancer plusieurs agents Claude Code en parallèle](/fr/blog/run-multiple-claude-code-agents/).

## Pour conclure

Claude Code devient un vrai levier sur un projet Next.js quand le CLAUDE.md est à jour, que les commandes de vérification sont systématiques et que le travail est découpé en petites étapes. Surveillez en priorité la frontière entre serveur et client, la génération du build et les tests de bout en bout. Avec cette discipline, l’agent produit des modifications propres et faciles à relire.

## Questions fréquentes

**Comment configurer CLAUDE.md pour un projet Next.js ?** Placez un fichier CLAUDE.md à la racine du projet avec les commandes npm run dev, npm run build, npm run lint et npm run test, ainsi que les conventions de dossiers. Ajoutez des règles explicites pour les Server et Client Components, les Route Handlers et les variables d’environnement.

**Claude Code peut-il gérer les composants serveur et client de Next.js ?** Oui, à condition de documenter la frontière dans le CLAUDE.md. L’agent peut générer des Server Components, des Client Components et des Route Handlers, mais il faut vérifier qu’il n’importe pas de code serveur dans un composant client ou n’utilise pas de hooks dans un composant serveur.

**Comment tester les changements générés par Claude Code dans un projet Next.js ?** Demandez à l’agent d’exécuter npm run lint, npm run test et npm run build après chaque modification. Pour les parcours utilisateur, lancez aussi npm run test:e2e avec Playwright ; relisez toujours le diff avant d’accepter.

**Peut-on lancer plusieurs agents Claude Code sur un même projet Next.js ?** Oui, en utilisant des worktrees Git distincts pour isoler les modifications de chaque agent, puis en les fusionnant. Des outils comme AgentVera facilitent cette exécution parallèle avec revue de code automatique et checkpoints.

---

**À propos d’AgentVera.** AgentVera est une app de bureau pour macOS, Windows et Linux, développée par Solviera Teknoloji. Elle exécute 18 agents de code IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) côte à côte, par projet, dans de vrais terminaux avec les installations et connexions CLI de l’utilisateur. L’offre gratuite inclut des agents illimités. Télécharger: https://agentvera.dev/fr/download/ · Tarifs: https://agentvera.dev/fr/pricing/