Wix Headless Fast

Construis un site Wix Headless en déployant du code livré, pas en l'écrivant. Là où wix-headless fournit à l'agent des recettes à partir desquelles coder, cette skill livre l'intégration elle-même — une couche de données typée, des hooks, des composants, des pages, et un script de seed qui sont déjà corrects — et le travail de l'agent se réduit à la marque, la mise en page, le texte et le câblage. Les décisions vivent dans le code ; ne les remets pas en question.

Relation avec les skills connexes

Skill	Utilise quand
wix-headless-fast (celle-ci)	Un vertical supporté correspond à la demande et le frontend est Astro ou React — le chemin rapide.
`wix-headless`	Un vertical que cette skill ne livre pas encore, un frontend non-React, des runs backend-only, ou des types de projet stripe/self-managed.
`wix-vibe-headless`	REST client-only sur un `WIX_CLIENT_ID` à l'intérieur d'une plateforme vibe (Base44 etc.) — pas de SDK, pas de CLI.

Le modèle

Le code livré est l'implémentation. Chaque vertical est livré sous references/<vertical>/:
- app/ — le cœur agnostique du framework (TypeScript) : une couche de données qui retourne des DTOs simples et sérialisables (images résolues en URLs https, prix pré-formatés), des hooks React, et des composants headless sans routage. Fonctionne dans les îles Astro, les SPAs Vite, et Next.
- app-astro/ — une fine couche Astro : des pages SSR qui récupèrent via le cœur et passent des DTOs aux îles, avec le SEO de la page item pré-câblé et éditable par le propriétaire.
- seed/ — un script seed REST au moment du build (plan en données brutes en entrée, contenu créé en sortie) plus son contrat SEED.md.
- INSTRUCTIONS.md — le playbook du vertical : carte des fichiers, ce que tu construis, règles strictes, vérification.
Un seul point d'auth. Tout le code livré appelle Wix via src/wix/sdk.ts : sur Astro géré par Wix l'auth est ambiante (pas de client, pas d'id) ; sur n'importe quel autre setup React le même fichier lance un client visiteur manuel hors de l'id client public dans src/wix/config.ts. L'étape de déploiement configure cela — rien à câbler manuellement.
Copie tel quel ; étends en appelant. Câble les hooks/composants/fonctions exportés ; ne réécris jamais leurs internes, ne les re-route pas via des routes API, ni ne re-dérive une forme de requête. Pour un vrai écart, ajoute une nouvelle fonction dans la couche de données (ou consulte la skill wix-docs pour le contrat API) — ne modifie jamais les versions livrées.
Jamais de mock, échoue bruyamment, les achats via Wix. Données live ou un état vide honnête ; erreurs surfacées, pas avalées ; checkout/achat toujours via la session de redirection Wix.

L'exécution

Résous la stack. Par défaut Wix-managed Astro — prends-la sauf si l'utilisateur nomme un framework React différent ou que le répertoire contient déjà un projet React non-Astro. Un frontend non-React est hors de portée → wix-headless.
Scaffolde / connecte (géré). Nécessite Node ≥ 20.11 et un Wix CLI connecté (npx @wix/cli@latest whoami ; se connecter via le device-code flow — affiche l'URL+code, ne lis jamais les tokens en contexte). Ensuite :
- répertoire vide → CI=1 npm create @wix/new@latest -- headless --folder-name <name> --business-name "<Brand>" --site-template --skip-install --no-publish, puis travaille à l'intérieur du dossier créé (installe les dépendances avec npm install --ignore-scripts) ;
- projet existant pas encore sur Wix → CI=1 npm create @wix/new@latest init sur place ;
- a déjà wix.config.json → aucun des deux ; c'est un run itératif.
Déploie le code livré (depuis la racine du projet) : node <SKILL_ROOT>/install/deploy.mjs <vertical…> --stack astro|react (react stack : ajoute --client-id s'il n'y a pas de wix.config.json pour lire l'id client public). Re-lancer est sûr — cela remplit les fichiers manquants, ne réécrit jamais les modifications.
Seed le backend selon le seed/SEED.md du vertical — écris un plan en données brutes à partir du brief et lance le script seed. Il installe l'app Wix du vertical lui-même. Le seeding est additif : ne supprime ni n'écrase jamais le contenu existant ; si un nettoyage semble nécessaire, demande.
Construis la couche de marque selon le INSTRUCTIONS.md du vertical : la page d'accueil, le header/footer/tokens de la mise en page, et le texte — composant les pièces livrées. Lis les INSTRUCTIONS avant de toucher à n'importe quel fichier livré.
Libère une fois, à la toute fin (géré) : npx @wix/cli@latest build puis npx @wix/cli@latest release. Ne fais pas build+release en cours de flux ; le contenu backend est récupéré à l'exécution, donc une re-libération ne « rafraîchit » jamais les données seedées. Termine avec l'URL live et le lien du dashboard https://manage.wix.com/dashboard/<siteId>.

Ne fais pas de smoke-test avec un dev server sauf si l'utilisateur demande explicitement de vérifier — la correction provient du code livré, et les vrais erreurs surgissent au build/release.

Verticals

L'utilisateur veut…	Vertical	Playbook
Boutique en ligne : produits, catégories, variantes, panier, paiement	storefront	`references/storefront/INSTRUCTIONS.md`

Une demande qui ne correspond pas à un vertical livré n'est pas le chemin rapide de cette skill — oriente-la vers wix-headless plutôt que d'improviser un vertical non-livré ici.

Ajouter un vertical (contrat de structure)

Les nouveaux verticals suivent la même mise en page — le script de déploiement les découvre automatiquement (n'importe quel répertoire references/<name>/app/ est un vertical) :

references/<vertical>/
  INSTRUCTIONS.md      # playbook : carte des fichiers, câblage par stack, ce que tu construis, règles strictes, vérification
  app/                 # cœur agnostique du framework — chemins disjoints pour que les verticals ne se heurtent jamais :
    wix/<vertical>/    #   types.ts (DTOs) + couche de données (appels via ../sdk, images via ../media)
    hooks/<vertical>/  #   hooks React (SSR-friendly : acceptent les données initiales)
    components/<vertical>/  # composants sans routage (plain <a> par défaut + prop LinkComponent)
    styles/<vertical>.css   # styles structurels sur les tokens de style --sf-*
  app-astro/           # couche Astro important UNIQUEMENT du cœur :
    pages/…            #   SSR fetch → DTO props → îles client:load ; les pages item portent
                       #   wixMetadata + <SEO.Tags> ; les îles chrome sont client:only
    layouts/…          #   (réutilise SiteLayout quand c'est approprié)
  seed/                # seed-<vertical>.mjs (REST, frappe son propre token CLI) + SEED.md

Les règles de base que la structure encode : les entités d'API brutes ne quittent jamais la couche de données (DTOs uniquement) ; l'état partagé client-side utilise un store à portée module (jamais React context — cela ne peut pas couvrir les îles Astro) ; chaque URL d'image est résolue via src/wix/media.ts ; chaque valeur monétaire est une chaîne formatée au moment où un composant la voit.