Skip to content
EvolveEvolveEvolve

medusa

@evolve-framework/medusa · v1.0.0

The Medusa v2 engine for Evolve: modules that serve the same GraphQL contract as @evolve-framework/commercetools from Medusa's Store API, so a storefront cannot tell which engine is behind the graph.

When to use

Use it when Medusa is your commerce engine. A service composes the modules it needs, from CatalogModule and CartModule to orders, payments, customers, business units, quotes, order approvals and shopping lists. It reads the Store API with a publishable key only and holds no admin credentials. It is the counterpart of the commercetools and SFCC engines, so a service uses exactly one of them.

Get started

  1. Install the package with the peer dependencies it needs. It comes from the Evolve registry, which needs a one-time sign-in.

    pnpm add @evolve-framework/medusa @evolve-framework/core @labdigital/federated-token fastify graphql zod
    Requirements7
    @evolve-framework/core>= 1.8.0 < 2.0.0
    @labdigital/federated-token>= 3.0.0 < 4.0.0
    @types/node>=22optional
    fastify>= 5.12.1 < 6.0.0
    graphql>= 16.0.0 < 17.0.0
    msw^2.14.6 || ^3.0.1optional
    zod>= 4.4.0 < 5.0.0

For example:

import { CompositeModule } from "@evolve-framework/core";
import {
  ClientFactory,
  getClientOptions,
  MedusaConfig,
} from "@evolve-framework/medusa";
import { CartModule, CatalogModule } from "@evolve-framework/medusa/modules";


const config = await MedusaConfig.load();
const clientFactory = new ClientFactory();
clientFactory.configure(getClientOptions(config));


const module = new CompositeModule([new CatalogModule(), new CartModule()]);

Modules

ModuleServesRequired options
AuthModuleAuthentication–
BusinessUnitModuleBusiness units–
CartModuleCart–
CatalogModuleCatalog–
CheckoutModuleCheckout–
CustomerModuleCustomer–
DeliveryOptionsModuleDelivery optionsprovider
EventsModuleThe route @evolve-framework/medusa-plugin-events posts to, publishing the shared product and category events for what it forwards, so a CMS and a search index follow a Medusa catalog as they follow commercetools.clientFactory, messagePublisher, origin
GiftCardModuleGift card–
InvoiceModuleInvoice–
MultipleCartModuleMultiple carts–
OrderApprovalModuleOrder approval–
OrderModuleOrder–
PaymentModulePayment–
QuoteModuleQuote–
ShoppingListModuleShopping lists–

Adapters

AdapterWhat it isRequired options
MedusaSearchQueryAdapterProduct search answered by Medusa's own Search module, through POST /store/search, against the index @evolve-framework/medusa-plugin-search declares.–

Configuration

MedusaConfig reads 3 environment variables. See which

Testing

Test helpers in /cleanup, /testing. What they are for

Commands

Installing this package adds these commands to the evolve CLI.

  • evolve cleanup: Development only. Delete what end-to-end runs left behind

Entry points

@evolve-framework/medusaThe Medusa client and its configuration, the request context, error mapping and slug helpers.40 exports
@evolve-framework/medusa/dataloadersThe request-scoped dataloaders the modules read products, categories and slugs through.5 exports
@evolve-framework/medusa/modulesThe modules: auth, business units, cart, catalog, checkout, customers, orders, order approvals, payments, quotes and shopping lists, and the route that turns Medusa's catalog events into internal events.16 exports
@evolve-framework/medusa/searchThe product source a search index is built from, and a search provider for the catalog.4 exports
@evolve-framework/medusa/sitemapThe product source for sitemap generation.1 export
@evolve-framework/medusa/cleanupTest-data cleanup through Medusa's admin API, for the command line and a test-support service.8 exports
@evolve-framework/medusa/testingA test client and mocked Store API handlers, for testing against Medusa without a server.5 exports