Biz Deploy Vercel — Déployer un site web sur Vercel en toute si…

Biz Deploy Vercel — Déployer un site web sur Vercel en toute simplicité, en une commande

Cette compétence transforme un dossier de projet local (React / Next.js / Vite / HTML statique) en une URL live sur Vercel avec SSL, CDN et déploiement de prévisualisation. Objectif : les solopreneurs / PME n'ont pas besoin de connaître DevOps pour déployer leur page d'atterrissage, simplement en discutant avec Claude.

Esprit : Ne pas demander à l'utilisateur ce que Claude peut vérifier lui-même. Détecter automatiquement le framework, générer vercel.json si nécessaire, ne s'arrêter qu'à une étape manuelle réelle (connexion navigateur, DNS de domaine personnalisé).

Quand l'utiliser

L'utilisateur souhaite :

• Déployer une page d'atterrissage / un site web sur une URL live pour partager / tester / lancer des annonces
• Redéployer un projet après avoir modifié le code
• Configurer Vercel pour la première fois sur un nouveau dépôt
• Configurer un domaine personnalisé pointant vers Vercel

Quand NE PAS l'utiliser

• Besoin uniquement de construire en local, pas encore de mise en public → ignorer, utiliser npm run build / next dev.
• Déploiement sur Netlify / Cloudflare Pages / AWS → cette compétence est spécialisée pour Vercel.
• Besoin d'un CI/CD complexe avec GitHub Actions personnalisé → utiliser cette compétence pour initialiser le projet, mais la partie workflow personnalisé est à configurer par l'utilisateur.
• Besoin d'un backend Node.js avec état complet (websocket, long polling) → serverless Vercel inadapté, utiliser Railway / Fly.io.

Ce que l'utilisateur recevra

1. URL live de type https://<projet>.vercel.app (production) ou URL de prévisualisation.
2. URL Inspect de type https://vercel.com/<compte>/<projet>/<id-déploiement> pour consulter les logs.
3. Projet lié dans .vercel/project.json (ignoré par git) — le prochain déploiement nécessite uniquement vercel --prod.
4. Si l'utilisateur demande un domaine personnalisé → instructions DNS spécifiques (enregistrement A / CNAME).

---

Workflow en 6 étapes

Étape 1 — Pré-vérification : Vérifier Vercel CLI / MCP

Exécuter scripts/check_vercel.sh (ou les commandes équivalentes en ligne) pour déterminer l'état des 3 éléments :

Élément à vérifier	Commande	Résultat attendu
Node.js	node --version	v18+ ou v20+
Vercel CLI	vercel --version	Version retournée (v32+)
Authentification Vercel	vercel whoami	Nom d'utilisateur retourné

Si Node.js manquant :

• macOS : suggérer brew install node ou télécharger https://nodejs.org
• Windows : guider vers l'installateur .msi sur https://nodejs.org/en/download/
• Linux : nvm install --lts ou gestionnaire de paquets.
• Arrêter la compétence, attendre que l'utilisateur confirme l'installation.

Si Vercel CLI manquant :

• Détecter le gestionnaire de paquets utilisé (vérifier pnpm, yarn, npm par ordre de priorité ou lire le fichier lock du projet).
• Installer globalement :
  • pnpm add -g vercel (si l'utilisateur utilise pnpm)
  • npm install -g vercel (par défaut)
• Revérifier avec vercel --version.

Si Vercel CLI existe mais pas authentifié (vercel whoami retourne une erreur) :

• Exécuter vercel login — cette commande ouvre le navigateur, l'utilisateur doit cliquer pour confirmer. C'est une étape manuelle obligatoire.
• Informer l'utilisateur : "J'ai lancé vercel login. Ouvrez le navigateur, cliquez sur confirmer pour vous authentifier. Quand c'est fait, dites 'ok' pour continuer."
• Arrêter, attendre la réponse de l'utilisateur.

Si l'utilisateur mentionne Vercel MCP :

• Vérifier le serveur MCP en listant les outils MCP disponibles (outils préfixés par mcp__vercel__*).
• Si MCP est présent, privilégier quand même la CLI pour le déploiement réel (la CLI est plus stable pour les uploads de fichiers), utiliser MCP pour interroger le projet / domaine / variables d'environnement après déploiement si nécessaire.
• Si l'utilisateur insiste pour utiliser MCP : suivre la doc https://vercel.com/docs/mcp pour l'authentification, puis utiliser les outils MCP correspondants.

Étape 2 — Détection du framework + structure du projet

Lire les fichiers dans la racine du projet pour déterminer le framework :

Fichier	Framework
next.config.js / next.config.mjs / next.config.ts	Next.js
vite.config.js / vite.config.ts	Vite (React/Vue/Svelte)
package.json avec "react-scripts"	Create React App
package.json avec "astro"	Astro
package.json avec "@remix-run/dev"	Remix
Uniquement index.html + assets, pas de package.json	HTML statique
package.json présent mais ne correspond à aucun modèle ci-dessus	Demander à l'utilisateur quel framework, ou laisser Vercel détecter automatiquement

Noter également :

• La commande de build depuis package.json (scripts.build)
• Le répertoire de sortie (Next : .next, Vite : dist, CRA : build, statique : .)
• La version de Node.js requise (depuis engines.node ou .nvmrc)

→ Lire la référence correspondante :

• React/Vite → references/react-vite.md
• Next.js → references/nextjs.md
• HTML statique → references/static-html.md

Étape 3 — Générer vercel.json (si nécessaire)

Next.js : Détection automatique par Vercel, pas besoin de vercel.json sauf pour des en-têtes / redirections personnalisées.

Vite / CRA (routage SPA) : Besoin d'un vercel.json qui réécrit toutes les routes vers index.html pour que le routage côté client fonctionne :

{
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

HTML statique : Généralement pas nécessaire. Si le site a plusieurs pages (thank-you.html, privacy.html), pas besoin de réécriture. S'il n'y a qu'un index.html avec un routeur JS, besoin de réécriture comme pour une SPA.

En-têtes de sécurité (recommandés pour la production) :

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "X-Content-Type-Options", "value": "nosniff" },
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" }
      ]
    }
  ]
}

