Skip to content
EvolveEvolveEvolve

commercetools

@evolve-framework/commercetools · v1.0.0

The commercetools engine for Evolve: modules that serve the shared GraphQL contract from a commercetools project, from the catalog, cart and checkout to orders, payments, customers, business units, quotes, order approvals, shopping lists and invoices.

When to use

Use it when commercetools is your commerce engine. A service composes the modules it needs, such as a catalog service with CatalogModule and a purchase service with CartModule, CheckoutModule and OrderModule. It pairs with the commercetools-* payment adapters, with search-algolia or search-meilisearch for product search, and with a CMS package. It is the counterpart of @evolve-framework/medusa and @evolve-framework/sfcc, so a service uses exactly one engine.

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/commercetools @commercetools/platform-sdk @evolve-framework/core @labdigital/federated-token @opentelemetry/api fastify graphql graphql-yoga zod
    Requirements12
    @commercetools/platform-sdk>=9.0.0
    @evolve-framework/core>= 1.10.0 < 2.0.0
    @labdigital/commercetools-mock>= 5.0.1, < 6.0.0optional
    @labdigital/federated-token>= 3.0.0 < 4.0.0
    @opentelemetry/api^1.9.0
    @types/node>=22optional
    fastify>= 5.12.1 < 6.0.0
    graphql>= 16.0.0 < 17.0.0
    graphql-yoga>= 5.21.3 < 6.0.0
    msw^2.14.6 || ^3.0.1optional
    vitest>= 4.0.0 < 6.0.0optional
    zod>= 4.4.0 < 5.0.0

For example:

import {
  CartModule,
  CatalogModule,
  ClientFactory,
  type CommercetoolsLoaderContext,
  CommercetoolsConfig,
  getClientOptions,
} from "@evolve-framework/commercetools";
import { CompositeModule } from "@evolve-framework/core";


const config = await CommercetoolsConfig.load();
const clientFactory = ClientFactory.create(await getClientOptions(config));


// Typed with what the modules' loaders read from the request context.
const module = new CompositeModule<CommercetoolsLoaderContext>([
  new CatalogModule({ clientFactory }),
  new CartModule({
    clientFactory,
    // The keys of the custom types your project provisioned
    customTypes: { order: "order", "line-item": "line-item" },
  }),
]);

Modules

ModuleServesRequired options
ApiExtensionModulecommercetools API extensions as a module: the extensions, the client they read with, and the route they answer on, composed like every other capability rather than wired by hand in each project.extensions, clientFactory
AuthModuleAuthentication–
BackInStockModuleBack in stock–
BusinessUnitModuleBusiness units–
CartModuleCartclientFactory, customTypes
CatalogModuleCatalogclientFactory
CheckoutModuleCheckoutclientFactory
CustomerModuleCustomerconfig, customTypes
DeliveryOptionsModuleDelivery optionscustomTypes, provider
InvoiceModuleInvoice–
MultipleCartModuleMultiple cartscustomTypes
OrderApprovalModuleOrder approval–
OrderModuleOrderclientFactory
PaymentModulePaymentclientFactory, customTypes
PaymentProviderModuleHosts a PaymentAdapter as a Domain Service — the server side of the remote bridge.adapter
ProductReviewModuleProduct review–
QuoteModuleQuote–
ReturnModuleReturnclientFactory, customTypes, carrier
ShoppingListModuleShopping lists–
GiftCardModuleGift cardstore

Adapters

AdapterWhat it isRequired options
BasePaymentAdapterBase class for in-process payment providers.–
RemotePaymentAdapterA PaymentAdapter that forwards every call over HTTP to a remote payment service (one hosting the real adapter behind a RemotePaymentPublisher).–
GiftCardPaymentAdapterPaying with a gift card, a partial method: it covers the smaller of the card's balance and what is left to pay, and several cards can sit on one cart beside the method that pays the rest.clientFactory, store

Configuration

CommercetoolsConfig reads 9 environment variables. See which

Testing

Test helpers in /testing, /factories, /simulation, /cleanup, /test-support. 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
  • evolve simulate: Development only. Write what an ERP, a warehouse and a merchant would

Entry points

@evolve-framework/commercetoolsThe modules, the commercetools client and its configuration, the request context and dataloaders, the subscription handler that turns commercetools events into internal events, the one that keeps an order's payment state in line with its payments, and the one that tells a buyer a quote is ready.123 exports
@evolve-framework/commercetools/api-extensionBuilding blocks for commercetools API extensions, and ready-made ones such as order numbers, default shipping and the EU VAT rules.24 exports
@evolve-framework/commercetools/catalogThe product source a search index is built from, and the mapper from products to search documents.19 exports
@evolve-framework/commercetools/sitemapThe product source for sitemap generation.1 export
@evolve-framework/commercetools/algoliaHelpers that write products straight to an Algolia index; @evolve-framework/search-algolia with the catalog source is the replacement.19 exports
@evolve-framework/commercetools/paymentsThe payment adapter contract and registry that payment packages implement, and the remote adapter that reaches a payment service over HTTP.26 exports
@evolve-framework/commercetools/gift-cardPaying with gift cards, a partial method: GiftCardPaymentAdapter, the giftCardBalance query in GiftCardModule, and the GiftCardStore they are written against with its reference implementation, CustomObjectGiftCardStore, which keeps cards as custom objects with a hashed PIN.11 exports
@evolve-framework/commercetools/shopping-listShopping list reads, writes and mappers, for a project extending shopping lists.18 exports
@evolve-framework/commercetools/product-specificationsZod schemas for typed product specifications (text, number, date, enum and the like), and a helper to read one off a product.27 exports
@evolve-framework/commercetools/testingA mocked commercetools project, test clients and tokens, the custom types and payment states a test project needs, and describePaymentAdapterContract, the scenarios every payment adapter meets.17 exports
@evolve-framework/commercetools/factoriesFactories that create carts, orders, customers, products and other resources in that mocked project.23 exports
@evolve-framework/commercetools/simulationWrite what a back office would: confirm, ship and deliver orders, raise and pay invoices, and answer quote requests.37 exports
@evolve-framework/commercetools/cleanupRemove what an end-to-end run created: orders with their payments, carts, quote requests, generated business units, memberships and customers, refusing anything that is not test data.10 exports
@evolve-framework/commercetools/test-supportThe commercetools handlers for the test-support service in @evolve-framework/core/test-support.2 exports