Tu as un projet Next.js qui tourne en local. Tu veux qu'il soit en ligne, avec un vrai domaine, sous HTTPS, avec des déploiements automatiques à chaque push. Voici le chemin précis pour y arriver avec Claude Code comme agent CLI, sans deviner les commandes ni tâtonner sur le dashboard Vercel. Si tu veux le contexte plus large (du brief jusqu'au site en ligne), commence par le guide complet pour apprendre Claude, sinon enchaîne directement.
Pourquoi Vercel quand on code avec Claude
Quand Claude Code génère un projet Next.js, il génère par défaut une structure que Vercel reconnaît sans configuration : App Router, route handlers, middleware, images optimisées. Tu importes le repo, Vercel détecte next dans package.json, le build passe. Dans la pratique, sur un projet Next.js fraîchement initialisé par Claude, tu ne touches pas à next.config.js avant le premier déploiement.
L'autre raison, c'est le modèle de preview deployments : chaque branche Git devient une URL publique. Tu peux demander à Claude de pousser une modification et tu obtiens un lien à ouvrir avant de merger. Netlify et Cloudflare Pages font la même chose, avec des compromis différents sur le pricing et les fonctions serverless. Pour un projet Next.js piloté par Claude Code, Vercel reste le chemin le plus court, c'est l'éditeur du framework.
Prérequis : ce que ton projet doit avoir avant de déployer
Quatre choses, dans l'ordre :
- Un repo Git initialisé localement (GitHub, GitLab ou Bitbucket côté distant).
- Un
package.jsonavec au minimum les scriptsbuild(souventnext build) etstart. - Un
.gitignorequi exclutnode_modules,.next, et surtout.envet.env.local. - Un compte Vercel connecté à ton GitHub.
Plutôt que de vérifier ça à la main, demande-le à Claude Code. Le prompt qui marche bien :
Vérifie que ce projet est prêt pour un déploiement Vercel.
Regarde package.json (scripts build et start), .gitignore
(node_modules, .next, .env*), et liste tous les fichiers
qui contiennent des secrets ou des clés API. Ne commit rien,
juste un rapport.Claude lit l'arborescence, ouvre les fichiers concernés et te renvoie un diagnostic du type "package.json OK, .gitignore manque .env.local, j'ai trouvé une clé Stripe en clair dans lib/payment.ts ligne 3". À ce stade tu sais exactement quoi corriger avant de pousser quoi que ce soit en ligne.
Étape 1 : pousser le projet sur GitHub avec Claude Code
Une fois le projet propre, demande à Claude de créer le repo et de pousser. Il enchaîne les commandes lui-même :
git init
git add .
git commit -m "Initial commit"
gh repo create mon-projet --private --source=. --pushLe prompt qui fonctionne bien :
Initialise un repo GitHub privé pour ce projet via gh CLI.
Avant le premier commit, fais un git status et confirme
qu'aucun fichier .env ou clé API ne va partir. Puis push.Le piège classique, c'est le .env.local qui se retrouve dans le premier commit parce que le .gitignore a été ajouté trop tard. Si ça arrive, ne te contente pas de supprimer le fichier dans un commit suivant : l'historique Git le garde. Demande à Claude de réécrire l'historique avec git filter-repo ou, plus simple, refais un repo propre. Et révoque toutes les clés qui ont fuité, même 30 secondes en public suffisent à se faire scanner.
Étape 2 : importer le projet dans Vercel
Sur vercel.com, clique sur Add New Project, sélectionne le repo que Claude vient de créer. Vercel détecte Next.js, propose les build settings par défaut (build command next build, output directory .next, install command npm install). Tu ne touches à rien.
Deux exceptions à connaître. Si tu es en monorepo (Turborepo, pnpm workspaces), précise le root directory dans Settings, sinon Vercel cherche le package.json à la racine et plante. Si tu utilises pnpm ou bun, Vercel le détecte via le lockfile, mais vérifie que le lockfile est bien commité, c'est la première source de builds qui marchent en local et cassent en production.
Lance le build. Le premier prend en général entre 60 et 120 secondes. Si ça passe, tu as déjà une URL en .vercel.app qui sert ton site en HTTPS.
Étape 3 : gérer les variables d'environnement
C'est la section qui fait échouer la moitié des premiers déploiements. Vercel sépare les variables en trois environnements : Production, Preview, Development. Une variable définie uniquement en Development n'existe pas pour ton site en ligne.
Le flux propre :
- Dans Project Settings > Environment Variables, ajoute chaque clé une par une.
- Coche Production et Preview pour les variables qui doivent exister partout (clés Stripe en mode test pour Preview, mode live pour Production).
- Préfixe par
NEXT_PUBLIC_uniquement ce qui doit être lisible côté client (clé publique Stripe, URL d'API publique). Tout ce qui estNEXT_PUBLIC_est bundlé dans le JavaScript envoyé au navigateur, donc lisible par n'importe qui.
Le prompt utile à donner à Claude :
Liste toutes les variables d'environnement utilisées dans ce code.
Pour chacune, indique : son rôle, si elle doit être exposée
côté client (préfixe NEXT_PUBLIC_) ou rester serveur, et
un exemple de valeur. Format tableau Markdown.Tu copies la table dans Vercel, tu remplis les vraies valeurs, tu redéploie. Si tu changes une variable existante, il faut redéclencher un build manuellement (Deployments > ... > Redeploy), Vercel ne le fait pas tout seul.
Étape 4 : brancher un domaine custom
Tu achètes le domaine où tu veux (OVH, Namecheap, Cloudflare Registrar, Gandi). Côté Vercel, va dans Project Settings > Domains, ajoute tondomaine.com. Vercel te donne deux options de configuration DNS selon ce que tu veux faire :
| Cas | Type de record | Valeur |
|---|---|---|
| apex (tondomaine.com) | A | 76.76.21.21 |
| sous-domaine (www, app) | CNAME | cname.vercel-dns.com |
Tu vas dans le panneau DNS de ton registrar, tu ajoutes le record, tu sauvegardes. Vercel détecte la propagation et bascule automatiquement. Compte 15 minutes dans 80% des cas, parfois jusqu'à 24h selon le registrar et les caches DNS de ton FAI. Le certificat SSL (Let's Encrypt) est généré automatiquement dès que le DNS pointe correctement, tu n'as rien à faire.
Si tu veux à la fois tondomaine.com et www.tondomaine.com, ajoute les deux dans Vercel et choisis lequel redirige vers l'autre (en général on garde l'apex et on redirige www, ou l'inverse, peu importe tant que c'est cohérent).
Les 5 erreurs de build qui bloquent ton premier déploiement
Ce sont presque toujours les mêmes. Pour chacune, le message typique et le prompt à coller à Claude.
| Erreur | Message typique | Prompt à Claude |
|---|---|---|
| Variable d'env manquante | Error: STRIPE_SECRET_KEY is not defined | "Liste toutes les env vars du code et compare avec celles que j'ai définies sur Vercel (je colle la liste)." |
| Import case-sensitive | Module not found: Can't resolve './Header' alors que le fichier s'appelle header.tsx | "Trouve tous les imports où la casse du fichier ne match pas la casse de l'import. macOS s'en fout, Linux Vercel non." |
| Lockfile pas commité | npm ERR! Cannot find module 'xxx' au build | "Vérifie que package-lock.json (ou pnpm-lock.yaml) est bien dans le repo et à jour avec package.json." |
| Erreur TypeScript | Type error: Property 'x' does not exist on type 'y' | "Lance npx tsc --noEmit et corrige toutes les erreurs. Ne mets pas ignoreBuildErrors à true dans next.config." |
| Function trop lourde | Serverless Function has exceeded the unzipped maximum size of 250 MB | "Trouve quelle dépendance fait exploser le bundle de cette route. Suggère un import dynamique ou un déplacement vers edge runtime." |
L'import case-sensitive est de loin le plus vicieux : tout marche en local sur Mac, le push passe, le build crashe sur les runners Linux. À ce stade tu lis les logs de build Vercel, tu identifies la ligne, tu colles à Claude. Pour aller plus loin sur ce type de pipeline, regarde aussi comment configurer Claude pour ton workflow quotidien, c'est là que tu calibres les prompts récurrents.
Workflow continu : push, preview, production
Une fois le premier déploiement passé, le reste devient simple. Chaque push sur main déclenche un build de production. Chaque push sur une autre branche génère une URL preview unique du type mon-projet-git-feature-xyz.vercel.app. Cette URL a accès aux variables d'env taggées Preview, donc tu peux tester contre une base de données de staging sans risquer la prod.
Le workflow avec Claude ressemble à ça :
git checkout -b feature/nouvelle-landing
# tu demandes à Claude de modifier des fichiers
git add . && git commit -m "Refonte hero"
git push -u origin feature/nouvelle-landingVercel poste un commentaire sur la PR avec l'URL preview. Tu ouvres, tu vérifies. Si c'est bon, tu merges sur main, la prod se met à jour dans la minute. Si tu veux bypasser Git pour un déploiement ponctuel, npx vercel --prod depuis ton dossier local fait le boulot, mais évite de prendre cette habitude, tu perds la traçabilité Git.
Ce modèle marche aussi très bien quand tu construis une landing page avec Claude ou quand tu testes une variation A/B : une branche par variante, deux URLs preview, tu choisis. Pour le détail des outils sur cette stack, va voir la fiche outil Vercel et Next.js.
Et maintenant
Tu as un projet en ligne, un domaine, des previews à chaque branche, des variables d'env séparées entre prod et staging. Le prochain palier, c'est de transformer ce setup en routine : un prompt système pour Claude Code qui rappelle tes conventions (TypeScript strict, pas de any, vars d'env documentées), un checklist avant chaque merge, un workflow CI qui lance les tests avant que Vercel ne build. Si tu veux structurer tout ça dans une pratique quotidienne plutôt que de tâtonner projet par projet, Maîtriser Claude au quotidien couvre exactement ce passage, du bricolage qui marche à un workflow que tu peux répéter sur dix sites.