Utiliser Gemini CLI sur un projet Next.js : guide pratique

Gemini CLI s’utilise dans un projet Next.js en lançant simplement gemini à la racine du dépôt. L’agent lit le contexte du projet, propose des modifications et exécute les commandes nécessaires. Ce guide explique comment le configurer et l’utiliser efficacement sur une codebase Next.js, App Router ou Pages Router ; pour une vue d’ensemble de l’outil, voir Gemini CLI.

Pourquoi Gemini CLI convient au travail sur Next.js

Gemini CLI fonctionne directement dans le terminal, là où vivent déjà les commandes de votre projet Next.js : installation, dev server, lint, tests et build. Il peut donc vérifier ses propres modifications avec pnpm build ou npm run lint au lieu de se contenter de générer du code sans retour. Pour Next.js, l’agent exploite les informations présentes dans le code : directives 'use client', fichiers route.ts, conventions de dossiers App Router, configuration next.config.*, et typage TypeScript. Cela lui permet de distinguer le code serveur du code client, de respecter les règles d’import et de produire des modifications cohérentes avec l’architecture existante. Comme il lit le fichier GEMINI.md, vous pouvez y encoder les choix spécifiques au projet : App Router ou Pages Router, emplacement des composants, commandes de test, et pièges à éviter. L’agent devient ainsi un pair programmeur qui suit vos conventions au lieu d’appliquer des patterns génériques.

Préparer le projet pour l’agent

La première étape consiste à créer un fichier GEMINI.md à la racine du dépôt. Gemini CLI le charge automatiquement comme instructions projet. Pour un projet Next.js, ce fichier doit rester court mais précis : commandes, arborescence, règles de composants serveur/client et contraintes de build. Voici un exemple réaliste pour un projet App Router avec Vitest et Playwright.

# GEMINI.md

## Commandes
- Installation : `pnpm install`
- Développement : `pnpm dev`
- Build : `pnpm build`
- Lint : `pnpm lint`
- Tests unitaires : `pnpm test` (Vitest)
- Tests E2E : `pnpm test:e2e` (Playwright)

## Conventions Next.js
- App Router dans `src/app` ; ne pas créer de dossier `src/pages` sauf demande explicite
- Composants serveur par défaut ; n’ajouter `'use client'` que lorsqu’un état ou un événement navigateur est nécessaire
- Route handlers dans `src/app/api/**/route.ts`
- Logique de données dans `src/lib`, composants réutilisables dans `src/components`
- Utiliser les Server Actions pour les mutations ; ne pas créer d’API REST interne sauf besoin réel
- Ne pas importer de module serveur (base de données, secrets) dans un composant client

## Règles pour l’agent
- Ne pas modifier `next.config.*`, `tsconfig.json` ou les dépendances sans demander
- Vérifier les imports entre serveur et client après chaque modification
- Toujours lancer `pnpm lint` et les tests liés avant de considérer une tâche terminée
- Ne pas supprimer les commentaires `// TODO` existants

Ce fichier doit évoluer avec le projet : si vous adoptez un nouveau runner de test ou un alias d’import, mettez-le à jour. Pour aller plus loin, consultez le guide Utiliser Gemini CLI : le guide pas à pas.

Une boucle de travail fiable

Pour éviter que l’agent ne parte dans une refonte massive, travaillez par petites étapes : décrivez la tâche, laissez l’agent proposer un plan, validez-le, puis demandez-lui d’implémenter. Après chaque modification, exécutez les tests et relisez le diff avant de passer à la suite. Exemples de prompts adaptés à Next.js :

• Ajoute une route handler GET /api/posts qui renvoie les articles triés par date, avec un typage TypeScript strict et une gestion d’erreur 404.
• Refactore la logique de fetch de ce composant serveur dans src/lib/posts.ts sans changer le comportement.
• Ce composant client n’a pas d’état ni d’effet ; transforme-le en composant serveur et supprime 'use client' si possible.
• Écris un test Playwright qui vérifie la soumission du formulaire de contact et l’apparition du message de confirmation.
• Corrige l’erreur d’hydratation sur la page d’accueil en comparant le rendu serveur et client, puis propose une correction minimale.

Demandez toujours à l’agent de résumer ce qu’il va modifier avant d’écrire du code, puis de lister les commandes de vérification qu’il compte lancer. Relisez ensuite le git diff en portant attention aux fichiers de config et aux modifications de dépendances. Cette discipline de revue s’inscrit dans une démarche de pair programming avec l’IA.

Tâches typiques et pièges à surveiller

Gemini CLI gère bien la génération de route handlers, la conversion entre composants serveur et client, l’ajout de métadonnées, la correction d’erreurs TypeScript, ou l’écriture de tests. En revanche, certains pièges spécifiques à Next.js reviennent souvent, et il faut les garder à l’œil.

Dans un projet App Router, l’agent peut aussi proposer de modifier next.config.* ou de réorganiser les dossiers : cela casse parfois le routing. Refusez ces changements s’ils ne sont pas nécessaires, et demandez une explication précise avant d’accepter. De même, une modification dans un Server Component peut introduire une erreur de build si elle importe une bibliothèque uniquement cliente ; faites toujours tourner pnpm build en fin de session.

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

Utilisez l’agent pour écrire les tests, pas pour les exécuter à votre place sans contrôle. Pour les tests unitaires, demandez-lui de couvrir les fonctions de src/lib avec Vitest ou Jest, en particulier les utilitaires de formatage de date et les parseurs de données. Pour les parcours utilisateur, Playwright est plus adapté : demandez des scénarios qui ciblent le rendu final, pas les détails d’implémentation. Exemple de prompt : « Ajoute un test Vitest pour src/lib/posts.ts qui vérifie le tri par date et le cas d’une liste vide. » ou « Rédige un test Playwright pour la page /dashboard qui vérifie l’affichage des données après connexion simulée. » Après chaque session, lancez vous-même pnpm lint, pnpm test et pnpm build. Si l’agent a modifié des Server Actions ou des route handlers, testez aussi les appels réels avec un client HTTP. Enfin, relisez le diff avec git diff --check pour repérer les espaces ou les fins de ligne incohérentes.

Faire tourner plusieurs agents sur un projet Next.js avec AgentVera

Sur une grosse codebase Next.js, plusieurs agents Gemini CLI peuvent travailler en parallèle si chacun utilise son propre git worktree, ce qui évite les conflits d’écriture dans src/app ou src/components. AgentVera lance les vrais outils en ligne de commande dans des terminaux séparés, puis, quand un agent a terminé, un second modèle relit son code et signale les problèmes avec des liens fichier:ligne, utile pour repérer une erreur d’hydratation ou un import serveur/client incorrect. Les checkpoints de chaque tour permettent de revenir en arrière si un lot de modifications casse le build Next.js.

En résumé

Gemini CLI devient un vrai accélérateur sur Next.js si vous lui donnez un GEMINI.md précis et si vous validez chaque étape par des tests et un build. Gardez la main sur les changements d’architecture, surtout autour de la frontière serveur/client et du cache. Avec une boucle de travail disciplinée, l’agent produit des modifications utiles sans déstabiliser votre application.