Règle : Ne créer vercel.json que si l'utilisateur en a vraiment besoin. Créer un fichier inutile = bruit dans le dépôt.

Étape 4 — Liste de vérification avant déploiement

Avant d'exécuter vercel, vérifier :

• Un .gitignore contient .vercel/, node_modules/, .env* (NE PAS commiter les secrets)
• Les chemins de fichiers dans le code sont tous minuscules + relatifs (Linux sensible à la casse)
• Pas d'URL localhost codées en dur
• Les scripts/feuilles de style externes sont en https://
• Si Next.js a des variables d'environnement → préparer la liste des variables à définir
• Si package.json présent → npm install (ou équivalent) peut être exécuté localement

Si un problème évident est détecté (ex : localhost codé en dur dans le HTML), corriger d'abord avant de déployer.

Étape 5 — Déploiement

Premier déploiement d'un projet (pas encore de .vercel/project.json) :

vercel --prod --yes

Le flag --yes accepte tous les paramètres par défaut de la détection automatique du framework. Vercel va :

• Demander la portée (sélectionne automatiquement le compte de l'utilisateur avec --yes)
• Détecter le préréglage du framework
• Définir la commande de build et le répertoire de sortie
• Pusher le code, builder, déployer

Si un nom de projet personnalisé est nécessaire ou si l'utilisateur souhaite lier à un projet existant :

vercel link              # Lier au projet existant (interactif)
vercel --prod            # Déployer après liaison

Déploiement de prévisualisation (hors production) :

vercel

→ Retourne une URL de prévisualisation du type https://<projet>-<hash>.vercel.app, utilisée pour tester avant de promouvoir en production.

Redéploiement (projet déjà lié) :

vercel --prod

Capturer la sortie — analyser stdout pour récupérer :

• Production: https://<projet>.vercel.app
• Inspect: https://vercel.com/...

Informer immédiatement l'utilisateur de ces 2 URL.

Étape 6 — Vérification + rapport

Après un déploiement réussi :

1. Vérification HTTP de l'URL live avec curl -I https://<projet>.vercel.app — vérifier le statut 200 et SSL actif.
2. Rapport à l'utilisateur au format suivant :

## ✅ Déploiement réussi

**URL live** : https://<projet>.vercel.app
**Inspect / Logs** : https://vercel.com/<compte>/<projet>/<id-déploiement>
**Framework** : <Next.js | Vite | CRA | HTML statique>
**Temps de build** : <Xs>

### Prochain déploiement
Il suffit d'exécuter : `vercel --prod`

### Options
- Configurer un domaine personnalisé → dites "configure le domaine <votredomaine.com>"
- Configurer des variables d'environnement → dites "ajoute env <CLE>"
- Voir les logs → `vercel logs`

3. Si l'utilisateur demande un domaine personnalisé → lire references/domains.md et guider pour le DNS.

---

Cas particuliers + récupération

Échec de build sur Vercel mais OK en local

Causes fréquentes :

• Sensibilité à la casse : import './Components/Header' fonctionne en local Mac mais échoue sur Linux si le dossier réel est components. Correction : renommer avec la casse correcte.
• Dépendance manquante : un paquet présent dans devDependencies mais nécessaire à l'exécution → déplacer dans dependencies.
• Version de Node.js incompatible : ajouter "engines": { "node": "20.x" } dans package.json ou .nvmrc.

→ Récupérer les logs avec vercel logs <url-déploiement>, lire, corriger, redéployer.

Projet lié au mauvais compte / projet

rm -rf .vercel/ puis réexécuter vercel --prod --yes. Ou utiliser vercel link pour sélectionner le bon projet.

Variables d'environnement en production

vercel env add <CLE> production
# Coller la valeur quand demandé
vercel env pull .env.production.local   # Récupérer en local si nécessaire

Éviter de commiter les fichiers .env*. Ajouter au .gitignore s'ils n'y sont pas.

Expiration de l'authentification

Le token CLI peut expirer. Si vercel whoami renvoie "non autorisé" → relancer vercel login.

---

Références détaillées par framework

Lire la référence correspondant au framework du projet :

Framework	Référence
Next.js (routeur App / Pages)	references/nextjs.md
React (Vite / CRA)	references/react-vite.md
HTML statique	references/static-html.md
Domaine personnalisé + DNS	references/domains.md
Erreurs & dépannage	references/troubleshooting.md

Références officielles

• Documentation Vercel CLI : https://vercel.com/docs/cli
• Configuration de build Vercel : https://vercel.com/docs/projects/project-configuration
• Limites Vercel (offre gratuite) : https://vercel.com/docs/limits
• Page de statut : https://www.vercel-status.com