Construire une app Next.js avec Claude Code

Le problème : Next.js 16 prend du temps à configurer depuis zéro. L'App Router introduit des changements cassants à chaque version majeure, les params async te coincent dès le premier jour, et les données d'entraînement de Claude vieillissent plus vite que le framework ne sort de versions. Tu finis par corriger Claude plus qu'il ne t'aide.

La victoire rapide : Lance Claude Code depuis un projet create-next-app tout neuf et laisse AGENTS.md faire le briefing. Claude lit les docs Next.js 16 fournies avant de toucher au moindre fichier :

npx create-next-app@latest my-app --typescript --tailwind --app --turbopack
cd my-app
claude

Avant de commencer

Trois choses doivent être en place.

Node.js 20.9.0 ou plus récent. Next.js 16 a abandonné le support de Node 18. Vérifie ta version :

node --version

Claude Code installé globalement :

npm install -g @anthropic-ai/claude-code

Un abonnement Claude Pro ou Team. Claude Code utilise ton compte Anthropic. Le tier gratuit ne marche pas.

TypeScript 5.1+. Next.js 16 l'exige. Lancer create-next-app@latest avec --typescript installe la bonne version pour toi.

Git et un dépôt GitHub rendent le déploiement Vercel en une étape. Pas strictement obligatoire, mais la section déploiement suppose que tu as les deux.

Créer le projet

create-next-app@latest génère un projet Next.js 16 avec Turbopack, TypeScript et Tailwind CSS v4 déjà branchés. Turbopack est le bundler par défaut maintenant, il remplace Webpack. Le Fast Refresh tourne jusqu'à 10x plus vite que l'ancien setup, et les builds à froid sont 2 à 5x plus rapides.

Lance la génération :

npx create-next-app@latest my-app --typescript --tailwind --app --turbopack
cd my-app

Deux fichiers à la racine du projet comptent pour Claude Code : AGENTS.md et CLAUDE.md. La version canary génère les deux automatiquement. Sur la version stable, tu devras peut-être les créer à la main.

S'ils manquent, crée AGENTS.md à la racine du projet avec une seule ligne pour charger les docs fournies :

node_modules/next/dist/docs/

Ensuite, crée un CLAUDE.md qui l'importe. La section suivante couvre ce qu'il faut ajouter en plus.

Pourquoi AGENTS.md compte : il pointe Claude vers la documentation fournie dans node_modules/next/dist/docs/. Claude lit ces docs au démarrage de la session au lieu de se fier à ses données d'entraînement. Dans les benchmarks Next.js, les agents avec les docs fournies atteignent 100 % sur les évals Next.js. Les agents sans elles ratent les changements d'API cassants introduits dans Next.js 16.

CLAUDE.md utilise la syntaxe d'import @AGENTS.md pour tirer ces règles sans les recopier :

@AGENTS.md

Claude lit les deux fichiers avant d'écrire la moindre ligne de code.

Personnaliser CLAUDE.md

Le CLAUDE.md auto-généré couvre les conventions Next.js. Ajoute la stack de ton projet par-dessus :

@AGENTS.md

## Stack

- Next.js 16 with App Router (TypeScript)
- Tailwind CSS v4 with shadcn/ui components
- PostgreSQL via Supabase (use server-side client for Server Components)
- oRPC with Zod for type-safe API routes

## File Conventions

- Server Components by default. Add "use client" only when you need browser APIs or interactivity.
- Route handlers go in app/api/[route]/route.ts
- Database queries run in lib/db.ts, never inline in components

## Commands

- Dev server: npm run dev
- Type check: npx tsc --noEmit
- Build: npm run build

## Proxy

- Middleware logic lives in proxy.ts, not middleware.ts (Next.js 16)

La note sur proxy.ts vaut la peine d'être ajoutée explicitement. Claude se rabat encore sur middleware.ts par défaut. Une ligne dans CLAUDE.md évite cette erreur à chaque fois.

Garde CLAUDE.md précis. Les instructions vagues (« écris du code propre ») ne changent rien au comportement de Claude. Les chemins de fichiers concrets, les commandes et les conventions de nommage, eux, font la différence.

Comprendre l'App Router avec Claude Code

