Développement de Storefront Medusa

Guide d'intégration frontend pour construire des storefronts avec Medusa. Couvre l'utilisation du SDK, les patterns React Query et l'appel de routes API personnalisées.

Quand appliquer

Charger cette skill pour TOUTE tâche de développement de storefront, y compris :

• Appeler des routes API Medusa personnalisées depuis le storefront
• Intégrer le SDK Medusa dans les applications frontend
• Utiliser React Query pour la récupération de données
• Implémenter des mutations avec mises à jour optimistes
• Gestion des erreurs et invalidation du cache

Charger aussi building-with-medusa quand : Construire les routes API backend que le storefront appelle

CRITIQUE : Charger les fichiers de référence si nécessaire

La référence rapide ci-dessous NE SUFFIT PAS pour l'implémentation. Vous DEVEZ charger le fichier de référence avant d'écrire du code d'intégration storefront.

Charger cette référence lors de l'implémentation des fonctionnalités storefront :

• Appeler des routes API ? → DOIT charger references/frontend-integration.md en premier
• Utiliser le SDK ? → DOIT charger references/frontend-integration.md en premier
• Implémenter React Query ? → DOIT charger references/frontend-integration.md en premier

Catégories de règles par priorité

Référence rapide

1. Utilisation du SDK (CRITIQUE)

• sdk-always-use - TOUJOURS utiliser le SDK JS Medusa pour TOUTES les requêtes API - JAMAIS utiliser fetch() régulier
• sdk-existing-methods - Pour les endpoints intégrés, utiliser les méthodes SDK existantes (sdk.store.product.list(), sdk.admin.order.retrieve())
• sdk-client-fetch - Pour les routes API personnalisées, utiliser sdk.client.fetch()
• sdk-required-headers - Le SDK ajoute automatiquement les headers obligatoires (clé API publique pour store, auth pour admin) - fetch() régulier manque ces headers et cause des erreurs
• sdk-no-json-stringify - JAMAIS utiliser JSON.stringify() sur le body - Le SDK gère la sérialisation automatiquement
• sdk-plain-objects - Passer des objets JavaScript simples au body, pas des chaînes
• sdk-locate-first - Toujours localiser où le SDK est instancié dans le projet avant de l'utiliser

2. Patterns React Query (HAUTE)

• query-use-query - Utiliser useQuery pour les requêtes GET (récupération de données)
• query-use-mutation - Utiliser useMutation pour les requêtes POST/DELETE (mutations)
• query-invalidate - Invalider les queries dans onSuccess pour rafraîchir les données après les mutations
• query-keys-hierarchical - Structurer les query keys hiérarchiquement pour une gestion efficace du cache
• query-loading-states - Toujours gérer les états isLoading, isPending, isError

3. Affichage des données (HAUTE)

• display-price-format - CRITIQUE : Les prix de Medusa sont stockés tels quels ($49.99 = 49.99, PAS en centimes). Les afficher directement - JAMAIS diviser par 100

4. Gestion des erreurs (MOYENNE)

• error-on-error - Implémenter le callback onError dans les mutations pour gérer les échecs
• error-display - Afficher les messages d'erreur aux utilisateurs quand les mutations échouent
• error-rollback - Utiliser les mises à jour optimistes avec rollback en cas d'erreur pour une meilleure UX

Pattern SDK critique

TOUJOURS passer des objets simples au SDK - JAMAIS utiliser JSON.stringify() :

// ✅ CORRECT - Objet simple
await sdk.client.fetch("/store/reviews", {
  method: "POST",
  body: {
    product_id: "prod_123",
    rating: 5,
  }
})

// ❌ FAUX - JSON.stringify casse la requête
await sdk.client.fetch("/store/reviews", {
  method: "POST",
  body: JSON.stringify({  // ❌ NE PAS FAIRE!
    product_id: "prod_123",
    rating: 5,
  })
})

Pourquoi c'est important :

