Skip to content
EvolveEvolveEvolve

sfcc

@evolve-framework/sfcc · v1.0.0

The Salesforce Commerce Cloud (B2C Commerce) engine for Evolve: modules that serve the shared GraphQL contract from the Shopper APIs of an SFCC site.

When to use

Use it when Salesforce Commerce Cloud is your commerce engine. A service composes the modules it needs, from CatalogModule and CartModule to checkout, orders, payments and quotes. It is the counterpart of the commercetools and Medusa engines, so a service uses exactly one of them.

It covers less of the contract than the commercetools engine:

  • Business units and shopping lists are in the schema but answer "Not implemented yet". So do sign-up and changes to a customer account: its addresses, information, password (reset included), email and deletion.
  • Order approvals do not exist on Commerce Cloud. OrderApprovalModule keeps the schema complete: its queues and rules are empty, and every decision or rule change is refused with an UNSUPPORTED validation error.
  • These operations have no resolver at all, so they answer null, or an error where the field is required: createGuestSession, addressValidate, cartSetDeliveryRemarks, customerDefaultAddressUpdate, customerPersonalDetailsUpdate, customerNotificationPreferencesUpdate, orderByPublicId, quoteRequestCreate, quoteRequestCancel, the business-unit address mutations, and businessUnitAssociateActivate and businessUnitAssociateDeactivate.

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/sfcc @evolve-framework/core @labdigital/federated-token fastify graphql zod
    Requirements6
    @evolve-framework/core>= 1.0.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
    zod>= 4.4.0 < 5.0.0

For example:

import { CompositeModule } from "@evolve-framework/core";
import {
  ClientFactory,
  CommerceCloudConfig,
  getClientOptions,
  type SfccLoaderContext,
} from "@evolve-framework/sfcc";
import { CartModule, CatalogModule } from "@evolve-framework/sfcc/modules";


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


// Typed with what the modules' loaders read from the request context.
const module = new CompositeModule<SfccLoaderContext>([
  new CatalogModule({ clientFactory }),
  new CartModule(),
]);

Modules

ModuleServesRequired options
AuthModuleAuthenticationconfig, clientFactory
BusinessUnitModuleBusiness units–
CartModuleCart–
CatalogModuleCatalogclientFactory
CheckoutModuleCheckout–
CustomerModuleCustomer–
OrderApprovalModuleOrder approval–
OrderModuleOrder–
PaymentModulePayment–
QuoteModuleQuote–
ShoppingListModuleShopping lists–

Configuration

CommerceCloudConfig reads 5 environment variables. See which

Entry points

@evolve-framework/sfccThe SFCC client and its configuration (SFCC_*), the request and store context, and the dataloaders.30 exports
@evolve-framework/sfcc/authShopper login and the token manager behind guest and registered sessions.7 exports
@evolve-framework/sfcc/dataloadersThe request-scoped dataloaders for products, categories, customers and orders.9 exports
@evolve-framework/sfcc/modulesThe modules: auth, business units, cart, catalog, checkout, customers, orders, order approvals, payments, quotes and shopping lists.12 exports