L'App Router sépare les composants en deux catégories. Les Server Components tournent sur le serveur et peuvent récupérer des données directement. Les Client Components tournent dans le navigateur et gèrent l'interactivité.

Claude lit les règles de l'App Router depuis AGENTS.md et place la frontière au bon endroit sans que tu aies à le préciser. Le défaut, c'est Server Component. Tu ajoutes "use client" en haut d'un fichier seulement quand tu as besoin de useState, useEffect, d'API navigateur ou de gestionnaires d'événements.

Next.js 16 embarque React 19.2. Ça inclut les View Transitions, useEffectEvent, et le composant <Activity />. C'est assez récent pour que les données d'entraînement de Claude ne les couvrent peut-être pas bien. Pour tout ce qui utilise les API React 19, ajoute des exemples explicites à CLAUDE.md ou décris ce que tu veux en termes de comportement plutôt que de noms d'API.

Demande à Claude de construire une page tableau de bord et il place la récupération de données dans le Server Component et fait redescendre les résultats en props vers les parties interactives :

claude "build a /dashboard page that fetches user stats from the database and shows them in a summary card with a refresh button"

Claude génère le Server Component en haut de l'arbre, crée un Client Component pour le bouton de rafraîchissement, et les relie ensemble. Tu ne précises pas quel composant est lequel. Claude lit les règles depuis AGENTS.md et trouve tout seul.

Construire une fonctionnalité de bout en bout

Voici un parcours concret : une page de profil utilisateur avec des données côté serveur et un formulaire d'édition côté client.

Commence en plan mode avant d'écrire la moindre ligne de code :

claude --plan "add a /profile page with server-fetched user data and an editable display name form"

Claude cartographie les fichiers dont il a besoin : un composant de page, une Server Action pour la soumission du formulaire, un helper de requête base de données, et un Client Component pour le formulaire. Tu relis le plan. Puis il construit.

Le fichier de la page utilise les params async comme l'exige Next.js 16 :

// app/profile/[id]/page.tsx
import { ProfileForm } from "@/components/profile-form";
import { getUser } from "@/lib/db";

interface PageProps {
  params: Promise<{ id: string }>;
}

export default async function ProfilePage({ params }: PageProps) {
  const { id } = await params;
  const user = await getUser(id);

  return (
    <main className="max-w-lg mx-auto py-12">
      <h1 className="text-2xl font-bold mb-6">Your Profile</h1>
      <ProfileForm user={user} />
    </main>
  );
}

L'objet params est une Promise dans Next.js 16. await params est obligatoire. Claude gère ça correctement quand AGENTS.md est en place. Sans lui, Claude écrit l'ancien pattern synchrone et le build échoue avec une erreur de type.

La Server Action du formulaire vit dans un fichier séparé :

// app/profile/actions.ts
"use server";

import { updateUser } from "@/lib/db";

export async function updateDisplayName(userId: string, name: string) {
  await updateUser(userId, { displayName: name });
}

Les pièges de Next.js 16 que Claude gère

Quelques changements cassants par rapport à Next.js 14/15 coincent Claude sans AGENTS.md. Avec lui, ça marche correctement.

Les Cache Components et la directive "use cache". Next.js 16 remplace experimental.dynamicIO par la directive "use cache". Ajoute-la en haut de tout composant ou fonction que tu veux mettre en cache :

// app/stats/page.tsx
"use cache";

import { getStats } from "@/lib/db";

export default async function StatsPage() {
  const stats = await getStats();
  return <pre>{JSON.stringify(stats, null, 2)}</pre>;
}

Claude génère la directive correctement pour les nouveaux fichiers. Pour du code migré depuis Next.js 15, dis-le explicitement à Claude : « migrate this file from experimental.dynamicIO to the use cache directive. »

Turbopack par défaut. npm run dev utilise Turbopack. La config Webpack dans next.config.ts est en grande partie sans objet, sauf si tu as des loaders custom. Claude le sait grâce à AGENTS.md et ne génère pas de config spécifique à Webpack.

Le MCP DevTools de Next.js

Next.js 16 embarque un serveur Model Context Protocol pour le débogage assisté par IA. Il donne à Claude le contexte de routage, des logs navigateur et serveur unifiés, et un accès automatique aux traces de pile d'erreurs dans la session.

