Intégration Next.js WooCommerce (`nextjs-woocommerce`)

Intégration Next.js WooCommerce (nextjs-woocommerce)

Guide opérationnel et checklist pour l'architecture, l'interrogation et l'intégration d'applications Next.js App Router avec un backend WooCommerce headless via WPGraphQL, WooGraphQL et l'authentification JWT.

---

Prérequis et références documentaires

• Projet Next.js 14+ initialisé avec App Router et TypeScript.
• Backend WooCommerce actif avec WPGraphQL, WooGraphQL et wp-graphql-jwt-authentication.
• Pour les schémas API complets et les motifs de code Next.js, consultez nextjs-woocommerce-reference.md.
• Pour une implémentation réutilisable du client de récupération de données, voir woocommerce-fetcher.ts.

---

Checklist d'implémentation étape par étape

flowchart TD
    S1["1. Configuration de l'environnement et du client"] --> S2["2. Catalogue public de produits (ISR/SSG)"]
    S2 --> S3["3. Authentification utilisateur (JWT + Cookies)"]
    S3 --> S4["4. Profil protégé et historique des commandes"]
    S4 --> S5["5. Session de panier et pont vers le checkout natif"]

Phase 1 : Configuration de l'environnement et du client

• Configurer les variables d'environnement :
  • Ajoutez NEXT_PUBLIC_WORDPRESS_API_URL=https://votre-boutique.com/graphql dans .env.example et .env.development.
  • Ajoutez NEXT_PUBLIC_WORDPRESS_URL=https://votre-boutique.com pour les redirections de checkout.
• Mettre en place le client universel :
  • Implémentez woocommerce-fetcher.ts prenant en charge le cache ISR et les en-têtes d'authentification.

Phase 2 : Catalogue public de produits et taxonomies

• Navigation par catégorie : Interrogez productCategories avec hideEmpty: true pour les en-têtes et les menus de catégories.
• Archive de grille de produits : Interrogez products en utilisant des fragments union (... on SimpleProduct, ... on VariableProduct). Configurez next: { revalidate: 300, tags: ['products'] }.
• Page détail produit : Pré-renforcez les routes dynamiques (app/products/[slug]/page.tsx) avec generateStaticParams() interrogeant tous les slugs de produits.

Phase 3 : Pipeline d'authentification JWT

• Mutation de connexion : Implémentez une Server Action exécutant login(input: { username: username, password: password }).
• Stockage des cookies : Stockez le authToken retourné dans un cookie HttpOnly sécurisé (auth_token).
• Liaison de session : Si le client renvoie un sessionToken, stockez-le dans le cookie wc_session.
• Déconnexion : Supprimez les cookies d'authentification lors de la déconnexion de l'utilisateur.

Phase 4 : Données utilisateur protégées et commandes

• Profil client : Interrogez viewer { id name email } en passant l'en-tête Authorization: Bearer <authToken>.
• Historique des commandes : Interrogez customer { orders { nodes { id orderNumber total status } } } avec cache: 'no-store'.

Phase 5 : Gestion du panier et stratégie de checkout

• État du panier : Capturez et persistez l'en-tête woocommerce-session retourné sur les mutations addToCart.
• Pont vers le checkout natif :
  • Redirigez les utilisateurs vers https://votre-boutique.com/checkout pour tirer parti des passerelles de paiement natives WooCommerce (ZarinPal, Mellat, Stripe), de la logistique régionale et des sceaux de conformité, sans avoir à réécrire les passerelles personnalisées.

---

Cas aux limites et pièges connus

1. Dé-optimisation statique vs dynamique : Lire les cookies dans la mise en page racine ou les pages de produits bascule Next.js en mode SSR dynamique complet. Lisez les cookies d'authentification uniquement à l'intérieur des Server Actions, des Route Handlers ou des sous-arbres isolés du tableau de bord (app/account/...).
2. Fragments polymorphes : Les requêtes directes comme products { nodes { price } } échoueront à la validation dans WooGraphQL. Enveloppez toujours les prix et les variations dans ... on SimpleProduct et ... on VariableProduct.
3. Perte de session : Lors de l'ajout d'articles au panier, ne pas renvoyer l'en-tête woocommerce-session crée un nouveau panier vide à chaque mutation.
4. CORS sur le point de terminaison GraphQL : Assurez-vous que WordPress envoie les en-têtes Access-Control-Allow-Origin et Access-Control-Allow-Headers: Authorization, Content-Type, woocommerce-session pour votre domaine Next.js.

---

Vérification et tests pré-vol

• pnpm build réussit avec la génération statique des pages produit.
• Le formulaire de connexion émet auth_token et redirige vers le tableau de bord.
• La page de compte affiche les détails du client et la liste des commandes avec un jeton valide.
• L'ajout au panier met à jour le nombre d'articles dans le panier à travers plusieurs requêtes client.