Modular Cart System
Relevant source files
The following files were used as context for generating this wiki page:
The Modular Cart System is a framework-agnostic, multi-package architecture designed to provide a unified cart experience across different commerce providers (primarily Shopify). It replaces legacy storefront-specific cart implementations with a set of dedicated packages that handle everything from state management and optimistic UI to server-side persistence and provider-specific network calls.
The system is structured into a kernel-adapter pattern where the core logic remains independent of the underlying commerce platform. This allows the storefront to maintain a consistent API while delegating the complexities of specific provider APIs—such as Shopify's GraphQL mutations—to specialized adapters.
Sources: CONTEXT.md:277-285, packages/cart/core/README.md:1-10, README.md:183-188
Core Architecture and Components
The architecture relies on a "Cart Kernel" that wires together various functional modules. This kernel acts as the central orchestrator for mutations, events, and state resolution.
Architectural Overview Diagram
The following diagram illustrates the relationship between the host application, the cart kernel, and the commerce provider.
Sources: CONTEXT.md:295-303, CONTEXT.md:364-370
Component Definitions
| Component | Description |
|---|---|
| Cart Kernel | The central object that wires the adapter, middleware, predictors, and event bus. One kernel exists per host process. |
| Cart Adapter | Provider-specific implementation (e.g., Shopify) that owns network calls and normalizes data to the canonical Cart shape. |
| Transport | A host-supplied function bag that performs actual HTTP/GraphQL calls for an Adapter, threading tenant context. |
| Cart Mutation | A typed object (intent) describing a change, such as add-line or clear. |
| Mutation Queue | A client-side ordered list of pending mutations awaiting server confirmation, strictly serialized. |
Sources: CONTEXT.md:295-325, packages/cart/core/CHANGELOG.md:21-23
State Management and Prediction
The system utilizes an optimistic UI strategy through "Predictors" to ensure the interface feels instantaneous even while awaiting server responses.
Predictor Types
- Line Predictor: Synthesizes a predicted cart line (e.g., when adding an item). It uses first-non-null-wins logic. Built-ins include
snapshotPredictorandcachePredictor. - Cart Predictor: Transforms the projected cart after mutations. These run in a registered sequence. Examples include
quantitySumPredictorandsubtotalPredictor.
Sources: CONTEXT.md:335-344, CONTEXT.md:444-448
Predictive Flow Sequence
This diagram shows how a user interaction triggers a prediction before the server confirms the change.
Sources: CONTEXT.md:331-334, CONTEXT.md:364-370
Integration and Persistence
The system is designed to integrate deeply with Next.js and Shopify while remaining decoupled from specific authentication or storage libraries.
Key Integration Interfaces
- Cart-ID Storage: A server-side interface for persisting cart identifiers. The Next.js implementation uses
httpOnlyCookieStorage. - Auth Bridge: Glue between the cart system and the host's authentication (e.g., NextAuth). It resolves Buyer Identity on the server and subscribes to session changes on the client.
- Buyer Identity: Represents who is checking out, including email, phone, and opaque provider-specific session tokens (like Shopify's
customerAccessToken).
Sources: CONTEXT.md:317-325, CONTEXT.md:351-356, packages/cart/next/CHANGELOG.md:14-18
Capabilities and Customization
Adapters declare their Capabilities, such as support for giftCards, notes, or multipleDiscountCodes. This drives type narrowing in the React layer, specifically for the useCartActions() hook. Additionally, adapters can expose Custom Mutations (e.g., subscribeFrequency) that are listed in their capabilities.
Sources: CONTEXT.md:304-310, CONTEXT.md:326-330
Package Ecosystem
The system is distributed across several specialized workspace packages:
| Package | Purpose |
|---|---|
@nordcom/cart-core | Framework-agnostic kernel, types, adapter contracts, and money helpers. |
@nordcom/cart-react | React 19 provider, mutation queue, and <CartForm> primitive. |
@nordcom/cart-next | Next.js 16 specific implementations like cookie storage and server-action factories. |
@nordcom/cart-shopify | The Shopify-specific adapter that interacts with the Storefront API. |
Sources: CONTEXT.md:434-443, packages/cart/core/README.md:1-10, packages/cart/react/CHANGELOG.md:19-24
Summary
The Modular Cart System provides a scalable architecture for e-commerce carts by separating the core business logic from framework-specific and provider-specific implementations. Through the use of a Cart Kernel, optimistic predictors, and a strictly serialized mutation queue, it ensures a high-performance, resilient user experience that remains consistent regardless of the underlying commerce backend.