Tu as un site qui tourne en local, Claude t'a aidé à le coder, et maintenant il faut le mettre en ligne. Vercel est le chemin le plus court pour un projet Next.js, Astro ou Vite : build auto à chaque push Git, SSL gratuit, previews par pull request. Ce guide va du repo local au domaine custom, avec les pièges concrets et comment faire bosser Claude Code au terminal sur le déploiement lui-même. Si tu veux d'abord le contexte complet sur apprendre à utiliser Claude en entrepreneur, cette ressource couvre l'amont. Ici on reste sur une seule chose : un site en ligne, qui marche.
Ce qu'il faut avoir avant de déployer
La checklist est courte mais chaque élément bloque le déploiement s'il manque.
- Un projet qui build en local avec
npm run build. Si cette commande renvoie une erreur sur ta machine, elle renverra la même sur Vercel. Pas d'exception. - Node 20 ou supérieur installé (
node --versionpour vérifier). - Git initialisé dans le dossier du projet.
- Un compte GitHub (gratuit).
- Un compte Vercel (le plan Hobby gratuit suffit pour commencer, limites largement au-dessus d'un site vitrine ou d'une app en démarrage).
- Claude Code installé si tu veux débugger les erreurs de build directement depuis le terminal. Le guide Claude Code débutant couvre l'installation.
Teste npm run build maintenant, avant tout le reste. La majorité des échecs de premier déploiement viennent de là, pas de Vercel.
Préparer le projet généré par Claude pour la production
Les projets craftés avec Claude, surtout via Artifacts ou copiés depuis une conversation, contiennent souvent des trucs qui passent en dev mais cassent en prod : clés d'API en dur dans les composants, chemins absolus vers ton bureau, dépendances importées mais pas listées dans package.json, scripts build ou start manquants.
Au lieu de les chercher à la main, lance ce prompt dans Claude Code à la racine du projet :
Audite ce projet pour un déploiement Vercel. Vérifie :
1. Toutes les clés d'API ou secrets en dur dans le code (à externaliser en variables d'environnement)
2. Les imports qui ne correspondent à aucune dépendance dans package.json
3. La présence des scripts "build" et "start" dans package.json
4. Les chemins de fichiers absolus ou relatifs au home local
5. La présence d'un .gitignore qui exclut node_modules et .env.local
Retourne la liste des problèmes trouvés avec le fichier concerné et la correction à appliquer.Claude va parcourir le projet, lister les corrections, et tu peux lui demander de les appliquer directement. Vérifie à chaque fois la diff avant d'accepter : pour un déploiement, mieux vaut une correction manuelle qu'une suppression trop zélée d'un fichier de config.
Pousser le projet sur GitHub
Vercel peut déployer depuis la CLI, mais passer par GitHub change tout : chaque git push redéploie automatiquement, chaque pull request génère une URL de preview, et Claude Code sait manipuler ce workflow nativement.
Commandes à lancer dans le dossier du projet :
git init
echo "node_modules\n.env.local\n.env\n.DS_Store\n.next\ndist" > .gitignore
git add .
git commit -m "Initial commit"Crée ensuite le repo sur GitHub (bouton New repository, ne coche aucune option d'initialisation puisque le repo local existe déjà), puis récupère l'URL et pousse :
git remote add origin https://github.com/ton-pseudo/ton-repo.git
git branch -M main
git push -u origin mainVérifie sur GitHub que ton .env.local n'apparaît nulle part. Si tu le vois dans la liste des fichiers, tu as un problème de .gitignore à régler avant d'aller plus loin : une clé API poussée en public, c'est une clé compromise, même si tu la supprimes dans le commit suivant.
Connecter le repo à Vercel et lancer le premier déploiement
Dans le dashboard Vercel : Add New puis Project, choisis Import en face de ton repo GitHub (autorise l'accès à ton compte GitHub si c'est la première fois). Vercel détecte seul le framework : Next.js, Astro, Vite, SvelteKit, les 30+ presets couvrent la quasi-totalité des cas.
Pour un projet Next.js standard, aucune configuration n'est nécessaire. Clique sur Deploy. Le premier build prend en général 1 à 3 minutes, affichés en direct dans la console. Si c'est un projet Astro ou Vite, vérifie juste que la Build Command (npm run build) et l'Output Directory (dist pour Vite, dist pour Astro) correspondent à ta config locale.
À la fin, Vercel te donne une URL en .vercel.app. Ouvre-la : si le site s'affiche, le socle est en place. Si ça affiche une page d'erreur, va directement à la section débug plus bas.
Pour creuser Next.js spécifiquement (routing, data fetching, API routes), le guide Vercel et Next.js pour entrepreneurs détaille les patterns utiles.
Gérer les variables d'environnement
C'est la section où les premiers déploiements cassent le plus souvent. Dans Vercel : Settings puis Environment Variables. Tu ajoutes chaque variable une par une, avec trois cases à cocher : Production, Preview, Development. Pour un site de prod simple, coche les trois.
Exemple pour un projet Next.js qui appelle l'API Anthropic côté serveur :
| Variable | Valeur | Où elle est lue |
|---|---|---|
| ANTHROPIC_API_KEY | sk-ant-... | Côté serveur uniquement (API routes, Server Components) |
| NEXT_PUBLIC_SITE_URL | https://tondomaine.com | Côté client ET serveur (le préfixe NEXT_PUBLIC_ expose au navigateur) |
| STRIPE_SECRET_KEY | sk_live_... | Côté serveur uniquement, jamais exposée au client |
La règle Next.js à retenir : toute variable qui doit être lue dans le code qui tourne dans le navigateur doit commencer par NEXT_PUBLIC_. Les autres restent côté serveur, invisibles aux visiteurs. Astro a sa propre convention (PUBLIC_), Vite aussi (VITE_) : consulte la doc du framework si tu n'es pas sur Next.
Piège classique : tu ajoutes une variable, tu rafraîchis le site, rien ne change. Vercel ne redéploie pas automatiquement quand tu modifies les variables. Il faut relancer un déploiement : onglet Deployments, les trois points sur le dernier déploiement, Redeploy. Ou pousser un commit vide : git commit --allow-empty -m "redeploy" && git push.
Débugger les erreurs de build avec Claude Code
Les erreurs typiques qui font planter un build Vercel : Module not found, erreurs de type TypeScript, variable d'environnement attendue mais absente, dépassement de la limite mémoire du build (rare sur Hobby, mais ça arrive sur un projet qui compile beaucoup).
Workflow qui marche à tous les coups :
- Ouvre le déploiement en échec dans Vercel, onglet Build Logs.
- Repère la première erreur rouge (pas la dernière : la suite n'est souvent qu'une cascade de la première).
- Copie le bloc d'erreur complet, avec le chemin du fichier et le numéro de ligne.
- Dans Claude Code à la racine du projet, colle :
Voici une erreur de build Vercel sur ce projet :
[coller le log ici]
Lis le fichier concerné, identifie la cause, propose un patch. Ne modifie rien avant que je valide.Claude Code va lire le fichier, souvent remonter aux imports ou à la config concernée, et proposer la correction. Tu valides, il écrit, tu commit et push. Vercel rebuild automatiquement.
Pour les erreurs TypeScript persistantes qui bloquent le build mais pas le dev, deux options : corriger proprement les types (ce que Claude fait bien) ou ajouter typescript: { ignoreBuildErrors: true } dans next.config.js en dépannage. La deuxième est un patch temporaire, à documenter dans un commentaire pour y revenir.
Brancher un domaine custom
Deux cas selon où tu as acheté ton domaine.
Domaine acheté chez un registrar externe (OVH, Namecheap, Gandi, Infomaniak). Dans Vercel : Settings, Domains, ajoute ton domaine (tondomaine.com). Vercel affiche les enregistrements DNS à créer, en général :
- Un enregistrement A pour la racine (
@) qui pointe vers76.76.21.21. - Un enregistrement CNAME pour
wwwqui pointe verscname.vercel-dns.com.
Va chez ton registrar, zone DNS, ajoute ces entrées exactement comme indiqué. La propagation prend de quelques minutes à quelques heures selon ton registrar. Vercel vérifie en continu : dès que les DNS pointent correctement, un petit badge vert apparaît et le certificat SSL est émis automatiquement via Let's Encrypt. Rien à configurer côté HTTPS.
Domaine acheté via Vercel. Tout est configuré automatiquement. Tu paies le domaine à Vercel au tarif en vigueur, et il est branché en quelques secondes.
Dans les deux cas, pense à configurer la redirection : la plupart du temps tu veux que www.tondomaine.com redirige vers tondomaine.com (ou l'inverse). Vercel propose le réglage dans l'écran des domaines, un clic.
Previews, rollbacks et workflow en continu
Une fois le site en ligne, le workflow prend sa vraie dimension. Chaque pull request GitHub génère une URL de preview Vercel unique, affichée en commentaire sur la PR. Pratique pour montrer une modif à un client avant de merger, ou pour tester visuellement un changement de design sans toucher à la prod.
Si une mise en prod casse quelque chose, l'onglet Deployments liste tous les déploiements passés. Clic sur un déploiement précédent qui marchait, Promote to Production, le site repasse sur cette version en quelques secondes. Pas besoin de revert dans Git dans l'urgence : tu rollback, tu corrige, tu redéploies tranquillement.
Workflow combiné avec Claude Code que je recommande pour une app en production :
- Nouvelle branche Git pour chaque chantier (
git checkout -b feature/nouveau-formulaire). - Claude Code fait les modifs sur la branche.
- Commit et push : Vercel génère la preview.
- Tu ouvres la preview, tu valides visuellement.
- Pull request vers
main, merge, déploiement en prod.
Cette boucle est au cœur de ce qu'on travaille dans créer un site web avec Claude de A à Z, qui couvre tout l'amont (brief, design, code) avant la mise en ligne. Et si tu démarres de zéro, le pilier setup Claude couvre l'environnement complet, de Claude Code à ton éditeur.
Passer à la pratique
Un site Vercel qui tourne, c'est un projet qui build en local, un repo poussé sur GitHub, des variables d'environnement bien scopées, et un domaine dont les DNS pointent au bon endroit. Le reste, Claude Code le fait avec toi : debug des builds, patch des erreurs de types, nettoyage du projet avant mise en ligne. Pour pousser plus loin et apprendre à articuler Claude, Claude Code et Vercel dans un workflow complet (site vitrine, blog SEO, automatisations, marketing), le programme Maîtriser Claude au quotidien couvre les 5 chantiers en 5 semaines, avec un projet concret livré à chaque module.