Basket Management Differences with PWA Kit

PWA Kit and Storefront Next rely on the Shopper Baskets API, but they differ in where basket state is managed and how it is hydrated in the app lifecycle. PWA Kit commonly uses hook-driven basket reads and mutations in components, while Storefront Next uses middleware, request context, and route loaders and actions to manage basket state with a server-first model.

Architecture

Aspect	PWA Kit	Storefront Next
Basket API baseline	Shopper Baskets V1 is available and remains the default for many existing imports	Basket flows are implemented with `shopperBasketsV2` patterns in loaders/actions
Primary integration model	`@salesforce/commerce-sdk-react` hooks in components	Middleware + request context + route loaders/actions
Basket state location	React Query cache and component hook state	Cookie snapshot on the server plus optional client hydration in provider state
Hydration strategy	Data fetched when basket hooks run in UI	Lazy by default: hydrate full basket only when required

Request and State Lifecycle

Phase	PWA Kit	Storefront Next
Initial request	Basket data is typically fetched through basket hooks used by rendered components	Middleware reads basket cookie snapshot and attaches it to request context
Basket creation/access	Hook and mutation flows resolve or create basket during shopper actions	`ensureBasketId` and server helpers manage basket identity in loaders/actions
Client updates	Mutations update React Query caches and UI state	Actions update server resource context; client can sync through provider updater hooks
Post-checkout cleanup	App-specific hook/mutation flows clear basket	`destroyBasket()` and provider reset hooks clear server/client basket state

Migration Considerations

When moving basket functionality from PWA Kit to Storefront Next:

Move basket reads out of components and into route loaders when possible.
Move basket mutations to route actions and update request-scoped basket context.
Treat basket cookie snapshot data as the default source for lightweight UI state (for example, cart badge counts).
Use lazy hydration for full basket payloads only in routes or components that require full basket detail.
Keep basket API usage consistent across the codebase to avoid stale or mismatched basket state behavior.

Key Similarities

Both storefronts use SCAPI basket endpoints for cart operations.
Both support guest and authenticated shopper basket flows.
Both can preserve basket continuity across shopper navigation.

References

Shopper Baskets V1 API Reference
sfnext-basket-management