Nouvel arrivage : 14 retours d’expérience Scout

Medusa Explained · Les modules

Ce qu’il y a dans un module Medusa

Dans Medusa, les données et les opérations du commerce sont organisées en modules : catalogue, prix, stock, entrepôts. Voyons pourquoi ce découpage est utile et ce que contient un module. Nous verrons aussi comment créer les nôtres avec les mêmes outils que Medusa.

3 novembre 2026Comprendre Medusa

Une basket, quatre modules

Prenons une basket vendue dans une boutique Medusa. Sa fiche (nom, description, tailles, coloris) appartient au module Product. Son prix, qui peut varier selon la devise ou une promotion, relève de Pricing. La quantité disponible est suivie par Inventory. Les entrepôts et magasins où se trouvent les paires sont décrits par Stock Location.

Une fiche produit, quatre modules

Fiche produit
Basket · 42 / BleuProductProductque vend-on ?
120 €PricingPricingquel prix ?
En stockInventoryInventorycombien ?
Entrepôt, boutiqueStock LocationStock Locationoù ?
Ici, quatre responsabilités : Product décrit la variante, Pricing fixe le prix, Inventory compte les quantités et Stock Location décrit les lieux.

Une seule basket, donc, et quatre modules qui en parlent chacun à sa façon. Le reste de la boutique suit la même logique : le panier, la commande et le paiement ont aussi leur module.

Chaque activité de la boutique obéit ainsi à ses propres règles, et c’est autour de ces activités que Medusa organise son code.

Pourquoi découper en domaines

Une boutique en ligne réunit plusieurs logiques métier : décrire les produits, déterminer les prix, tenir les quantités, enregistrer les ventes. Leurs règles sont de nature différente. Dans le catalogue, un produit se décline en variantes ; un prix dépend de conditions comme la devise ou le type de client. Si ces logiques s’entremêlent dans le code, comprendre l’une d’elles ou garder ses règles cohérentes oblige à démêler tout le système.

Séparer les responsabilités répond à cette difficulté. On regroupe ce qui concerne un même métier et on limite les dépendances entre ces groupes. Chacun forme un domaine : un ensemble cohérent d’informations, de règles et d’opérations. Le catalogue en est un. Produits, variantes (la basket en 42, coloris bleu) et options (la taille, la couleur) sont distincts, mais certaines règles du catalogue les concernent ensemble : une variante doit fournir une valeur pour chaque option de son produit. Les prix obéissent à d’autres contraintes, comme les soldes, les devises ou les tarifs professionnels.

Le développeur trace ces frontières, en suivant des critères précis. Il regroupe ce qui est fortement lié et évolue ensemble. Il sépare les responsabilités qui ont des raisons de changer différentes : la description d’une basket reste la même quand son prix baisse pour les soldes. Ce contour suit l’activité. Un écran peut mobiliser plusieurs modules, et un module regroupe souvent plusieurs tables.

Dans Medusa, le module concrétise ces frontières. Il garde ses données et ses règles internes, et le reste de l’application passe par son service principal, qui expose ses opérations. Pricing et Product sont deux modules distincts : faire évoluer les règles de prix ne suppose pas de réécrire Product. Les lecteurs familiers du Domain-Driven Design (DDD) reconnaîtront une idée de cette approche, qui modélise le métier pour en borner la complexité.

La maintenance y gagne. On comprend un domaine en lisant son module, on sait où chercher une règle, et une modification reste dans des limites connues, ce qui réduit les effets de bord. Des dépendances subsistent entre modules, et un bon découpage demande toujours du jugement. Il donne surtout à chaque changement un endroit précis où se faire.

Reste à voir ce qu’un domaine contient concrètement. Pour cela, un exemple plus petit qu’un catalogue suffit.

Un domaine à deux entités : la réparation

