Guide de déploiement

Guide les utilisateurs dans le déploiement de leur bibliothèque de composants de code vers Webflow.

Quand utiliser cette compétence

Utiliser quand :

• L'utilisateur est prêt à déployer les composants vers Webflow
• L'utilisateur demande comment partager, publier ou déployer sa bibliothèque
• Premier déploiement vers un workspace
• Une explication étape par étape du déploiement est nécessaire

NE PAS utiliser quand :

• Le déploiement a échoué (utiliser troubleshoot-deploy à la place)
• Validation avant le déploiement (utiliser pre-deploy-check à la place)
• Configuration du développement local (utiliser local-dev-setup à la place)

Remarque : La commande CLI est webflow library share. Cette compétence utilise « déployer » comme terme pour l'utilisateur final.

Instructions

Phase 1 : Vérifications préalables

1. Vérifier que le projet est prêt :

   • Vérifier la configuration webflow.json
   • S'assurer que toutes les dépendances sont installées
   • Exécuter les vérifications de la compétence pre-deploy-check

2. Vérifier le statut d'authentification :

   • Chercher un .env existant avec le token API
   • Vérifier WEBFLOW_WORKSPACE_API_TOKEN s'il est défini
   • Préparer l'authentification si nécessaire

3. Confirmer la cible de déploiement :

   • Quel workspace ?
   • Nouvelle bibliothèque ou mise à jour d'une existante ?

Phase 2 : Authentification

4. Guider l'authentification :
   • Interactive : Suivre les invites CLI
   • CI/CD : Utiliser le flag --api-token
   • Montrer comment obtenir le token API du workspace si nécessaire

Phase 3 : Déploiement

5. Exécuter le déploiement :
   • Exécuter npx webflow library share
   • Surveiller les erreurs
   • Capturer la sortie

Phase 4 : Vérification

6. Vérifier le déploiement :

   • Vérifier les composants dans Webflow Designer
   • Tester la fonctionnalité des composants
   • Confirmer que tous les composants apparaissent

7. Fournir les étapes suivantes :

   • Comment utiliser les composants dans Designer
   • Comment mettre à jour à l'avenir
   • Tâches courantes après le déploiement
   • Si le déploiement échoue, utiliser troubleshoot-deploy pour diagnostiquer et corriger les problèmes

Flux de travail de déploiement

Déploiement standard

📦 Déploiement des composants de code

Étape 1 : Vérifications préalables
├── webflow.json ✅
├── Dépendances ✅
└── Test de build ✅

Étape 2 : Authentification
├── Vérification de l'authentification existante...
└── Token valide trouvé ✅

Étape 3 : Déploiement
├── Bundling des composants...
├── Upload vers le workspace...
└── Traitement...

Étape 4 : Vérification
├── Bibliothèque enregistrée ✅
└── 4 composants disponibles ✅

🎉 Déploiement terminé !

Déploiement CI/CD

# Définir la variable d'environnement
export WEBFLOW_WORKSPACE_API_TOKEN=your-token-here

# Déployer sans invites
npx webflow library share --no-input

Exemples

Prompt utilisateur :

Déployer mes composants vers Webflow

Réponse :

🚀 Guide de déploiement : Composants de code

Je vais vous guider à travers le déploiement de votre bibliothèque de composants.

---

## Étape 1 : Vérifications préalables

Exécution de la validation...

✅ webflow.json configuré
✅ Dépendances installées
✅ Build réussit
✅ Taille du bundle : 2,3 Mo (sous la limite de 50 Mo)

Toutes les vérifications sont passées ! Prêt à déployer.

---

## Étape 2 : Authentification

**Option A : Interactive (Recommandé pour la première fois)**

