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