Imaginons un module Repair. Il n’existe pas dans Medusa : c’est un exemple, assez petit pour en comprendre les pièces. Notre boutique propose de réparer les paires abîmées, semelle décollée ou couture ouverte, et doit suivre ces réparations.

Le suivi repose sur deux sortes d’entités. La demande de réparation (RepairRequest) décrit le problème signalé et son état : ouverte, puis prête. L’intervention (RepairIntervention) décrit un travail effectué pour cette demande, comme recoller la semelle ou reprendre la couture, et indique s’il est terminé. Une demande de réparation peut donner lieu à plusieurs interventions ; chaque intervention se rattache à une seule demande. C’est une relation « un à plusieurs », qu’on note 1 → N.

Une demande, plusieurs interventions

Module Repair

Atelier de réparation, module Repair

RepairRequest

req_01

problem
« semelle décollée »
status
open

1 demande

RepairIntervention

int_01terminée

description
« recoller la semelle »
completed
true
request_id
req_01

int_02non terminée

description
« reprendre une couture »
completed
false
request_id
req_01

N interventions

Valeurs illustratives. La demande parente req_01 garde son identifiant ; chaque intervention enfant y renvoie par request_id.

Pour chaque sorte d’entité, un modèle décrit les champs disponibles et leurs types. L’entité concrète, c’est une demande de réparation précise, par exemple celle de la semelle décollée signalée mardi. Elle porte un identifiant stable, qui permet de la retrouver et de la désigner sans ambiguïté. Le modèle s’écrit une fois ; les entités concrètes s’accumulent ensuite dans la base.

Pourquoi réunir ces deux entités dans un même module ? Parce qu’une intervention n’a pas de sens hors de sa demande de réparation, et que toutes deux obéissent aux règles du suivi des réparations. C’est le critère de regroupement appliqué à un cas minuscule. Leur relation reste donc interne au module : en base, elle prendra la forme d’une clé étrangère SQL entre deux tables du même domaine.

Ce module hypothétique utilise les mêmes outils que les modules natifs de Medusa. Ceux-ci sont bien plus riches et ne se réduisent pas à cet exemple, mais leur anatomie repose sur les mêmes pièces. La première sert à décrire les données.

Décrire les données une seule fois

Medusa décrit les données avec son propre langage de modélisation, le DML (Data Model Language). Voici les deux modèles du module Repair :

import { model } from "@medusajs/framework/utils"

export const RepairRequest = model.define("repair_request", {
  id: model.id().primaryKey(),
  problem: model.text(),
  status: model.enum(["open", "ready"]).default("open"),
  interventions: model.hasMany(() => RepairIntervention, {
    mappedBy: "request",
  }),
})

export const RepairIntervention = model.define("repair_intervention", {
  id: model.id().primaryKey(),
  description: model.text(),
  completed: model.boolean().default(false),
  request: model.belongsTo(() => RepairRequest, {
    mappedBy: "interventions",
  }),
})

Chaque modèle reçoit un nom, puis ses propriétés : un identifiant et des champs typés (un texte, une valeur choisie dans une liste, un booléen). Les dernières propriétés déclarent la relation des deux côtés. hasMany indique qu’une demande de réparation possède plusieurs interventions, belongsTo qu’une intervention appartient à une demande. L’option mappedBy relie les deux déclarations en donnant, de chaque côté, le nom de la propriété inverse.

Ce langage n’est pas réservé aux extensions. Les modules natifs sont écrits de la même manière : le modèle Product de Medusa commence lui aussi par model.define.

Que produit cette description ? D’abord une définition pour l’ORM. Un ORM (object-relational mapping) est la couche qui fait correspondre les objets manipulés dans le code aux lignes des tables d’une base relationnelle ; Medusa s’appuie sur MikroORM. Grâce aux modèles, l’ORM sait lire et enregistrer une demande de réparation ou une intervention.