Exécutez la commande de déploiement :
```bash
npx webflow library share

Cela va :

1. Ouvrir votre navigateur pour la connexion à Webflow
2. Vous demander d'autoriser l'application
3. Enregistrer les identifiants dans .env

Option B : Token API (Pour CI/CD ou utilisateurs récurrents)

1. Obtenir votre token API du workspace :

   • Aller au tableau de bord Webflow
   • Naviguer vers les paramètres de votre workspace
   • Trouver « Apps & Integrations » → « Manage »
   • Sous « Workspace API Access », cliquer sur « Generate API Token »
   • Copier le token

2. Exécuter avec le token :

   npx webflow library share --api-token YOUR_TOKEN_HERE

Ou définir la variable d'environnement :

export WEBFLOW_WORKSPACE_API_TOKEN=YOUR_TOKEN_HERE
npx webflow library share

Étape 3 : Déployer

Prêt à déployer ? Exécutez :

npx webflow library share

Résultat attendu :

✓ Bundling des composants...
✓ Authentification...
✓ Upload de la bibliothèque...
✓ Traitement...

La bibliothèque « My Component Library » a été partagée avec succès !

Composants :
- Button
- Card
- Accordion
- Modal

Voir dans Designer : Ouvrir n'importe quel site dans votre workspace

Étape 4 : Vérifier dans Designer

Après le déploiement :

1. Ouvrir Webflow Designer pour n'importe quel site dans votre workspace
2. Ouvrir le panneau Add (touche A ou bouton +)
3. Trouver la section « Components »
4. Chercher votre bibliothèque sous les composants personnalisés
5. Glisser un composant sur le canevas pour tester

Étape 5 : Étapes suivantes

✅ Vos composants sont en direct !

Pour mettre à jour les composants plus tard :

# Apporter vos modifications, puis redéployer
npx webflow library share

Notes importantes :

• Les mises à jour remplacent la bibliothèque entière (pas de mises à jour partielles)
• Les instances de composants existants se mettront à jour automatiquement
• Ne pas renommer les fichiers .webflow.tsx (casse les instances)

💡 Conseils :

• Ajouter .env à .gitignore pour protéger votre token
• Utiliser le flag --verbose pour déboguer les problèmes
• Exécuter npx webflow library log pour voir les logs de déploiement récents

Exemple : Configuration première fois

🚀 Guide de déploiement : Configuration première fois

Je vois que c'est votre premier déploiement. Laissez-moi vous guider à travers la configuration complète.

---

## Étape 1 : Obtenir le token API du workspace

Vous aurez besoin d'un token API du workspace pour déployer :

1. **Ouvrir le tableau de bord Webflow**
   Aller à webflow.com et se connecter

2. **Naviguer vers les paramètres du workspace**
   Cliquer sur le nom du workspace → Paramètres

3. **Trouver l'accès API**
   Aller à « Apps & Integrations » → « Manage »

4. **Générer le token**
   Sous « Workspace API Access » :
   - Cliquer sur « Generate API Token »
   - Copier le token (vous ne le verrez plus !)

5. **Enregistrer le token**
   Ajouter à votre fichier .env :

WEBFLOW_WORKSPACE_API_TOKEN=your-token-here

   ⚠️ Ajouter .env à .gitignore :
   ```bash
   echo ".env" >> .gitignore

Étape 2 : Déployer

Maintenant, exécutez :

npx webflow library share

Le CLI va :

1. Lire votre token depuis .env
2. Bundler vos composants
3. Upload vers votre workspace

Étape 3 : Vérifier

Après un déploiement réussi :

1. Ouvrir Webflow Designer
2. Appuyer sur 'A' pour ouvrir le panneau Add
3. Trouver vos composants dans la section Components
4. Glisser sur le canevas pour tester

🎉 Premier déploiement terminé !

Les déploiements futurs sont plus simples :

# Juste exécuter ceci après avoir apporté des modifications
npx webflow library share

---

**Exemple : Configuration CI/CD**

🚀 Guide de déploiement : Configuration CI/CD

Configuration des déploiements automatisés pour votre pipeline.

Exemple GitHub Actions

Créer .github/workflows/deploy.yml :

name: Deploy to Webflow

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Deploy to Webflow
        env:
          WEBFLOW_WORKSPACE_API_TOKEN: ${{ secrets.WEBFLOW_WORKSPACE_API_TOKEN }}
        run: npx webflow library share --no-input

Ajouter le secret à GitHub

1. Aller à votre repo → Settings → Secrets and variables → Actions
2. Cliquer sur « New repository secret »
3. Nom : WEBFLOW_WORKSPACE_API_TOKEN
4. Valeur : Votre token API du workspace
5. Cliquer sur « Add secret »

Flags clés pour CI/CD

npx webflow library share --no-input

• --no-input : Désactive les invites interactives
• Utilise automatiquement la variable d'environnement WEBFLOW_WORKSPACE_API_TOKEN

Optionnel : Ajouter une vérification TypeScript

- name: Type check
  run: npx tsc --noEmit

✅ CI/CD configuré !

Maintenant, chaque push vers main déploiera automatiquement vos composants.

## Validation

Après le déploiement, vérifier le succès avec ces vérifications :

| Vérification | Comment vérifier |
|-------|---------------|
| Déploiement terminé | `npx webflow library share` s'est terminé sans erreurs |
| Composants visibles | Ouvrir Designer Add panel → trouver votre bibliothèque |
| Logs d'import propres | `npx webflow library log` affiche une importation réussie |
| Taille du bundle OK | La sortie affiche un bundle sous 50 Mo |
| Les props fonctionnent | Glisser le composant sur le canevas, vérifier les props dans le panneau droit |

## Directives

### Terminologie

La commande CLI est `webflow library share`. Cette compétence utilise « déployer » comme terme pour l'utilisateur final pour la cohérence avec le vocabulaire courant des développeurs. Voir la [référence CLI](../../references/CODE_COMPONENTS_REFERENCE.md) (Section 12) pour la documentation complète de la commande.

### Méthodes d'authentification

| Méthode | Cas d'utilisation | Commande |
|--------|----------|---------|
| Interactive | Première fois, développement local | `npx webflow library share` |
| Variable d'environnement | CI/CD, automation | Définir `WEBFLOW_WORKSPACE_API_TOKEN` |
| Flag CLI | Token différent unique | `--api-token TOKEN` |

### Checklist pré-déploiement

Avant chaque déploiement :

- [ ] `npm install` est à jour
- [ ] Le build réussit localement
- [ ] Bundle sous 50 Mo
- [ ] Tous les tests de composants réussissent
- [ ] Pas de code qui casse SSR (ou ssr: false défini)
- [ ] Les props ont des valeurs par défaut où supporté (non disponible pour Link, Image, Slot, ID)

### Problèmes courants de déploiement

| Problème | Cause | Solution |
|-------|-------|----------|
| « Authentication failed » | Token invalide/expiré | Régénérer le token du workspace |
| « Bundle too large » | Plus de 50 Mo | Optimiser les dépendances |
| « Library not found » | Mauvais workspace | Vérifier le workspace du token |
| « Build failed » | Erreurs de code | Corriger les erreurs de compilation |

### Référence des flags CLI

Tous les flags pour `npx webflow library share` :

| Flag | Description | Défaut |
|------|-------------|---------|
| `--manifest` | Chemin vers le fichier `webflow.json` | Scanne le répertoire courant |
| `--api-token` | Token API du workspace | Utilise `WEBFLOW_WORKSPACE_API_TOKEN` de `.env` |
| `--no-input` | Ignorer les invites interactives (pour CI/CD) | Non |
| `--verbose` | Afficher plus d'informations de débogage | Non |
| `--dev` | Bundler en mode développement (sans minification) | Non |

### Rollback et versioning

- Chaque `library share` remplace la **bibliothèque entière** — il n'y a pas de mises à jour partielles
- Il n'y a **pas de rollback intégré** — utiliser git pour revenir les modifications et redéployer
- **Ne jamais renommer les fichiers `.webflow.tsx`** — renommer crée un nouveau composant et supprime l'ancien, cassant toutes les instances existantes dans les projets

### Commandes de débogage

```bash
# Vérifier les logs de déploiement récents
npx webflow library log

# Sortie de déploiement verbose (erreurs détaillées)
npx webflow library share --verbose

# Vérification du bundle local (détecte les erreurs de build avant le déploiement)
npx webflow library bundle --public-path http://localhost:4000/

Déploiement CI/CD

L'exemple GitHub Actions ci-dessus s'applique à n'importe quel système CI. Les éléments clés sont :

# Modèle CI générique :
npm ci                                        # Installer les dépendances
npx webflow library share --no-input          # Déployer sans invites
# Nécessite la variable d'environnement WEBFLOW_WORKSPACE_API_TOKEN

Vérification post-déploiement

Toujours vérifier après le déploiement :

1. Vérifier Designer : Les composants apparaissent dans le panneau Add
2. Tester le drag-and-drop : Le composant s'affiche sur le canevas
3. Tester les props : Les props sont éditables dans le panneau droit
4. Tester l'aperçu : Le composant fonctionne en mode aperçu
5. Tester la publication : Le composant fonctionne sur le site publié