Basket Management

Basket management provides a consistent way to preserve cart state across the server and client while removing the need to fetch or create a basket on every request. Our React Router middleware stores a snapshot of the current basket as a cookie, enabling the basket ID and item count to persist across page refreshes. Full basket state hydration is performed lazily, which helps keep page loads fast.

Here’s an overview of the basket management process.

1. Middleware initializes context with a cookie snapshot on every request.
2. Root loader passes the snapshot into the BasketProvider without hydrating the full basket.
3. Client components hydrate lazily via useBasket() when full basket data is required.
4. Middleware updates or deletes the cookie based on the final basket state after loaders or actions finish.

The server-side middleware is the source of truth for basket state and cookie management.

createBasketMiddleware accepts these optional settings.

• mode: 'lazy' (default) or 'eager' hydration.
• cookieName: Override the basket cookie name (default __sfdc_basket).
• cookieDurationRegistered: Cookie duration (TTL) in ms for registered shoppers.
• cookieDurationGuest: Cookie duration (TTL) in ms for guest shoppers.
• currency: Currency used when creating a basket.
• calculateBasketSnapshot: Add custom fields to the cookie snapshot.

Context value:

• basketResourceContext: snapshot, basket, hydration state, and error.

Modes:

• lazy (default): Only the snapshot is set. Full basket is fetched on demand.
• eager: Middleware hydrates basket before calling next().

Cookie snapshot characteristics: The cookie snapshot:

• Is stored in __sfdc_basket.
• Includes basketId, totalItemCount, and uniqueProductCount.
• Contains optional custom fields via calculateBasketSnapshot.

Here’s a minimal cookie snapshot configuration for the default lazy mode.

Use these helpers in loaders or actions (server) to interact with the request-scoped basket.

BasketProvider keeps basket data in React context for the client. It receives the snapshot from the root loader, exposes lazy hydration, and updates through hooks.

BasketProvider accepts:

• snapshot: Cookie-safe basket snapshot for initial render.
• basket: Full basket payload (optional, for eager client hydration).

The provider stores:

• snapshot: Cookie-safe basket summary.
• current: Full basket payload (when hydrated).
• hydrated: Whether hydration has been attempted.
• error: Hydration error info (if any).

The root loader intentionally passes only basketSnapshot to avoid eager basket creation.

useBasket() triggers a client-side fetch when:

• A snapshot exists (has basketId).
• No full basket is yet in context.

Use these hooks in client components after mutations or checkout completion. Common use cases include sharing updated basket data across the React app and clearing basket state after order completion. You typically call useBasketUpdater after basket actions, such as adding or removing items, or applying or removing promotions. Updates aren’t automatically inferred from route loaders because of the default lazy behavior.

Use these options only when needed.

1. Eager hydration: Set mode: 'eager' if a route always needs a full basket.
2. Custom snapshot fields: Add metadata (for example, pickup flags) via calculateBasketSnapshot.
3. Force refresh: Call getBasket(context, { ensureBasket: true }) to hydrate server-side before action logic that requires a full basket.

Example custom snapshot: