Build Validate

Validez les composants de code avant le déploiement pour détecter les problèmes rapidement.

Quand utiliser cette compétence

Utilisez-la quand :

• L'utilisateur s'apprête à déployer et veut vérifier les problèmes d'abord
• De façon proactive avant d'exécuter webflow library share
• L'utilisateur demande de valider, vérifier ou tester ses composants
• Après avoir apporté des modifications importantes aux composants

NE l'utilisez PAS quand :

• Le déploiement a déjà échoué (utilisez troubleshoot-deploy à la place)
• Vous construisez simplement pour le développement local
• Vous auditez la qualité du code (utilisez component-audit à la place)

Instructions

Phase 1 : Vérification de la structure du projet

1. Vérifier que webflow.json existe :

   • Vérifier les champs obligatoires (library.name, library.components)
   • Valider que le motif glob correspond aux fichiers composants — le motif recommandé est "./src/**/*.webflow.@(js|jsx|mjs|ts|tsx)" couvrant toutes les extensions supportées
   • Vérifier le chemin globals s'il est spécifié — le fichier doit exister et être importable
   • Vérifier le chemin bundleConfig s'il est spécifié — le fichier doit exister

2. Vérifier les dépendances :

   • Vérifier que @webflow/webflow-cli est installé
   • Vérifier que @webflow/data-types est installé
   • Vérifier que @webflow/react est installé
   • Vérifier la compatibilité des versions (vérifier les versions installées, ne pas supposer de versions spécifiques)

3. Vérifier les fichiers composants :

   • Trouver tous les fichiers .webflow.tsx / .webflow.ts correspondant au motif glob
   • S'assurer que les composants React correspondants existent
   • Vérifier les fichiers de définition orphelins

4. Valider les imports dans les fichiers .webflow.tsx :

   • Doit importer declareComponent depuis @webflow/react
   • Doit importer props depuis @webflow/data-types (si les props sont définis)
   • Doit importer le composant React réel en cours de déclaration

Phase 2 : Analyse des composants

5. Pour chaque composant, vérifier :

   • declareComponent est appelé avec le composant et un objet de configuration
   • name est fourni dans la configuration
   • Toutes les props ont des propriétés name et une defaultValue appropriée si applicable
   • Les types de props sont valides — les 11 types supportés sont :
     • Text (alias : String) — saisie de texte sur une seule ligne
     • RichText — texte multi-ligne avec formatage
     • TextNode — texte éditable sur une ou plusieurs lignes sur le canevas
     • Link — saisie d'URL (retourne un objet { href, target, preload })
     • Image — téléchargement et sélection d'image
     • Number — saisie numérique
     • Boolean — basculement vrai/faux
     • Variant — liste déroulante avec options prédéfinies (nécessite un tableau options)
     • Visibility — contrôles afficher/masquer
     • Slot — zones de contenu pour les composants enfants
     • ID — ID d'élément HTML

6. Valider les options des composants :

   • Si l'objet options est présent, valider :
     • applyTagSelectors est un booléen (par défaut : false) — active les sélecteurs de balises du site en Shadow DOM
     • ssr est un booléen (par défaut : true) — contrôle le rendu côté serveur

