CodFlow Storefront — Déploiement Vercel

Vitrine CodFlow — Procédure de déploiement Vercel

cod-astro/theme01 est le thème de vitrine frontal pour CodFlow (Astro 7). Alors que le backend CodFlow (cod-server) et le tableau de bord marchand (cod-client-astro) s'exécutent sur Cloudflare Workers (avec D1, R2 et KV), la vitrine prend en charge des cibles de déploiement dynamiques (DEPLOY_TARGET=vercel ou DEPLOY_TARGET=cloudflare).

Déployer la vitrine sur Vercel est souvent préféré car :

1. Résout l'erreur Cloudflare 1042 (blocage Worker vers Worker) : Lorsque cod-server est déployé sur un sous-domaine gratuit *.workers.dev sans domaine personnalisé, Cloudflare bloque un autre Cloudflare Worker sur *.workers.dev qui tente de l'appeler. Vercel s'exécute en dehors du réseau interne de Cloudflare, permettant à la vitrine de récupérer cod-server sur *.workers.dev sans nécessiter de domaine personnalisé.
2. Bande passante Edge mondiale généreuse : Vercel inclut une bande passante généreuse et la mise en cache CDN Edge pour le trafic de la vitrine.
3. Déploiements de prévisualisation automatiques : Chaque branche Git/PR peut avoir sa propre URL de prévisualisation pour tester les modifications du thème.

---

Variables d'environnement requises

Avant de déployer, collectez ces valeurs :

Variable	Description	Exemple
DEPLOY_TARGET	Obligatoire. Indique à astro.config.mjs d'utiliser @astrojs/vercel	vercel
COD_SERVER_URL	Obligatoire. URL de base de l'API cod-server déployée	https://api.votredomaine.com ou https://codflow-server.<compte>.workers.dev
STORE_API_KEY	Obligatoire. Clé API brute du magasin correspondant à la clé ensemencée dans D1	Générée dans codflow-setup Étape 4
MEDIA_DOMAIN	Optionnel. Domaine personnalisé pour le CDN d'images R2	media.votredomaine.com

[!IMPORTANT] STORE_API_KEY est secrète. Elle est utilisée côté serveur dans les routes SSR et les proxys API. Ne l'exposez jamais dans les bundles côté client.

---

Méthodes de déploiement

Choisissez la Méthode 1 (Vercel CLI) pour les déploiements automatisés/terminal, ou la Méthode 2 (Tableau de bord Vercel / Git) pour un déploiement continu depuis GitHub.

---

Méthode 1 : Déployer via Vercel CLI (Recommandé pour les agents IA)

1. Prérequis

• Assurez-vous que la CLI Vercel est accessible via npx vercel (ou installée globalement).
• Vérifiez l'authentification :

  npx vercel whoami
  

  Si vous n'êtes pas connecté :
  • Si un navigateur est disponible : npx vercel login
  • Si en mode headless/CI : Définissez VERCEL_TOKEN dans l'environnement (export VERCEL_TOKEN="<token>").

2. Configurer et lier le projet

Accédez au répertoire de la vitrine :

cd cod-astro/theme01

Exécutez la configuration initiale :

npx vercel link

Suivez les invites interactives (ou fournissez des indicateurs dans les sessions non interactives) :

• Lier à un projet existant ? Non (ou Oui si vous liez un projet existant)
• Nom du projet : <projet>-storefront (ex. mastore-storefront)
• Dans quel répertoire se trouve votre code ? ./

3. Définir les variables d'environnement

Ajoutez les variables d'environnement de production requises à l'aide de la CLI :

# 1. Cible de déploiement
printf "vercel" | npx vercel env add DEPLOY_TARGET production

# 2. URL de l'API backend (doit commencer par https://)
printf "https://<votre-domaine-cod-server>" | npx vercel env add COD_SERVER_URL production

# 3. Clé API du magasin
printf "<votre-clé-api-brute-du-magasin>" | npx vercel env add STORE_API_KEY production

# 4. Optionnel : Domaine média (si un domaine personnalisé R2 est configuré)
printf "<media.votredomaine.com>" | npx vercel env add MEDIA_DOMAIN production