Ensuite, des migrations. Une migration est un script qui fait évoluer la structure de la base : créer une table, ajouter une colonne. Medusa permet de les générer à partir des modèles ; on les applique ensuite explicitement, et rien ne modifie la base à votre insu. Pour notre relation, la migration ajoute à la table des interventions une colonne request_id, qui contient l’identifiant de la demande de réparation, et une clé étrangère qui garantit que cette colonne désigne bien une demande existante. Quand on ajoute un champ au modèle, on génère une nouvelle migration, puis on l’applique de la même façon.

Enfin, des types TypeScript. Plutôt que de recopier la structure dans une interface séparée, on la déduit du modèle :

import { InferTypeOf } from "@medusajs/framework/types"

type RepairRequestType = InferTypeOf<typeof RepairRequest>

Le type suit le modèle : si un champ change, le type change avec lui.

Des modèles à la base de données

Modèles DML

RepairRequest RepairIntervention

Définitions ORM, types et migrations

Type TypeScript

InferTypeOf<typeof RepairRequest>

Raccord ORM

objets↔lignes

Migrations

  1. Générer la migration
  2. Appliquer la migration
  3. Tables
repair_request
idproblemstatus
req_01semelle décolléeopen
1 N request_id → repair_request.id
repair_intervention
iddescriptioncompletedrequest_id
int_01recoller la semelletruereq_01
int_02reprendre une couturefalsereq_01
Les modèles DML fournissent les définitions ORM, les types et les migrations ; c’est l’application des migrations qui crée les tables SQL, reliées par request_id.

Une limite doit être dite nettement. Le DML seul ne crée pas de base vivante, puisque les migrations doivent encore être appliquées. Surtout, la description n’expose encore aucune méthode de gestion à l’application : rien ne lui permet de créer une demande de réparation ni de lister ses interventions. C’est le service qui se charge d’offrir ces opérations.

Du modèle au service : la Service Factory

Dans un module Medusa, les opérations passent par un service, c’est-à-dire une classe qui regroupe ce qu’on peut faire avec les données du domaine. Écrire à la main la création, la lecture, la modification et la suppression de chaque entité serait long et répétitif. Medusa fournit pour cela une Service Factory : une fonction, MedusaService, qui fabrique la base d’un service à partir des modèles qu’on lui confie.

class RepairModuleService extends MedusaService({
  RepairRequest,
  RepairIntervention,
}) {}

Ces quelques lignes donnent au service principal du module des méthodes de gestion pour chacun des deux modèles, intervention comprise. Ce sont les opérations dites CRUD : créer, lire, modifier, supprimer (create, read, update, delete).

OpérationDemande de réparationIntervention
CréercreateRepairRequestscreateRepairInterventions
ListerlistRepairRequestslistRepairInterventions
Lire un élémentretrieveRepairRequestretrieveRepairIntervention
ModifierupdateRepairRequestsupdateRepairInterventions
SupprimerdeleteRepairRequestsdeleteRepairInterventions

Les noms suivent une règle simple : l’opération, puis le nom du modèle, au pluriel sauf pour retrieve, qui lit un seul élément. Ce tableau présente les opérations principales ; la Factory en génère quelques autres, par exemple pour compter des résultats ou rendre une suppression réversible.

La Factory crée aussi un service interne par modèle, repairRequestService et repairInterventionService, dont les méthodes portent des noms courts : create, list, retrieve, update, delete. Ces services restent à l’intérieur du module. L’application passe par le service principal.

Le module désigne une fois son service principal. Les méthodes de gestion générées et les méthodes publiques que le développeur ajoute à ce service sont alors accessibles à l’application, sans déclaration d’exposition méthode par méthode. L’application choisit celles qu’elle appelle. Cette disponibilité dans le code ne crée pas automatiquement de routes HTTP.

La Factory fournit le service

RepairRequest RepairIntervention
MedusaService(…)

Module Repair

Atelier de réparation, module Repair

RepairModuleService

service principal

  • gestion des demandes
  • gestion des interventions

services internes

repairRequestService gère RepairRequest
repairInterventionService gère RepairIntervention

Application

appelle uniquement le service principal

MedusaService produit à partir des deux modèles le service principal RepairModuleService et ses services internes ; le reste de l’application ne passe que par le service principal.

Les rôles restent bien séparés. Les tables, la relation SQL et les types proviennent des modèles DML ; les méthodes et les services proviennent de la Factory. Là encore, Medusa applique ce mécanisme à lui-même : le service du module Product étend MedusaService avec ses propres modèles.

Le module sait désormais créer, lire, modifier et supprimer des demandes de réparation et des interventions. Il ne sait pas encore quand une réparation est prête.

Les règles métier du module

Dans cet atelier, choisissons une règle simple : une demande de réparation est prête quand elle compte au moins une intervention et que toutes ses interventions sont terminées. Une telle règle ne se déduit d’aucun modèle : elle appartient au métier de la boutique. C’est donc au développeur de l’écrire, sous la forme d’une méthode ajoutée au service principal, markReady(requestId).

Son déroulement tient en quelques gestes. La méthode charge la demande de réparation avec ses interventions, grâce à la relation déclarée dans le DML. Si la demande n’a aucune intervention, elle refuse. Si une seule intervention n’est pas terminée, elle refuse aussi et dit pourquoi. Sinon, elle passe la demande à l’état prêt.

Cette règle traverse deux entités, mais elle reste entièrement dans le même domaine : la demande et ses interventions sont deux faces du suivi des réparations. Elle n’a besoin d’aucun autre module.

Le service principal porte maintenant deux familles d’opérations côte à côte. Les méthodes générées par la Factory gèrent les données ; la méthode métier applique une règle. Ajouter markReady ne masque ni ne remplace updateRepairRequests : les deux restent disponibles sur la même interface, et la Factory ne choisit pas pour vous lesquelles exposer. Un appel direct à updateRepairRequests pourrait donc passer une demande à l’état prêt sans rien vérifier. Pour cette action, l’application doit appeler markReady.

Deux appels, une règle métier

Module Repair · même service principal

Application

Voie métier

markReady(req_01)

Contrôle

Au moins une intervention, toutes terminées

Résultat actuel : refus

int_02 non terminée

status reste open

Si toutes terminées

status → ready

Méthode générée, toujours accessible

updateRepairRequests

Écriture directe

status → ready

sans vérifier les interventions

Le service expose côte à côte la méthode métier markReady, qui contrôle les interventions avant de changer le statut, et la méthode générée updateRepairRequests, qui reste accessible et écrit directement.

Le partage du travail apparaît ici clairement. Le framework fournit le socle : persistance, migrations, types, opérations de gestion. Le développeur garde ce qui fait la valeur de son domaine, ses règles. Il reste du code à écrire, mais c’est celui qui compte.

Étendre Medusa à son métier

Medusa fournit le moteur e-commerce : catalogue, prix, stock, commandes et paiements. Un module propre y ajoute les données, les états, les règles et les opérations d’une activité : des contrats, des échéances et des renouvellements pour des souscriptions ; des demandes, des interventions et leurs statuts pour un service de réparation ; des dépôts et des relevés de ventes pour le dépôt-vente.

Le framework prend en charge la structure : le DML définit les modèles de données, et la Factory génère les méthodes courantes pour les créer, les lire, les modifier et les supprimer. Le développeur écrit la logique métier : les règles, les contrôles et les opérations propres à son activité.

À partir de ce moteur, on peut développer des services métier autour de la vente, construire progressivement un outil de gestion proche d’un ERP, ou une application SaaS spécialisée pour un secteur. Il restera ensuite à comprendre comment ces modules peuvent fonctionner ensemble.

Un sujet à creuser ? Ajoutez cet article à votre discussion office hours.

Voir ma discussion