7. Vérifier les problèmes de SSR :

   • Analyser l'utilisation d'API réservées au navigateur en dehors de useEffect ou de blocs protégés :
     • window, document, localStorage, sessionStorage, navigator
   • Signaler les motifs de contenu dynamique/personnalisé (tableaux de bord spécifiques à l'utilisateur, vues authentifiées)
   • Signaler l'interface utilisateur lourde/interactive qui ne bénéficie pas du SSR (graphiques, scènes 3D, cartes, éléments animés)
   • Signaler la sortie non déterministe (nombres aléatoires, valeurs basées sur l'heure qui diffèrent entre serveur et client)
   • Suggérer ssr: false dans les options si le composant est purement interactif ou dépendant du navigateur

8. Vérifier le style :

   • Vérifier que les styles sont importés dans .webflow.tsx ou via le fichier globals
   • Vérifier l'utilisation des classes du site — les classes du site ne fonctionnent PAS en Shadow DOM
   • Les variables du site fonctionnent : var(--variable-name, fallback)
   • Les propriétés CSS héritées fonctionnent : font-family: inherit
   • Les sélecteurs de balises fonctionnent SI applyTagSelectors: true est défini dans les options du composant
   • Valider la configuration CSS-in-JS si utilisée (voir détection CSS-in-JS ci-dessous)

9. Vérifier les problèmes de Shadow DOM + React Context :

   • Si un composant utilise des slots (props.Slot) ET importe/utilise useContext ou un Context Provider :
     • Avertir que les composants parents et enfants en slots ne peuvent pas partager React Context — chaque enfant se rend dans son propre conteneur Shadow DOM avec sa propre racine React
     • Suggérer des alternatives : Nano Stores, événements personnalisés, paramètres URL, ou stockage du navigateur

Phase 3 : Test de construction

10. Exécuter la vérification TypeScript/build :

    • Vérifier les erreurs de compilation TypeScript
    • Vérifier que tous les imports se résolvent correctement
    • Identifier tout problème au moment de la compilation

11. Vérifier la taille du bundle :

    • Si une sortie de build existe, vérifier que la taille totale du bundle est inférieure à 50 MB (limite maximale du bundle)
    • Si dépassement, signaler comme erreur et suggérer l'optimisation

12. Exécuter un test de bundle local (optionnel, suggérer à l'utilisateur) :

    • Suggérer d'exécuter npx webflow library bundle --public-path http://localhost:4000/ pour tester la mise en bundle avant le partage
    • Si des problèmes de bundling surviennent, suggérer le flag --debug-bundler pour inspecter la configuration webpack finale

Phase 4 : Détecter la configuration spécifique au framework

13. Détection de la bibliothèque CSS-in-JS :

    • Si le projet utilise styled-components : vérifier que @webflow/styled-components-utils est installé et styledComponentsShadowDomDecorator est exporté depuis le tableau des décorateurs globals
    • Si le projet utilise Emotion ou Material UI (@emotion/styled, @emotion/react, @mui/material) : vérifier que @webflow/emotion-utils est installé et emotionShadowDomDecorator est exporté depuis le tableau des décorateurs globals

14. Détection de Tailwind CSS :

    • Si le projet utilise Tailwind CSS (tailwindcss dans les dépendances) :
      • Vérifier que @tailwindcss/postcss est installé
      • Vérifier que postcss.config.mjs existe avec le plugin @tailwindcss/postcss
      • Vérifier que Tailwind CSS est importé dans le fichier globals (par ex., @import "tailwindcss" dans globals.css)

15. Détection du préprocesseur Sass/Less :

    • Si le projet utilise Sass (fichiers .scss ou sass dans les dépendances) : vérifier que sass et sass-loader sont installés, et qu'une configuration webpack ajoute la règle .scss
    • Si le projet utilise Less (fichiers .less ou less dans les dépendances) : vérifier que less et less-loader sont installés, et qu'une configuration webpack ajoute la règle .less
    • Pour l'un ou l'autre : vérifier que bundleConfig est défini dans webflow.json pointant vers la configuration webpack

16. Validation de la configuration webpack personnalisée (si bundleConfig est spécifié) :

    • Vérifier que le fichier existe au chemin spécifié
    • Vérifier qu'il utilise les exports CommonJS (module.exports)
    • Avertir s'il tente de surcharger les propriétés bloquées : entry, output, target (elles sont silencieusement filtrées)
    • Vérifier que module.rules utilise la syntaxe de fonction (currentRules) => { ... }, pas un tableau

Phase 5 : Rapporter les résultats

17. Générer un rapport de validation :
    • Lister toutes les vérifications effectuées
    • Afficher l'état réussi/échoué/avertissement
    • Fournir des suggestions de correction pour les échecs
    • Indiquer la préparation au déploiement

Vérifications de validation

Vérifications obligatoires

Vérifications d'avertissement

Vérifications d'information

Exemples

Invite utilisateur :

Check if my components are ready to deploy

Réponse :

🔍 Build Validation: My Component Library

Running pre-deployment checks...

---

## Project Structure

✅ webflow.json found
✅ library.name: "My Component Library"
✅ library.components: "./src/**/*.webflow.@(js|jsx|mjs|ts|tsx)"
✅ globals: "./src/globals.ts"
✅ bundleConfig: not specified (using defaults)

---

## Dependencies

✅ @webflow/webflow-cli: installed
✅ @webflow/data-types: installed
✅ @webflow/react: installed
✅ react: installed
✅ typescript: installed

---

## Frameworks Detected

✅ Tailwind CSS detected
  ✅ @tailwindcss/postcss installed
  ✅ postcss.config.mjs found
  ✅ globals.css imports Tailwind

---

## Components Found (4)

### 1. Button ✅
- File: src/components/Button/Button.webflow.tsx
- Imports: ✅ declareComponent, ✅ props, ✅ Button component
- Props: label (Text), variant (Variant), disabled (Boolean)
- All props have defaults ✅
- SSR compatible ✅
- Options: applyTagSelectors: true ✅
- Styles imported ✅

### 2. Card ✅
- File: src/components/Card/Card.webflow.tsx
- Imports: ✅ declareComponent, ✅ props, ✅ Card component
- Props: title (Text), image (Image), content (RichText), link (Link)
- All props have defaults ✅
- SSR compatible ✅
- Styles imported ✅

### 3. Modal ⚠️
- File: src/components/Modal/Modal.webflow.tsx
- Imports: ✅ declareComponent, ✅ props, ✅ Modal component
- Props: title (Text), isOpen (Boolean), content (Slot)
- All props have defaults ✅
- ⚠️ SSR Issue: Uses `document.body` in render
  → Suggestion: Add `ssr: false` to options or wrap in useEffect
- Styles imported ✅

### 4. CartIcon ⚠️
- File: src/components/CartIcon/CartIcon.webflow.tsx
- Imports: ✅ declareComponent, ✅ CartIcon component
- Props: none
- ⚠️ Missing props - component has no editable properties
  → Suggestion: Consider adding props for designer customization
- ⚠️ Uses localStorage without SSR guard
  → Suggestion: Wrap in useEffect or useState initializer
- Styles imported ✅

---

## Build Test

✅ Build completed successfully
✅ No TypeScript errors
✅ No webpack errors
✅ Bundle size: 2.3MB / 50MB limit

---

## Summary

| Category | Status |
|----------|--------|
| Project Structure | ✅ Pass |
| Dependencies | ✅ Pass |
| Frameworks | ✅ Pass |
| Components | ⚠️ 2 warnings |
| Build | ✅ Pass |

---

## Ready to Deploy: ⚠️ WITH WARNINGS

You can deploy, but consider fixing these issues:

1. **Modal SSR Issue**
   Add to Modal.webflow.tsx:
   ```typescript
   options: {
     ssr: false
   }

2. CartIcon localStorage Usage Update CartIcon.tsx:

   const [count, setCount] = useState(() => {
     if (typeof window === "undefined") return 0;
     return parseInt(localStorage.getItem("cartCount") || "0");
   });

💡 To deploy: npx webflow library share 💡 To test locally first: npx webflow library bundle --public-path http://localhost:4000/

---

**Exemple : Échec de la construction**

🔍 Build Validation: My Component Library

Running pre-deployment checks...

Project Structure

✅ webflow.json found ⚠️ library.components uses narrow glob: "./src/*/.webflow.tsx" → Recommendation: Use "./src/*/.webflow.@(js|jsx|mjs|ts|tsx)" to cover all supported extensions

Dependencies

❌ Missing: @webflow/react Fix: npm install --save-dev @webflow/react

Build Test

❌ Build Failed

Error in src/components/Button/Button.webflow.tsx:

Module not found: Error: Can't resolve '@webflow/react'

Summary

Ready to Deploy: ❌ NO

Fix the following before deployment:

1. Install missing dependency

   npm install --save-dev @webflow/react

2. Re-run validation After installing, run this check again.

Exemple : Décorateur CSS-in-JS manquant

🔍 Build Validation: My Component Library

---

## Frameworks Detected

⚠️ styled-components detected but Shadow DOM decorator not configured
  → Install: npm install @webflow/styled-components-utils
  → Add to globals.ts:
    ```typescript
    import { styledComponentsShadowDomDecorator } from "@webflow/styled-components-utils";
    export const decorators = [styledComponentsShadowDomDecorator];

→ Reference globals in webflow.json:

    { "library": { "globals": "./src/globals.ts" } }

Without this, styled-components styles will be injected into document.head instead of the Shadow DOM, and your components will appear unstyled.

---

**Exemple : Problèmes de configuration webpack**

🔍 Build Validation: My Component Library

Webpack Configuration

⚠️ webpack.webflow.js: module.rules uses array syntax → Must use function syntax: rules: (currentRules) => { return [...]; } → Array syntax will not work — the function receives current rules to extend

⚠️ webpack.webflow.js: overrides output property → The output property is blocked and will be silently ignored → Blocked properties: entry, output, target

💡 Use --debug-bundler flag to inspect the final merged webpack config: npx webflow library bundle --debug-bundler

---

**Exemple : Avertissement Shadow DOM Context**

Components Found (2)

1. ThemeProvider ⚠️

• File: src/components/ThemeProvider/ThemeProvider.webflow.tsx

• Props: theme (Variant), children (Slot)

• ⚠️ Shadow DOM + React Context Issue: Component uses Slot prop AND React Context (ThemeContext). Children placed in slots render in separate Shadow DOM containers with their own React roots — they cannot access this Context.

  Alternatives for cross-component state:

  • Nano Stores (lightweight reactive state)
  • Custom events (window.dispatchEvent/addEventListener)
  • URL parameters (for shareable state)
  • Browser storage (localStorage/sessionStorage)

Directives

Ordre de validation

Exécutez les vérifications dans cet ordre pour optimiser l'efficacité :

1. Structure du projet (rapide, détecte les problèmes évidents)
2. Dépendances (moyen, obligatoire pour la construction)
3. Analyse des composants (moyen, détecte les problèmes de code)
4. Détection du framework (moyen, valide la configuration CSS-in-JS/Tailwind/Sass)
5. Test de construction (lent, mais obligatoire)

Motifs de détection de SSR

Recherchez ces motifs qui indiquent des problèmes de SSR :

// Utilisation directe d'API du navigateur (cassera SSR)
window.innerWidth
document.getElementById
localStorage.getItem
navigator.userAgent
sessionStorage.getItem

// Contenu dynamique/personnalisé (peut causer une incompatibilité d'hydratation)
// Tableaux de bord spécifiques à l'utilisateur, vues authentifiées

// Interface lourde/interactive (SSR n'ajoute rien de valeur, se re-rend de toute façon)
// Graphiques, scènes 3D, cartes, éléments pilotés par animation

// Sortie non déterministe (diffère entre serveur et client)
Math.random()
new Date().toLocaleString()

// Motifs sûrs (dans useEffect ou initialiseur d'état)
useEffect(() => {
  // Les API du navigateur ici sont fines
}, []);

useState(() => {
  if (typeof window === "undefined") return default;
  return window.innerWidth;
});

Quand des problèmes de SSR sont trouvés, suggérez clairement l'option ssr: false :

export default declareComponent(MyComponent, {
  name: "My Component",
  options: {
    ssr: false  // Disables server-side rendering
  },
});

Détection de CSS-in-JS / Tailwind / Préprocesseur

Vérifiez les dépendances du projet et les fichiers pour détecter les frameworks de style :

styled-components :

• Détection : styled-components dans les dépendances package.json
• Obligation : @webflow/styled-components-utils installé
• Obligation : styledComponentsShadowDomDecorator dans le tableau des décorateurs globals

Emotion / Material UI :

• Détection : @emotion/styled, @emotion/react, ou @mui/material dans les dépendances
• Obligation : @webflow/emotion-utils installé
• Obligation : emotionShadowDomDecorator dans le tableau des décorateurs globals

Tailwind CSS :

• Détection : tailwindcss dans les dépendances
• Obligation : @tailwindcss/postcss installé
• Obligation : postcss.config.mjs avec le plugin @tailwindcss/postcss
• Obligation : import Tailwind dans CSS globals (@import "tailwindcss")

Sass :

• Détection : fichiers .scss dans src ou sass dans les dépendances
• Obligation : sass et sass-loader installés en tant que dépendances dev
• Obligation : configuration webpack avec règle .scss utilisant la syntaxe de fonction pour module.rules
• Obligation : bundleConfig défini dans webflow.json

Less :

• Détection : fichiers .less dans src ou less dans les dépendances
• Obligation : less et less-loader installés en tant que dépendances dev
• Obligation : configuration webpack avec règle .less utilisant la syntaxe de fonction pour module.rules
• Obligation : bundleConfig défini dans webflow.json

Règles de validation de la configuration webpack

Quand bundleConfig est spécifié dans webflow.json :

1. Le fichier doit exister au chemin spécifié
2. Doit utiliser CommonJS : module.exports = { ... }
3. Les propriétés bloquées qui sont silencieusement ignorées : entry, output, target
4. module.rules doit être une fonction, pas un tableau : rules: (currentRules) => { ... }
5. ModuleFederationPlugin et MiniCssExtractPlugin sont dédupliqués automatiquement

Erreurs de compilation courantes

Optimisation de la taille du bundle

Les gains rapides pour réduire la taille du bundle :

1. Utiliser la construction de production : Assurez-vous que la minification est activée
2. Tree-shake les imports : Importez les exports spécifiques
3. Remplacer les libs lourdes : moment → date-fns, lodash → lodash-es
4. Chargement lazy : Imports dynamiques pour les composants lourds
5. Vérifier les doublons : Plusieurs versions de React, etc.
6. Surveiller la taille : Le bundle doit rester en dessous de la limite de 50 MB