# Codex et Next.js : guide pratique pour l’agent de code

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

Guide pratique pour utiliser Codex sur un projet Next.js : AGENTS.md, boucle de travail, prompts utiles, pièges serveur/client et validation par les tests.

**En bref:**

- Codex travaille bien sur Next.js quand le projet décrit ses commandes et ses conventions dans AGENTS.md.
- Il faut découper les tâches en petits changements et vérifier le diff, les tests, le lint et le build avant de valider.
- Les pièges principaux sont la frontière serveur/client, les route handlers et le rendu dynamique, contrôlables par des revues ciblées.

Lancer [Codex](/fr/agents/codex/) dans un projet Next.js permet de déléguer l’implémentation de routes, de composants et de tests, à condition de le cadrer. Le point clé est de décrire le projet dans un fichier AGENTS.md et de ne jamais accepter un diff sans l’avoir relu et testé. Ce guide couvre le setup, une boucle de travail fiable, les pièges propres à Next.js et la vérification.

## Pourquoi Codex convient bien au travail sur Next.js

Next.js impose des conventions fortes : dossiers app/, fichiers page.tsx, layout.tsx, route.ts, directive 'use client'. Codex lit tout le dépôt et peut appliquer ces conventions de façon cohérente, là où un snippet ignore le contexte. Il est utile pour les transformations répétitives (ajouter loading.tsx et error.tsx, typer les props, convertir un composant client en Server Component) et pour générer des route handlers avec validation Zod. Il ne remplace pas la compréhension du modèle de rendu, mais accélère le travail mécanique.

## Mise en place du projet pour l’agent

Le premier levier est un AGENTS.md versionné à la racine. Il doit contenir les commandes exactes, les conventions de dossiers et les règles Next.js que l’agent ne doit pas deviner. Voici un exemple court :

```markdown
# AGENTS.md

## Commandes
- `pnpm dev` : serveur de développement
- `pnpm build` : build de production
- `pnpm lint` : ESLint
- `pnpm test:run` : exécution unique des tests Vitest
- `pnpm exec playwright test` : tests end-to-end

## Conventions du projet
- App Router dans `src/app/`, composants partagés dans `src/components/`.
- Tout composant est un Server Component par défaut. N'ajoute `'use client'` que si l'état, les effets ou les événements navigateur l'exigent.
- Les route handlers sont dans `src/app/api/.../route.ts` et renvoient des réponses JSON typées.
- Valide les données entrantes avec Zod dans les route handlers.
- Utilise TypeScript strict, pas de `any` sauf exception explicitement validée.

## Règles pour l'agent
- Ne modifie pas `next.config.*` sans demande explicite.
- Ne change pas les versions dans `package.json` sans validation.
- Ajoute un test unitaire pour toute nouvelle fonction de transformation.
- Vérifie `pnpm lint` et `pnpm test:run` avant de terminer.
```

Ce fichier transforme les demandes vagues en exécutions cohérentes. Si vous découvrez la CLI, le [guide pas à pas](/fr/blog/how-to-use-codex-cli/) détaille la configuration initiale.

## Une boucle de travail fiable

Ne demandez jamais un gros refactor d’un coup. La boucle qui fonctionne est : définir un objectif précis, laisser Codex proposer un premier diff, relire `git diff`, lancer les tests et le lint, puis demander des corrections ciblées. Exemples de prompts adaptés :

- « Ajoute une route `POST /api/contact` dans `src/app/api/contact/route.ts`. Valide le corps avec Zod, renvoie 400 sur erreur et 201 avec l’objet créé. Ajoute un test Vitest pour le handler. »
- « Le composant `src/components/DatePicker.tsx` provoque un mismatch d’hydratation. Analyse la cause, corrige sans désactiver l’hydratation, puis lance `pnpm lint` et les tests liés. »
- « `src/app/dashboard/page.tsx` utilise `useEffect` seulement pour charger des données. Transforme-le en Server Component asynchrone, ajoute un `loading.tsx`, et vérifie que les props restent typées. »
- « Écris un test Playwright pour le flux connexion → tableau de bord avec un utilisateur de test. Utilise les rôles accessibles déjà présents et ajoute le test dans `tests/e2e/login.spec.ts`. »
- « Le formulaire `ContactForm` gère les erreurs avec plusieurs `useState`. Refactore-le avec `useActionState` si pertinent, conserve l’accessibilité et ajoute un test du comportement de soumission. »

