Wix App Builder

Aide à créer des extensions pour les applications Wix CLI. Couvre tous les types d'extension : pages de tableau de bord, modales, plugins, plugins de menu, widgets d'élément personnalisé, composants React d'éditeur, plugins de site, scripts intégrés, API backend, événements, plugins de service et collections de données.

⚠️ LISTE DE CONTRÔLE DU FLUX DE TRAVAIL OBLIGATOIRE ⚠️

Avant de signaler l'achèvement à l'utilisateur, TOUTES les cases DOIVENT être cochées :

• [ ] Étape 1 : Type(s) d'extension déterminé(s)
  • [ ] Questions de clarification posées si les exigences n'étaient pas claires
  • [ ] Besoin implicite de collection de données vérifié — sauf si l'utilisateur a fourni directement un ID de collection (voir Data Collection Inference)
  • [ ] Espace de noms de l'application obtenu si une extension de collection de données est créée
  • [ ] ID de collection délimités complets déterminés si une extension de collection de données est créée (voir Collection ID Coordination)
  • [ ] Recommandation expliquée avec raisonnement
• [ ] Étape 2 : Fichier(s) de référence d'extension lu(s) pour le(s) type(s) choisi(s)
• [ ] Étape 3 : Références API vérifiées ; MCP discovery utilisé uniquement pour les lacunes
• [ ] Étape 4 : Toutes les extensions implémentées
  • [ ] Tous les fichiers créés
  • [ ] Extension(s) enregistrée(s) dans extensions.ts
  • [ ] Compétence wix-design-system invoquée EN PREMIER lors de l'utilisation de @wix/design-system (pour les imports corrects, notamment les icônes)
• [ ] Étape 5 : Validation exécutée (voir Validation)
  • [ ] Dépendances installées
  • [ ] TypeScript compilé
  • [ ] Build réussi
  • [ ] Preview déployé
• [ ] Étape 6 : Tous les éléments d'action manuel collectés et présentés à l'utilisateur

🛑 ARRÊT : Si une case est décochée, ne PASSEZ PAS à l'étape suivante.

❌ ANTI-MODÈLES (À NE PAS FAIRE)

Assistant de Décision Rapide

1. Qu'essayez-vous de construire ?

   • Interface administrateur → Extensions de tableau de bord
   • Logique backend → Extensions backend
   • Stockage de données / collections CMS → Collection de données
   • Composant React d'éditeur → Extensions de site (projets d'application uniquement)

2. Qui le verra ?

   • Administrateurs uniquement → Extensions de tableau de bord
   • Visiteurs du site → Extensions de site
   • Côté serveur uniquement → Extensions backend

3. Où apparaîtra-t-il ?

   • Barre latérale/page du tableau de bord → Page de tableau de bord ou Modale
   • Tableau de bord d'application Wix existant (widget) → Plugin de tableau de bord
   • Tableau de bord d'application Wix existant (élément de menu) → Plugin de menu de tableau de bord
   • N'importe où sur le site → widget d'élément personnalisé
   • N'importe où sur le site (avec manifeste d'éditeur) → Composant React d'éditeur
   • Page de solution commerciale Wix → Plugin de site
   • Durant un flux commercial → Plugin de service
   • Après un événement → Extension d'événement

Flux de Décision (Vous n'êtes pas sûr ?)

• Admin : Besoin d'une UI pleine page ? → Page de tableau de bord. Besoin d'une popup/formulaire ? → Modale de tableau de bord. Extension du tableau de bord d'application Wix avec un widget visuel ? → Plugin de tableau de bord. Ajout d'un élément de menu au menu « plus d'actions » ou « actions en masse » d'un tableau de bord d'application Wix ? → Plugin de menu de tableau de bord. Contrainte modale : Les pages de tableau de bord ne peuvent pas utiliser <Modal /> ; utilisez une extension modale de tableau de bord séparée et dashboard.openModal().
• Backend : Lors d'un flux commercial (paiement/expédition/taxe) ? → Plugin de service. Après un événement (webhooks/sync) ? → Extension d'événement. Points de terminaison HTTP personnalisés ? → Points de terminaison backend. Besoin de collections CMS pour les données de l'application ? → Collection de données.
• Site : L'utilisateur place n'importe où (autonome) ? → widget d'élément personnalisé. Composant React d'éditeur avec manifeste d'éditeur (styling, contenu, éléments) ? → Composant React d'éditeur. Emplacement fixe sur la page d'application Wix ? → Plugin de site. Scripts/analytics uniquement ? → Script intégré.

Tableau de Référence des Types d'Extension

Contraintes clés :

• La page de tableau de bord ne peut pas utiliser <Modal /> ; utilisez une modale de tableau de bord séparée et dashboard.openModal().

Comparaison d'Extensions

Références Transversales

Data Collection Inference

CRITIQUE : Les collections de données sont souvent nécessaires implicitement — n'attendez pas que l'utilisateur dise explicitement « créer une collection CMS ». Déduisez le besoin automatiquement.

Ignorez cette section si l'utilisateur fournit directement un ID de collection (par exemple, une collection existante au niveau du site). Dans ce cas, utilisez l'ID fourni tel quel — aucune extension de collection de données ou scoping d'espace de noms nécessaire.

Incluez toujours une extension de collection de données quand L'UN DES éléments suivants est vrai :

Pourquoi cela importe : Sans l'extension de collection de données, la collection ne sera pas créée lors de l'installation de l'application, les API Wix Data peuvent ne pas fonctionner (l'éditeur de code n'est pas activé), et les ID de collection ne seront pas correctement délimités par l'espace de noms de l'application.

Si une collection de données est déduite, suivez App Namespace Requirement pour obtenir l'espace de noms avant de procéder.

App Namespace Requirement

Lors de la création d'une collection de données, vous DEVEZ demander à l'utilisateur son espace de noms d'application depuis le Wix Dev Center. C'est un paramètre obligatoire qui doit être obtenu depuis le tableau de bord Dev Center de l'utilisateur et ne peut pas être recommandé ou deviné.

Si l'utilisateur n'a pas fourni son espace de noms d'application, lisez APP_IDENTIFIERS.md et donnez à l'utilisateur les instructions pour l'obtenir.

Collection ID Coordination

S'applique UNIQUEMENT lorsqu'une extension de collection de données est créée. Si l'utilisateur fournit un ID de collection directement, utilisez-le tel quel — aucun scoping d'espace de noms, aucune extension de collection de données nécessaire.

Lorsqu'une collection de données est créée aux côtés d'autres extensions qui référencent les mêmes collections :

1. Obtenez l'espace de noms de l'application (voir App Namespace Requirement ci-dessus)
2. Déterminez le idSuffix pour chaque collection (le document de référence de la collection de données documente le format d'ID complet)
3. Utilisez l'ID de collection délimité complet (<app-namespace>/<idSuffix>) dans toutes les extensions qui référencent la collection via les appels API Wix Data

Exigence de Versioning Wix Stores

S'applique quand L'UN DES API Wix Stores est utilisé (produits, inventaire, commandes, etc.) :

1. Lisez la référence de versioning Stores — voir STORES_VERSIONING.md. Elle contient la carte des modules, une aide-mémoire des permissions, des recettes de catalogue double prêtes à copier-coller (lister/obtenir/créer/mettre à jour/supprimer des produits, inventaire, catégories), la carte des champs V1→V3, le mappage webhook et les pièges majeurs de V3. Utilisez-la avant de chercher dans les docs SDK — elle couvre les 80% courants.
2. Toutes les opérations Stores doivent d'abord vérifier la version du catalogue en utilisant getCatalogVersion()
3. Utilisez le module correct selon la version : productsV3 (V3) vs products (V1)
4. Les applications DOIVENT supporter V1 et V3 — les applications à version unique ne peuvent pas être listées sur l'App Market et se brisent sur les nouveaux sites
5. Demandez les deux étendues de permission V1 et V3 pour chaque opération Stores

C'est non négociable — V1 et V3 ne sont PAS rétro-compatibles.

Flux de Travail d'Implémentation

Étape 1 : Poser des Questions de Clarification (si nécessaire)

Ne posez des questions sur les valeurs de configuration que quand absolument nécessaire pour que l'implémentation progresse. Si une valeur peut être configurée plus tard ou ajoutée comme étape manuelle, ne bloquez pas là-dessus.

Exigence d'Identifiant de Code : Lors de la création d'un composant React d'éditeur, vous avez besoin de l'identifiant de code de l'utilisateur. S'il n'est pas fourni, lisez APP_IDENTIFIERS.md et donnez à l'utilisateur les instructions pour l'obtenir.

Si vous ne savez pas avec certitude sur l'approche (placement, visibilité, configuration, intégration), posez des questions de clarification. Si la réponse pourrait changer le type d'extension, attendez la réponse avant de procéder. Sinon, procédez avec le type d'extension qui convient le mieux.

Étape 2 : Faire Votre Recommandation

Utilisez le tableau de référence des types d'extension et le contenu de décision ci-dessus. Énoncez le type d'extension et le raisonnement bref (placement, fonctionnalité, intégration).

Étape 3 : Lire la Référence d'Extension, Vérifier les Références API, Puis Découvrir (si nécessaire)

Flux de travail : Lire la référence d'extension → Vérifier les références API → Utiliser MCP uniquement pour les lacunes.

1. Lisez le fichier de référence d'extension pour le type d'extension choisi du tableau ci-dessus
2. Identifiez les API requises à partir des exigences de l'utilisateur
3. Vérifiez les fichiers de référence API pertinents :
   • Événements backend → references/backend-event/COMMON-EVENTS.md
   • Wix Data → references/data-collection/WIX_DATA.md
   • SDK de tableau de bord → references/dashboard-page/DASHBOARD_API.md
   • SPI de plugin de service → references/service-plugin/*.md
4. Vérifiez que la méthode/événement spécifique existe dans les références
5. UTILISEZ UNIQUEMENT MCP discovery SI NON TROUVÉ dans les fichiers de référence

API de plateforme (ne jamais découvrir - dans les références) :

• Wix Data, SDK de tableau de bord, SDK d'événement (événements courants), SPI de plugin de service

API verticales (découvrir si nécessaire) :

• Wix Stores (⚠️ DOIT utiliser la référence de versioning Stores — vérification du catalogue V1/V3 requise), Wix Bookings, Wix Members, Wix Pricing Plans, intégrations tierces

Tableau de décision :

Outils MCP pour la découverte (si nécessaire) :

• SearchWixSDKDocumentation - Méthodes et API SDK (Toujours utiliser maxResults: 5)
• ReadFullDocsArticle - Documentation complète si nécessaire (uniquement si les résultats de recherche ont besoin de plus de détails)

Étape 4 : Implémentation des Extensions

Suivez le fichier de référence d'extension pour implémenter chaque extension. Règles clés :

• ⚠️ OBLIGATOIRE lors de l'utilisation de WDS : Invoquez la compétence wix-design-system EN PREMIER pour obtenir les imports corrects (les icônes proviennent de @wix/wix-ui-icons-common, PAS de @wix/design-system/icons).
• ⚠️ OBLIGATOIRE lors de l'utilisation de collections de données : Utilisez l'ID de collection EXACT à partir de idSuffix (sensible à la casse). Exemple : Si idSuffix est « product-recommendations », utilisez <app-namespace>/product-recommendations ET NON productRecommendations.
• Enregistrez toutes les extensions dans src/extensions.ts (voir Extension Registration).

Étape 5 : Exécuter la Validation

Après que toute l'implémentation soit complète, vous DEVEZ exécuter la validation. Voir APP_VALIDATION.md pour le flux de travail de validation complet :

1. Installation de paquets (détecter le gestionnaire de paquets, exécuter l'installation)
2. Vérification de compilation TypeScript (npx tsc --noEmit)
3. Validation de build (npx wix build)
4. Déploiement de preview (npx wix preview)

Ne SIGNALEZ PAS l'achèvement à l'utilisateur tant que la validation ne réussit pas.

Si la validation échoue, corrigez les erreurs et ré-validez jusqu'à ce qu'elle réussisse.

Étape 6 : Signaler l'Achèvement

Uniquement après que la validation réussisse, fournissez une section de résumé concise en haut de votre réponse :

## ✅ Implémentation Complète

[Description en 1-2 phrases de ce qui a été construit]

**Extensions Créées :**
- [Nom Extension 1] - [Brève description]
- [Nom Extension 2] - [Brève description]

**État de Build :**
- ✅ Dépendances : [Installées / message de statut]
- ✅ TypeScript : [Aucune erreur de compilation / statut]
- ✅ Build : [Achevé avec succès / statut]
- ✅/⚠️ Preview : [En cours d'exécution à l'URL / Échoué - raison]

**⚠️ IMPORTANT : [X] étape(s) manuelle(s) requise(s) pour finaliser la configuration** (voir la section « Manual Steps Required » ci-dessous)

• S'il n'y a AUCUNE étape manuelle, énoncez : « ✅ Aucune étape manuelle requise — vous êtes prêt à partir ! »

Étape 7 : Exposer les Éléments d'Action Manuel

Présentez toute étape manuelle que l'utilisateur doit effectuer (par exemple, configurer les paramètres dans le tableau de bord Wix, activer les permissions, configurer les services externes).

Format :

## 🔧 Étapes Manuelles Requises

Les actions suivantes doivent être effectuées manuellement par vous :

### 1. [Catégorie d'Action/Titre]
[Description détaillée avec instructions spécifiques]

### 2. [Catégorie d'Action/Titre]
[Description détaillée]

Extension Registration

Après la création d'un fichier d'extension, vous devez mettre à jour le fichier principal src/extensions.ts pour enregistrer l'extension auprès de l'application. Voir EXTENSION_REGISTRATION.md pour le guide complet.

Modèle rapide :

import { app } from "@wix/astro/builders";
import { dashboardpageMyPage } from "./extensions/dashboard/pages/my-page/extensions.ts";
import { embeddedscriptMyScript } from "./extensions/site/embedded-scripts/my-script/extensions.ts";

export default app()
  .use(dashboardpageMyPage)
  .use(embeddedscriptMyScript);

Sans enregistrement, les extensions n'apparaîtront pas ou ne fonctionneront pas dans le tableau de bord/éditeur/site Wix.

Validation

Exécutez ces étapes séquentiellement après que toute l'implémentation soit complète. Voir APP_VALIDATION.md pour le guide complet.

1. Installation de Paquets — Détecter le gestionnaire de paquets, exécuter l'installation
2. Compilation TypeScript — npx tsc --noEmit
3. Build — npx wix build
4. Preview — npx wix preview

Arrêtez et signalez les erreurs si une étape échoue. Vérifiez .wix/debug.log en cas d'échecs.

Optimisation des Coûts

• Lire d'abord la référence d'extension — toujours lire le fichier de référence d'extension pertinent avant d'implémenter
• Vérifier d'abord les références API — lire les fichiers de référence API pertinents avant d'utiliser MCP discovery
• Ignorer la découverte quand toutes les API requises se trouvent dans les fichiers de référence
• maxResults: 5 pour toutes les recherches SDK MCP
• ReadFullDocsArticle uniquement quand les résultats de recherche ont besoin de plus de contexte
• Invoquer wix-design-system en premier lors de l'utilisation de WDS (prévient les erreurs d'import)

Documentation

Pour les liens vers la documentation officielle Wix CLI pour tous les types d'extension, voir DOCUMENTATION.md.