SAP Commerce (OCC) integration
The @archibald/commerce package is Archibald's SAP Commerce (Hybris) integration. The framework's commerce packages (@archibald/cart, @archibald/cms, @archibald/product, @archibald/search, @archibald/auth, @archibald/quotes) are headless and backend-neutral — they define the clients, hooks and server modules. This package plugs SAP Commerce into those contracts by providing, per domain:
- an adapter — the client-side piece a feature client is configured with; it shapes requests against your BFF API,
- a provider — the server-side piece a feature module is registered with; it translates the request into OCC v2 calls,
- a mapper — the translation layer that turns Hybris response structures into the standardized storefront interfaces (and the seam to extend when your Hybris carries custom fields).
The same wiring works on Web (SSR/browser) and Mobile (React Native/Expo).
The domains
Each domain lives behind its own subpath export — import from @archibald/commerce/<feature>, never from the package root, so unused domains stay out of your bundle. Every page carries a how-to and the API surface:
| Domain | Subpath | Client side | Server side |
|---|---|---|---|
| Cart | @archibald/commerce/cart | CommerceCartAdapter, prebuilt CommerceCart factory, hooks | CommerceCartProvider |
| CMS | @archibald/commerce/cms | CommerceCMSAdapter (SmartEdit-aware) | CommerceCMSProvider |
| Product | @archibald/commerce/product | typed OCC product interfaces | CommerceProductProvider, CommerceProductMapper |
| Search | @archibald/commerce/search | CommerceSearchAdapter, search/facet interfaces | CommerceSearchProvider, CommerceSearchMapper |
| Authentication | @archibald/commerce/auth | CommerceUser interfaces | CommerceUserAuthProvider, CommerceStaticAuthProvider |
| Quotes | @archibald/commerce/quotes | CommerceQuote interfaces | CommerceQuotesProvider + quote services |
| B2B | @archibald/commerce/b2b | B2B unit / cost-center interfaces | CommerceB2B{Users,Carts,CostCenters}Service |
The root export (@archibald/commerce) carries only what is shared across domains: common interfaces and schemas (CommerceAddress, CommerceOrderEntry, CommerceComment, …) and the CommerceImageProxyModule, which forwards /medias/* to the commerce host and injects app.image.headers.server so media behind an access gateway stays reachable from the browser.
How to use
Install once, then wire only the domains you need — each page above shows its pair:
pnpm add @archibald/commerce
// server: src/{platform}/server/module/server.tsx — one module per domain, from the shop template
new CMSModule({ provider: new CommerceCMSProvider({ config: () => this.configService.get('hybris.api') }) }),
new SearchModule({ provider: new CommerceSearchProvider({ config: () => this.configService.get('hybris.api') }) }),
new ProductModule({ provider: new CommerceProductProvider({ config: () => this.configService.get('hybris.api') }) }),
new CommerceImageProxyModule()
Every provider reads the same config seam: the hybris block of your environment config (hybris.api — host, base site, OCC paths; hybris.oauth — the OAuth client for authentication).
Related guides
The generic feature architecture — clients, adapters, providers, hooks — is documented per feature under the guides; these pages document the SAP-Commerce-specific halves: