react-patterns

PWA Kit React Patterns

Before Writing Code

Always fetch the latest official documentation BEFORE building React components:

1. Web-search: "Salesforce PWA Kit React patterns 2026"
2. Web-search: "Salesforce Commerce SDK React hooks 2026"
3. Web-search: "Salesforce Retail React App reference architecture 2026"
4. Web-fetch: https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/getting-started.html
5. Web-fetch: https://developer.salesforce.com/docs/commerce/commerce-sdk-react/guide/getting-started.html
6. Web-fetch: https://github.com/SalesforceCommerceCloud/pwa-kit

Verify PWA Kit version, available hooks, getProps API, and routing patterns against current documentation before writing any component code.

Conceptual Architecture

CRITICAL: PWA Kit is NOT Remix/Next.js

WARNING: PWA Kit is a custom React framework built by Salesforce. It has its own SSR implementation, routing, and data fetching patterns. Do NOT use Next.js or Remix patterns -- they will not work.

Pattern	PWA Kit	Next.js (DO NOT USE)	Remix (DO NOT USE)
Server data fetching	getProps() static method	getServerSideProps	loader()
Client routing	React Router (react-router-dom)	File-based routing	File-based routing
Deployment	Managed Runtime	Vercel / self-hosted	Vercel / self-hosted
Styling	Chakra UI (default)	Any	Any
Commerce SDK	Built-in hooks + typed clients	N/A	N/A
SSR server	@salesforce/pwa-kit-runtime	Built-in	Built-in
Data mutations	Commerce SDK mutation hooks	Server Actions	action()
Error boundaries	React error boundaries	error.tsx	ErrorBoundary export

PWA Kit-Specific APIs

API / Pattern	Purpose	Where It Runs
Component.getProps()	Server-side data fetching (static method on page components)	Server (SSR)
useServerContext()	Access req, res during SSR	Server only
getConfig()	Read runtime configuration (config/default.js)	Server + Client
RouteComponent	Page-level component registered in route config	Both
Commerce SDK React hooks	Client-side SCAPI data fetching (useProduct, useBasket, etc.)	Client
withReactQuery (v3+)	React Query integration for data caching	Both

SSR and Hydration

PWA Kit renders React components on the server to produce initial HTML, which is sent to the browser. React then hydrates the HTML on the client -- attaching event listeners and initializing state so the app becomes fully interactive.

Key SSR constraints:

• window, document, navigator, and other browser APIs are undefined during SSR
• Use useEffect for any code that requires browser APIs (it only runs on the client)
• Ensure server-rendered HTML matches client-rendered HTML to avoid hydration mismatches
• PWA Kit supports streaming SSR with React 18+ for faster time-to-first-byte

Component Architecture

Layer	Role	Data Fetching	Example
Page component	Route-level, registered in app/routes.jsx	getProps() for SSR data	ProductDetailPage
Container component	Orchestrates data flow, connects to Commerce SDK	Commerce SDK hooks	ProductListContainer
Presentational component	Pure UI rendering, receives props	None (props only)	ProductTile, PriceDisplay
Layout component	Persistent shell (header, footer)	Minimal or none	AppConfig

PWA Kit Project Structure

Path	Purpose
app/pages/	Page components (route-level)
app/components/	Shared/reusable components
app/components/_app-config/	Application shell (layout wrapper)
app/routes.jsx	Route definitions mapping URLs to page components
app/ssr.js	SSR server entry point
config/default.js	Default runtime configuration (Commerce API, sites)
config/[env].js	Environment-specific overrides

Commerce SDK React Hooks

The @salesforce/commerce-sdk-react package provides hooks that wrap SCAPI calls with React Query for caching, loading states, and error handling.

Hook Category	Examples	Purpose
Product hooks	useProduct, useProducts, useSearchProducts	Fetch product data
Basket hooks	useBasket, useShopperBasketsMutation	Cart operations
Customer hooks	useCustomer, useShopperLoginMutation	Auth and profile
Category hooks	useCategories, useCategory	Navigation and browse
Promotion hooks	usePromotions	Active promotions

All hooks return { data, isLoading, error, isError } and support React Query options (staleTime, cacheTime, refetchOnWindowFocus, enabled). Mutation hooks return { mutate, mutateAsync, isLoading, error }.

Client-Side Routing

PWA Kit uses react-router-dom. Routes are defined in app/routes.jsx and map URL patterns to page components.

Router API	Purpose
<Link to="...">	Declarative navigation (client-side)
useNavigate()	Programmatic navigation
useParams()	Access URL parameters
useLocation()	Current URL, search params
useSearchParams()	Read/write URL query parameters

State Management

State Type	Tool	Scope	Examples
Server/remote state	Commerce SDK hooks (React Query)	Cached, shared	Products, basket, customer
Global client state	React Context	App-wide	User session, locale, currency
Local component state	useState / useReducer	Single component	Form inputs, UI toggles, selections
URL state	useSearchParams	Shareable	Filters, pagination, sort order

Avoid duplicating server state in client state -- let Commerce SDK hooks be the source of truth for remote data.

Performance Optimization Concepts

Technique	React API	When to Use
Memoize expensive computations	useMemo	Filtering, sorting large lists
Stable callback references	useCallback	Functions passed as props to child components
Component memoization	React.memo	Prevent re-render when props unchanged
Code splitting	React.lazy + Suspense	Large components not needed on initial render
Deferred updates	useDeferredValue (React 18+)	Non-urgent UI updates

Code Examples

Pattern: Page component with getProps

const ProductDetailPage = ({ product }) => {
    return <div>{product.name}</div>;
};
ProductDetailPage.getProps = async ({ params, api }) => {
    // Fetch live docs for Commerce SDK shopperProducts API
    return { product };
};
export default ProductDetailPage;

Pattern: Commerce SDK hook usage

const { data, isLoading, error } = useProduct({
    parameters: { id: productId }
});
// Fetch live docs for @salesforce/commerce-sdk-react hooks

Pattern: App shell layout

const AppConfig = ({ children }) => (
    <Box>
        <Header />
        <Box as="main">{children}</Box>
        <Footer />
    </Box>
);

Pattern: SSR-safe browser API access

useEffect(() => {
    // This only runs on the client, never during SSR
    // Fetch live docs for useEffect SSR behavior
}, []);

Best Practices

Data Fetching

• Use getProps() for SEO-critical, initial page load data (runs on server)
• Use Commerce SDK React hooks for interactive, client-side data updates
• Use Promise.all() inside getProps() for parallel data fetching
• Never duplicate server-fetched data into local state

Component Design

• Keep components small and single-purpose (page, container, presentational)
• Use composition and children props over deep prop drilling
• Use React Context only for truly global state (user, basket, locale)
• Memoize expensive computations with useMemo and stable callbacks with useCallback

SSR Safety

• Never access window, document, or browser APIs during render -- use useEffect
• Test components in SSR mode to catch hydration mismatches early
• Return null or fallback UI for client-only features during SSR
• Ensure conditional rendering is deterministic between server and client

Styling and UI

• Use Chakra UI components as the default component library in PWA Kit
• Leverage Chakra theme tokens for consistent spacing, colors, and typography
• Use responsive array syntax for breakpoint-based styling (e.g., w={['100%', '50%', '33%']})
• Override theme at the project level in app/theme/ rather than inline styles

---

Fetch the latest PWA Kit developer guide, Commerce SDK React documentation, and Retail React App source for exact hook signatures, route configuration, and getProps API before implementing.