Guide pratique pour connecter Nuxt 3 à Medusa 2 : installation, configuration CORS, SDK et création de votre premier storefront headless.
Avant de commencer, assurez-vous d'avoir les outils suivants installés sur votre machine :
Suivez le guide d'installation Medusa pour des instructions détaillées. Voici une version simplifiée :
Exécutez la commande suivante pour créer une nouvelle application Medusa :
npx create-medusa-app@latest my-medusa-store
Lorsqu'on vous demande :
Would you like to create the Next.js storefront? You can also create it later.
Choisissez No. Pour ce tutoriel, nous utiliserons notre storefront Nuxt personnalisé à la place.
Attendez que la configuration soit terminée. Une fois fait, votre application Medusa devrait automatiquement ouvrir une page dans votre navigateur, vous permettant de vous connecter à l'interface du tableau de bord Admin à http://localhost:9000/app.
http://localhost:9000/apphttp://localhost:9000Lorsque l'interface du tableau de bord Admin se charge, remplissez le formulaire d'inscription pour créer votre premier utilisateur Admin.
Ce tutoriel n'est pas centré sur la configuration Medusa, mais nous couvrirons la configuration de base nécessaire pour l'intégration avec notre application Nuxt.
Ouvrez le fichier .env dans votre dossier d'application Medusa et mettez à jour la clé STORE_CORS pour inclure l'URL par défaut de votre application Nuxt :
STORE_CORS=http://localhost:3000
Cela permet à Medusa d'accepter les requêtes API depuis http://localhost:3000, qui est l'URL par défaut pour une application Nuxt en local.
Naviguez vers Store Settings > Regions dans le tableau de bord Admin.
Naviguez vers Products > Collections.
Pour des instructions détaillées, visitez le guide d'installation Nuxt. Voici un résumé de ce que nous allons faire :
pnpm dlx nuxi@latest init nuxt-medusa
Naviguez vers votre dossier d'application :
cd nuxt-medusa
/app et déplacez app.vue dans ce dossier.nuxt.config.ts :export default defineNuxtConfig({
compatibilityDate: '2024-11-01',
devtools: { enabled: true },
future: {
compatibilityVersion: 4,
},
});
Suivez le guide d'installation ESLint. Je recommande d'activer le formatage stylistic :
Ajoutez la clé ESLint à votre fichier nuxt.config.ts :
eslint: {
config: {
stylistic: true,
},
},
Nuxt UI v3 est une bibliothèque basée sur Reka UI (anciennement Radix-Vue) et sert d'excellente alternative puisque la bibliothèque UI de Medusa (basée sur Radix Primitives) est uniquement React. Pour les détails d'installation, visitez la documentation Nuxt UI v3.
Les applications e-commerce nécessitent une gestion optimisée des images. Utilisez Nuxt Image pour cela. Les instructions d'installation sont disponibles ici.
/app/app.vue par le suivant :<template>
<UApp>
<NuxtRouteAnnouncer />
<NuxtPage />
</UApp>
</template>
/app/pages/index.vue :<template>
<div>
<AppHero />
</div>
</template>
/app/components/hero.vue :<script setup lang="ts">
const { title } = useAppConfig();
</script>
<template>
<UContainer class="flex items-center justify-center h-screen bg-neutral-100">
<h1 class="text-3xl text-primary-500 font-semibold">
{{ title }}
</h1>
</UContainer>
</template>
/app/app.config.ts :export default defineAppConfig({
title: 'Nuxt Medusa Storefront',
ui: {
colors: {
primary: 'blue',
neutral: 'zinc',
},
},
});
pnpm run dev
Vous devriez voir votre application Nuxt fonctionner avec le thème configuré.
Ouvrez le fichier .env dans votre dossier d'application Medusa et mettez à jour la clé STORE_CORS :
STORE_CORS=http://localhost:8000,http://localhost:3000,https://docs.medusajs.com
Redémarrez le serveur :
npm run dev
Créez un fichier .env dans votre projet Nuxt :
NUXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000
NUXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_your_key
Remplacez pk_your_key par votre Clé Publishable Medusa, que vous pouvez trouver sous Store Settings > Publishable Key.
Mettez à jour nuxt.config.ts :
runtimeConfig: {
public: {
medusaBackendUrl: '',
medusaPublishableKey: '',
},
},
Créons maintenant un plugin qui nous permet d'utiliser le SDK Medusa partout dans notre application.
D'abord, installons le SDK Medusa :
pnpm add @medusajs/js-sdk
pnpm add -D @medusajs/types
Créez votre plugin Nuxt Medusa /app/plugins/medusa.ts :
import Medusa from '@medusajs/js-sdk'
export default defineNuxtPlugin(() => {
const config = useRuntimeConfig()
const medusa = new Medusa({
baseUrl: config.public.medusaBackendUrl,
debug: process.env.NODE_ENV === 'development',
publishableKey: config.public.medusaPublishableKey,
})
return {
provide: {
medusa,
},
}
})
Testons maintenant notre intégration.
Pour cela, remplacez simplement votre /app/pages/index.vue par le suivant :
<script setup lang="ts">
const { $medusa } = useNuxtApp()
</script>
<template>
<div>
<AppHero />
<pre>{{ $medusa }}</pre>
</div>
</template>
Au moment de la rédaction de cet article, nous observons une erreur si nous démarrons l'application Nuxt disant :
[nuxt] [request error] [unhandled] [500] Cannot find module './stringify'Pour résoudre cela, vous devez installer la bibliothèque qs.
pnpm add qs
Redémarrons notre application, et vous devriez maintenant voir toutes les méthodes et propriétés du SDK Medusa affichées !
Félicitations ! Vous avez installé et configuré avec succès Medusa et Nuxt pour votre storefront. Votre environnement est maintenant prêt pour le développement ultérieur, où nous nous concentrerons sur la création de fonctionnalités, le style des composants et la connexion du frontend au backend. Dans les prochaines étapes, nous approfondirons la création de pages dynamiques et l'exploitation de l'API Medusa pour la gestion des produits et du panier.
Des analyses claires pour faire les bons choix techniques, même sans être dev.