API Integration Differences with PWA Kit

While both PWA Kit and Storefront Next use SCAPI for commerce functionality, they take fundamentally different approaches to API client architecture.

Architecture

Aspect	PWA Kit	Storefront Next
Package	`@salesforce/commerce-sdk-react`	`@salesforce/storefront-next-runtime/scapi`
Underlying Client	`commerce-sdk-isomorphic`	`openapi-fetch`
Pattern	React hooks	Direct API calls
Type Generation	Manual TypeScript	Generated from OpenAPI specs
Bundle Size	Larger (includes React Query + SDK)	Smaller (lightweight client)

API Call Location

Aspect	PWA Kit	Storefront Next
Reads (GET)	Inside components via hooks	In route loaders
Writes (POST/PUT)	Inside components via mutation hooks	In action routes
Authentication	Automatic via provider	Manual via middleware

Client Initialization

Aspect	PWA Kit	Storefront Next
When	Once at app root	Per-request in loaders/actions
Where	`CommerceApiProvider`	`createApiClients()` helper
Auth	Automatic token management	Middleware injects tokens

Caching

Aspect	PWA Kit	Storefront Next
Strategy	React Query cache	React Router revalidation
Invalidation	Automatic after mutations	Manual or via `shouldRevalidate`
Stale Time	Configurable (default 10s)	No built-in stale time

Code Examples Comparison

Fetching a product:

// PWA Kit - in component
const { data: product, isLoading } = useProduct({
  parameters: { id: productId },
});

// Storefront Next - in loader
const { data } = await clients.shopperProducts.getProduct({
  params: {
    path: { organizationId, id: productId },
    query: { siteId },
  },
});

Adding to Cart:

// PWA Kit - in component
const addItem = useShopperBasketsMutation("addItemToBasket");
addItem.mutate({
  parameters: { basketId },
  body: { productId, quantity },
});

// Storefront Next - in action route
const { data } = await clients.shopperBasketsV2.addItemToBasket({
  params: {
    path: { organizationId, basketId },
    query: { siteId },
  },
  body: [{ productId, quantity }],
});

Key Similarities

Both use SCAPI for commerce operations.
Both support SLAS authentication.
Both proxy API requests through the server.
Both provide TypeScript support.

Storefront Conversion Considerations

When migrating from PWA Kit to Storefront Next:

Move API calls to loaders: Replace useProduct, useCategory, and so on with loader fetches.
Move mutations to actions: Replace useShopperBasketsMutation with action routes.
Update parameter format: Change from { parameters: {} } to { params: { path: {}, query: {} } }.
Handle auth manually: Create auth middleware instead of relying on provider.
Remove React Query: No longer needed; caching handled by React Router.
Update error handling: Use ApiError class instead of hook error states.
Review non-personalized SCAPI responses: Before classifying affected requests, review custom hooks, fields, headers, schema overrides, and custom APIs. Remove explicit personalized=none values from individual requests when the central Storefront Next policy classifies the corresponding responses. See Classify Non-Personalized Responses.