(Optionnel : ajoutez-les également aux environnements preview et development si vous prévoyez d'utiliser des branches de prévisualisation).

4. Construire et déployer en production

Exécutez le déploiement de production avec l'adaptateur Vercel :

cd cod-astro/theme01
npx vercel --prod

Vercel téléversera le projet, exécutera npm run build:vercel (ou astro build avec DEPLOY_TARGET=vercel), compilera les fonctions SSR serverless/edge, et fournira l'URL de production en direct (ex. https://<projet>-storefront.vercel.app).

---

Méthode 2 : Déployer via le tableau de bord Vercel (Intégration Git)

Utilisez cette méthode lors de la connexion d'un dépôt GitHub / GitLab / Bitbucket :

1. Importer le dépôt dans Vercel :

   • Dans le tableau de bord Vercel, cliquez sur Ajouter un nouveau... → Projet.
   • Sélectionnez le dépôt codflow-os.

2. Configurer les paramètres du projet :

   • Nom du projet : ex. codflow-storefront
   • Préréglage du framework : Astro
   • Répertoire racine : Cliquez sur Modifier et choisissez cod-astro/theme01. Cochez l'option "Inclure les fichiers source en dehors du répertoire racine dans l'étape de construction" (nécessaire car les dépendances de l'espace de travail sont résolues dans le node_modules racine).
   • Commande de construction : Activez Remplacer et définissez :

     npm run build:vercel
     

     (Ou laissez la valeur par défaut astro build si DEPLOY_TARGET=vercel est définie dans les variables d'environnement).
   • Répertoire de sortie : Laissez la valeur par défaut (.vercel/output).
   • Commande d'installation : Laissez la valeur par défaut (npm install / installation de l'espace de travail racine).

3. Configurer les variables d'environnement : Sous Variables d'environnement, ajoutez :

   • DEPLOY_TARGET = vercel
   • COD_SERVER_URL = https://<votre-domaine-cod-server>
   • STORE_API_KEY = <votre-clé-api-brute-du-magasin>
   • MEDIA_DOMAIN = <media.votredomaine.com> (optionnel)

4. Déployer :

   • Cliquez sur Déployer. Vercel construira l'espace de travail, regroupera le site Astro avec @astrojs/vercel, et attribuera une URL de production.

---

Vérification et tests de fumée

Une fois le déploiement terminé, exécutez ces vérifications sur l'URL Vercel en direct :

Cible	Commande / Action de test	Résultat attendu
Page d'accueil	curl -s -o /dev/null -w "%{http_code}" https://<url-vitrine>	200 (réponse HTML)
Catalogue SSR	Ouvrir https://<url-vitrine>/ dans le navigateur	Les produits s'affichent avec images, prix et titre
Détail du produit	Ouvrir https://<url-vitrine>/product/<slug>	La page produit s'affiche avec le formulaire de commande / paiement
Panier / Flux de commande	Soumettre une commande de test (ou un modal de test)	La commande est enregistrée et la page de remerciement s'affiche

Test via le terminal :

# Vérifier que la page d'accueil retourne 200 OK
curl -s -I "https://<votre-vitrine>.vercel.app" | head -n 5

# Vérifier la connectivité API via le proxy de la vitrine
curl -s "https://<votre-vitrine>.vercel.app/api/cart/validate" \
  -H "Content-Type: application/json" \
  -d '{"items":[]}'
# Attendez une réponse JSON valide

---

Configuration du domaine personnalisé

Pour attacher un domaine personnalisé à la vitrine Vercel :

1. Dans le tableau de bord Vercel : Projet → Paramètres → Domaines.
2. Saisissez votre domaine (ex. store.votredomaine.com ou votredomaine.com).
3. Configurez les enregistrements DNS :
   • Pour les sous-domaines (store.votredomaine.com) : Ajoutez un CNAME pointant vers cname.vercel-dns.com.
   • Pour le domaine nu (votredomaine.com) : Ajoutez un enregistrement A pointant vers 76.76.21.21.
4. Attendez la délivrance du certificat SSL (automatique via Let's Encrypt).

---

Dépannage

Problème	Cause	Solution
La construction échoue : Cannot find module '@astrojs/vercel'	Dépendance manquante dans cod-astro/theme01	Exécutez npm install @astrojs/vercel --workspace=cod-astro-theme01 à la racine du dépôt.
La construction produit une sortie Cloudflare au lieu d'une sortie Vercel	DEPLOY_TARGET n'est pas défini sur vercel	Assurez-vous que DEPLOY_TARGET=vercel est présent dans les variables d'environnement Vercel, ou exécutez npm run build:vercel.
La vitrine se charge mais affiche des produits vides / une bannière d'erreur	COD_SERVER_URL incorrecte ou inaccessible	Confirmez que COD_SERVER_URL a le préfixe https:// et correspond au Worker API en direct. Vérifiez que curl https://<api-url>/api/docs retourne 200.
Les commandes échouent avec 401 Non autorisé	STORE_API_KEY ne correspond pas	La valeur dans Vercel STORE_API_KEY doit correspondre à la clé ensemencée dans la base de données D1 dans codflow-setup Étape 5. Revérifiez ou mettez à jour le secret dans Vercel.
La construction du monorepo échoue à résoudre les packages partagés	Configuration du répertoire racine Vercel	Si vous utilisez l'intégration Git, assurez-vous que "Inclure les fichiers source en dehors du répertoire racine" est activé dans les paramètres du projet Vercel, ou déployez via npx vercel à l'intérieur de cod-astro/theme01.
Avertissement de version Node.js : Node.js 26 n'est pas pris en charge	Les fonctions serverless Vercel prennent en charge jusqu'à Node 24	Avertissement normal sur les machines de développement Node 26 ; Vercel exécute automatiquement Node 24 dans ses fonctions cloud.
Les images ne se chargent pas depuis R2	MEDIA_DOMAIN mal configuré ou CORS manquant	Vérifiez que MEDIA_DOMAIN est défini (nom d'hôte uniquement, sans https://). Assurez-vous que la politique CORS du bucket R2 autorise les requêtes depuis le domaine Vercel.