Après chaque étape, relisez le diff avec `git diff --stat` puis `git diff`. Exécutez vous-même `pnpm test:run` et `pnpm build` avant de valider. Codex peut exécuter les commandes, mais valider le résultat reste votre responsabilité.

## Tâches typiques et points de vigilance

Codex s’en sort bien pour créer ou modifier des route handlers, générer des pages serveur avec fetch, ajouter des pages de chargement et d’erreur, et produire des tests unitaires ou E2E. En revanche, surveillez les points suivants, propres à Next.js :

| Tâche | Invite utile | Point de vigilance |
|-------|--------------|--------------------|
| Route handler | « Crée une route `GET /api/products` qui filtre par catégorie et renvoie un JSON paginé. » | Ne pas oublier `export const dynamic` si la réponse dépend de la requête ; éviter les imports serveur dans le client. |
| Composant client | « Transforme ce composant pour utiliser `useState` sans perdre le rendu serveur. » | Codex peut ajouter `'use client'` à une page entière alors qu’un sous-composant suffit. |
| Fetch de données | « Charge les produits dans un Server Component et gère l’état vide et l’erreur. » | Ne pas await `params` ou `searchParams` dans un composant client, et penser à Suspense. |
| Métadonnées | « Ajoute `generateMetadata` pour cette page dynamique. » | Vérifier les types `Metadata` et ne pas lire les en-têtes dans un composant client. |

Autres pièges fréquents : importer un module `server-only` dans un composant client, utiliser `cookies()` ou `headers()` sans `await`, ou modifier le comportement de cache sans comprendre les conséquences sur le build. Demandez toujours un petit diff et vérifiez les imports.

## Test et vérification pour Next.js avec l’agent

Pour valider le travail de Codex, combinez trois niveaux : tests unitaires Vitest pour les fonctions et handlers, tests de composants avec React Testing Library si besoin, et Playwright pour les parcours critiques. Demandez à l’agent d’écrire les tests en même temps que le code, mais vérifiez que les assertions sont significatives. Un test qui vérifie seulement que le rendu ne lève pas d’erreur est insuffisant pour un formulaire.

Les commandes à exiger avant de terminer : `pnpm lint`, `pnpm test:run`, `pnpm exec playwright test` et surtout `pnpm build`. Le build Next.js révèle les erreurs de frontière serveur/client, les usages de Suspense manquants et les problèmes de génération statique. Si vous travaillez à plusieurs agents, la [revue de code IA](/fr/blog/ai-code-review/) aide à repérer ces erreurs structurelles avant qu’elles n’arrivent en CI.

## Exécuter plusieurs agents sur un projet Next.js avec AgentVera

Pour les gros refactors Next.js, plusieurs agents peuvent travailler en parallèle via AgentVera, chacun dans son propre worktree Git pour éviter les écrasements de fichiers. La revue de code automatique est précieuse sur Next.js, car elle repère les imports de code serveur dans un composant client ou un usage de `searchParams` sans Suspense. Les checkpoints permettent d’annuler une mauvaise passe en un clic, et les budgets de tokens empêchent un agent de dériver sur tout le projet. Voir aussi [workflow d’agents IA](/fr/blog/ai-agent-workflow-pipeline/) pour composer des équipes.

## En résumé

Codex devient un bon exécutant sur Next.js quand le projet est décrit dans AGENTS.md, que les tâches sont petites et que chaque diff passe par les tests, le lint et le build. Méfiez-vous surtout de la frontière client/serveur et du rendu dynamique. Une revue systématique transforme l’agent en accélérateur plutôt qu’en générateur de dette.

## Questions fréquentes

**Codex peut-il créer une route API Next.js complète ?** Oui, il peut générer un fichier route.ts avec validation Zod et gestion des erreurs. Il faut lui préciser les conventions du projet et vérifier le handler avec un test.

**Comment éviter que Codex casse la frontière entre composants serveur et client ?** Déclarez dans AGENTS.md que tout composant est un Server Component par défaut et que 'use client' ne s’ajoute que si nécessaire. Relisez systématiquement les imports après chaque diff.

**Codex peut-il écrire des tests Playwright pour mon application Next.js ?** Oui, donnez-lui les rôles accessibles et le parcours utilisateur à couvrir. Demandez-lui d’exécuter les tests localement avant de valider la modification.

**Faut-il laisser Codex modifier next.config.js ou package.json ?** Évitez par défaut. Demandez à Codex de proposer les changements sans les appliquer, puis validez-les manuellement, car ces fichiers ont un impact direct sur le build Next.js.

---

**À 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/