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/pwa-kit-managed-runtime/guide/pwa-kit-overview.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.

PWA Kit-Specific APIs

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

PWA Kit Project Structure

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.

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.

State Management

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

Performance Optimization Concepts

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.