Storefront Best Practices

• Construire ou étendre une vitrine e-commerce — tout framework (Next.js, SvelteKit, TanStack Start, React, Vue) : pages produit, listes de produits, panier, paiement, navigation, page d'accueil, recherche, pages de compte ou confirmation de commande.
• Intégrer un backend (dont Medusa) — configuration du SDK, récupération des produits/catégories/régions, affichage des prix, sélection du mode de paiement et gestion du panier.
• Optimiser une boutique existante — amélioration des taux de conversion, correction des problèmes d'expérience mobile, ajout de données structurées SEO ou amélioration de l'accessibilité dans le parcours d'achat.
• Planifier l'implémentation d'une vitrine — génération d'un plan de construction étape par étape qui référence les fichiers de référence appropriés et évite les écueils connus avant d'écrire le moindre code.

• Projets non-ecommerce — les tableaux de bord d'administration, les applications SaaS, les blogs ou tout site sans flux d'achat/de commande n'ont aucune utilité pour les modèles de cette compétence.
• Travail purement backend ou API — si vous travaillez uniquement sur la logique de commerce côté serveur sans aucun composant frontend de storefront impliqué, cette compétence apporte peu de valeur.

Avant d'écrire tout code qui appelle une API ou un SDK backend, la compétence impose un flux de travail en 5 étapes : faire une pause, interroger la documentation ou le serveur MCP, vérifier la méthode avec l'utilisateur, écrire le code, puis rechercher les erreurs TypeScript. Cela évite les noms de méthodes devinés, les exemples obsolètes et les échecs silencieux à l'exécution.

La compétence associe chaque tâche de storefront — paiement, liste de produits, navigation, SEO, mobile, intégration Medusa, et bien plus encore — à un fichier de référence spécifique (par exemple, reference/layouts/checkout.md, reference/medusa.md). Elle précise exactement quels fichiers charger avant d'implémenter chaque fonctionnalité, garantissant ainsi une application cohérente des modèles.

Couvre les règles à fort impact propres aux vitrines : aria-live="polite" sur les compteurs de panier pour les lecteurs d'écran, env(safe-area-inset-bottom) pour les boutons fixes iOS, une taille minimale de 44 px pour les zones tactiles, l'utilisation obligatoire de loading="lazy" sur les images de produits sous la ligne de flottaison, et l'interdiction des emojis dans l'interface utilisateur de Storefront Best Practices.

Fournit des modèles de routage dynamique corrects pour Next.js (App Router et Pages Router), SvelteKit, TanStack Start et Remix pour les pages de produits et de catégories. Avertit explicitement contre les routes statiques par élément qui ne passent pas à l'échelle.

Couvre l'initialisation du SDK Medusa (clé API publiable requise), l'affichage correct des prix (ne pas diviser par 100), l'exigence de region_id lors de la récupération des produits, les conventions de port CORS (8000), la configuration Vite SSR, l'utilisation de @medusajs/types plutôt que des types personnalisés, et la réinitialisation de l'état du panier après la passation d'une commande.

Une liste catégorisée de plus de 30 anti-patterns nommés couvrant le panier/la navigation, la navigation produit, le tunnel de commande, le mobile, le SEO, les performances, la cohérence du design et l'intégration backend — chacun formulé comme une règle concrète ❌ à vérifier avant et pendant l'implémentation.

La compétence fournit un flux de travail séquentiel en 10 étapes, allant de la découverte (chargement de design.md) jusqu'à l'optimisation, en passant par les fondations, les composants principaux et le parcours d'achat. Chaque étape fait référence au fichier exact à charger avant la mise en œuvre, garantissant que rien n'est omis et que les styles restent cohérents.

Guide les décisions d'architecture liées au tunnel de commande (page unique ou multi-étapes), impose la récupération des méthodes de paiement depuis le backend plutôt que leur codage en dur, signale l'exigence de paiement en tant qu'invité, et fournit les étapes d'intégration de paiement spécifiques à Medusa via reference/layouts/checkout.md et reference/medusa.md.

Couvre la configuration du SDK, les modèles de région et de tarification, la récupération de produits avec region_id, les listes de pays limitées à la région du panier, la configuration Vite SSR, ainsi que l'utilisation du serveur Medusa MCP pour la vérification des méthodes — permettant d'éviter les erreurs d'intégration les plus courantes dans les storefronts Medusa.

Dirige les développeurs vers reference/mobile-responsiveness.md pour les tailles des zones tactiles, les marges de zone sécurisée et l'optimisation des images, et vers reference/seo.md pour le schéma JSON-LD des produits, les balises meta, Open Graph et la mesure des Core Web Vitals via PageSpeed Insights.