• Le SDK gère la sérialisation JSON automatiquement
• Utiliser JSON.stringify() va double-sérialiser et casser la requête
• Le serveur ne pourra pas parser le body

Checklist des erreurs courantes

Avant d'implémenter, vérifier que vous ne faites PAS ces choses :

Utilisation du SDK :

• [ ] Utiliser fetch() régulier au lieu du SDK JS Medusa (cause des erreurs de headers manquants)
• [ ] Ne pas utiliser les méthodes SDK existantes pour les endpoints intégrés (p.ex. utiliser sdk.client.fetch("/store/products") au lieu de sdk.store.product.list())
• [ ] Utiliser JSON.stringify() sur le paramètre body
• [ ] Définir manuellement les headers Content-Type (le SDK les ajoute)
• [ ] Hardcoder les chemins d'import du SDK (les localiser en premier dans le projet)
• [ ] Ne pas utiliser sdk.client.fetch() pour les routes personnalisées

React Query :

• [ ] Ne pas invalider les queries après les mutations
• [ ] Utiliser des query keys plates au lieu de hiérarchiques
• [ ] Ne pas gérer les états de chargement et d'erreur
• [ ] Oublier de désactiver les boutons pendant les mutations (isPending)

Affichage des données :

• [ ] CRITIQUE : Diviser les prix par 100 lors de l'affichage (les prix sont stockés tels quels : $49.99 = 49.99, PAS en centimes)

Gestion des erreurs :

• [ ] Ne pas implémenter les callbacks onError
• [ ] Ne pas afficher les messages d'erreur aux utilisateurs
• [ ] Ne pas gérer les défaillances réseau correctement

Comment utiliser

Pour les patterns détaillés et les exemples, charger le fichier de référence :

references/frontend-integration.md - Utilisation du SDK, patterns React Query, intégration API

Le fichier de référence contient :

• Patterns d'intégration SDK étape par étape
• Exemples complets React Query
• Exemples de code correct vs incorrect
• Meilleures pratiques pour les query keys
• Patterns de mises à jour optimistes
• Stratégies de gestion des erreurs

Quand utiliser le serveur MCP MedusaDocs

Utiliser cette skill pour (SOURCE PRIMAIRE) :

• Comment appeler des routes API personnalisées depuis le storefront
• Patterns d'utilisation du SDK (sdk.client.fetch)
• Patterns d'intégration React Query
• Erreurs courantes et anti-patterns

Utiliser le serveur MCP MedusaDocs pour (SOURCE SECONDAIRE) :

• Méthodes SDK intégrées (sdk.admin., sdk.store.)
• Référence API du SDK Medusa officiel
• Options de configuration spécifiques au framework

Pourquoi les skills d'abord :

• Les skills contiennent des patterns critiques comme « ne pas utiliser JSON.stringify » que le MCP n'met pas en avant
• Les skills montrent les patterns correct vs incorrect ; le MCP montre ce qui est possible
• La planification nécessite de comprendre les patterns, pas juste la référence API

Intégration avec le backend

⚠️ CRITIQUE : TOUJOURS utiliser le SDK JS Medusa - JAMAIS utiliser fetch() régulier

Lors de la construction de fonctionnalités qui s'étendent sur le backend et le frontend :

1. Backend (skill building-with-medusa) : Module → Workflow → Route API
2. Storefront (cette skill) : SDK → React Query → Composants UI
3. Connexion :
   • Endpoints intégrés : Utiliser les méthodes SDK existantes (sdk.store.product.list())
   • Routes API personnalisées : Utiliser sdk.client.fetch("/store/my-route")
   • JAMAIS utiliser fetch() régulier - clé API publique manquante cause des erreurs

Pourquoi le SDK est obligatoire :

• Les routes store ont besoin du header x-publishable-api-key
• Les routes admin ont besoin des headers Authorization et de session
• Le SDK gère automatiquement tous les headers obligatoires
• fetch() régulier sans headers → erreurs d'authentification/autorisation

Voir building-with-medusa pour les patterns de routes API backend.