Connecte-le dans tes réglages Claude Code en pointant vers le serveur MCP fourni :

{
  "mcpServers": {
    "nextjs-devtools": {
      "command": "node",
      "args": ["node_modules/next/dist/mcp/index.js"]
    }
  }
}

Avec le MCP DevTools actif, Claude peut diagnostiquer un souci de cache sans que tu copies-colles des logs. Demande à Claude pourquoi une route sert des données périmées, et il lit les logs serveur directement, retrace la clé de cache, et te dit quel appel revalidateTag() ajouter.

Sans ça, Claude diagnostique à partir du code seul. Avec, Claude diagnostique à partir de données d'exécution en direct. Cette différence compte surtout quand un bug n'apparaît qu'en production.

Le MCP DevTools donne aussi à Claude accès à l'arbre de routage à l'exécution. Si tu demandes à Claude d'ajouter une nouvelle route et qu'elle entre en conflit avec un segment dynamique existant, le MCP le signale tout de suite au lieu de te laisser le découvrir à l'exécution. Pour les setups App Router complexes avec des layouts imbriqués, des routes parallèles et des routes interceptrices, ce contexte vaut la peine d'être présent à chaque session.

Les contrôles qualité avant de livrer

Deux commandes tournent avant chaque commit.

Vérification de types sans aucune erreur :

npx tsc --noEmit

Build de production propre avec Turbopack :

npm run build

Demande à Claude de lancer les deux après tout changement significatif :

claude "run tsc --noEmit and fix any type errors, then confirm the build passes"

Claude lit la sortie d'erreur, corrige les soucis, et relance la vérification. C'est là que les erreurs de params async, les directives "use cache" manquantes et les Server Actions mal configurées remontent avant d'atteindre la production.

Zéro erreur de type et un build propre sont la barre minimale pour livrer. Pas une suggestion. La vérification tourne à chaque fois.

Déployer sur Vercel

Vercel détecte Next.js 16 automatiquement. Deux options pour déployer.

Intégration Git : pousse sur ta branche main et Vercel la build. Règle les variables d'environnement dans le dashboard Vercel sous Settings > Environment Variables avant le premier déploiement. Vercel lit la sortie de build et déduit quelles routes sont statiques, dynamiques ou en cache.

Déploiement CLI : règle d'abord tes variables d'environnement, puis pousse :

npx vercel env add DATABASE_URL production
npx vercel env add NEXT_PUBLIC_SUPABASE_URL production
npx vercel --prod

Les logs de build dans Next.js 16 montrent la stratégie de rendu de chaque route à côté de sa taille de sortie. Les routes statiques s'affichent en vert, les routes dynamiques en jaune. Ça te dit exactement ce qui est pré-rendu au moment du build et ce qui tourne à chaque requête.

Si une route que tu attendais statique s'affiche comme dynamique, le MCP DevTools aide à diagnostiquer pourquoi. Souvent, c'est une récupération de données non mise en cache qui force la route à tourner au moment de la requête.

À quoi ressemble un pipeline orchestré

Une seule session Claude Code gère bien des fonctionnalités. Un pipeline coordonné gère des produits.

Build This Now fait tourner 32 agents spécialisés à travers la planification, la construction, l'évaluation et les tests avant qu'une fonctionnalité ne sorte. Trois agents de planification travaillent en parallèle avant qu'aucune ligne de code ne soit écrite. Après le build, des évaluateurs adversariaux relisent la sortie et les builders corrigent ce qu'ils signalent. Deux agents de test tournent en parallèle, un avec un vrai navigateur. Chaque fonctionnalité sort du pipeline avec zéro erreur de type, zéro erreur de lint, et un build Turbopack propre.

La vérification npx tsc --noEmit à la fin de ce guide, c'est ce dernier contrôle. Dans un pipeline orchestré, elle tourne automatiquement après chaque passation entre agents.

Mets en place AGENTS.md, écris un CLAUDE.md précis, utilise le plan mode avant les fonctionnalités complexes, et lance les contrôles qualité avant chaque commit. Ces quatre habitudes couvrent l'essentiel de ce qui rend un workflow Claude Code avec Next.js 16 fiable. Le framework change. Le process, non.