PWA Kit (Headless B2C Storefronts)
Before Writing Code
Fetch live docs:
- Fetch
https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/overview for PWA Kit documentation
- Web-search
site:github.com SalesforceCommerceCloud pwa-kit for source, examples, and starter templates
- Web-search
site:developer.salesforce.com pwa-kit commerce-sdk for Commerce SDK integration
- Web-search
site:developer.salesforce.com pwa-kit managed-runtime deployment for deployment docs
Why: PWA Kit versions, Commerce SDK hooks, and Managed Runtime deployment procedures change across releases. Always verify the version in use (v2 vs v3+) before generating code.
Conceptual Architecture
What Is PWA Kit
PWA Kit is Salesforce's React-based framework for headless B2C Commerce:
| Aspect |
Detail |
| Framework |
React with custom SSR (NOT Remix, NOT Next.js) |
| Hosting |
Managed Runtime (Salesforce CDN/edge) or self-hosted Node.js |
| API Layer |
Commerce SDK -- typed access to SCAPI (Shopper APIs) |
| Authentication |
SLAS (Shopper Login and API Access Service) |
| UI Library |
Chakra UI (accessible, themeable components) |
| Extensibility |
Override templates/components without forking |
Project Structure
pwa-kit-storefront/
├── app/
│ ├── pages/ # Route-based page components
│ ├── components/ # Shared React components
│ ├── hooks/ # Commerce SDK React hooks
│ └── routes.jsx # Centralized route definitions
├── config/default.js # Site config (API credentials, locales)
└── ssr.js # SSR server entry point
Core Concepts
| Concept |
Description |
| Data Fetching (v2) |
getProps static method on page components -- runs server-side on initial load |
| Data Fetching (v3+) |
withReactQuery and React Query hooks replace getProps |
| Routing |
Centralized in app/routes.jsx (NOT file-based like Next.js); React Router syntax |
| SSR |
Custom server-side rendering via ssr.js; hydration on client |
| Commerce SDK Hooks |
useProduct, useCategories, useBasket, useCustomer, useSearchParams |
| Chakra UI |
Box, Flex, Grid, Stack for layout; responsive array syntax fontSize={['sm', 'md']} |
| SLAS Auth |
Guest tokens (automatic), registered login (OAuth), token refresh (transparent via SDK) |
Key Platform Warnings
- NOT file-based routing: routes must be explicitly defined in
routes.jsx.
- NOT Remix or Next.js: do not use Remix loaders/actions or Next.js
getServerSideProps.
- Version matters: v2 uses
getProps; v3+ uses React Query. Check package.json before coding.
- Managed Runtime constraints: environment variables are set in Runtime Admin, not
.env in production.
- No direct SCAPI calls: always use Commerce SDK; it handles auth, proxying, and token management.
Commerce SDK Configuration
The Commerce SDK is configured in config/default.js with Commerce API credentials (clientId, organizationId, shortCode, siteId). These values come from environment variables in production. The SDK handles SLAS authentication, token refresh, and SCAPI proxy routing transparently.
Commerce SDK Hook Patterns
| Hook |
Purpose |
Returns |
useProduct(id) |
Fetch product by ID |
Product object with variants, images, prices |
useCategories(id) |
Fetch category tree |
Category with subcategories |
useBasket() |
Cart management |
Basket object with line items, totals |
useCustomer() |
Customer profile |
Customer data, authentication state |
useSearchParams() |
Search and filtering |
Search results with facets, pagination |
Fetch live docs for current hook signatures -- return types and parameters evolve across SDK versions.
Routing
Routes are defined explicitly in app/routes.jsx using React Router syntax. Page components in app/pages/ are NOT auto-discovered. Each route maps a URL pattern to a component with optional data fetching.
// Pattern: route definition skeleton
// Fetch live docs for current route config API
const routes = [
{ path: '/', component: Home, exact: true },
{ path: '/product/:productId', component: ProductDetail },
]
Server-Side Rendering
| Phase |
Description |
| Server render |
ssr.js processes the request; getProps (v2) or React Query (v3+) fetches data |
| HTML delivery |
Fully rendered HTML sent to browser with embedded state |
| Client hydration |
React hydrates the server-rendered HTML and attaches event handlers |
| Client navigation |
Subsequent navigation is client-side via React Router |
Deployment Overview
| Target |
Method |
| Managed Runtime |
npm run push -- -m "message" via CLI; global CDN, auto-SSL, environment management |
| Self-hosted |
Any Node.js host (AWS, Heroku, Vercel); manual SCAPI proxy configuration needed |
Managed Runtime environments: development, staging, production. Each environment has independent configuration in Runtime Admin.
Extensibility Framework
Override templates and components without forking the base:
- Template overrides: replace specific pages or components via configuration.
- Component overrides: wrap or replace standard components.
- Hook overrides: customize data fetching logic.
- Theme overrides: extend Chakra UI theme with custom tokens and component styles.
Chakra UI Theming
Chakra UI is the default component library. Customize via extendTheme():
- Colors, fonts, spacing: override design tokens globally.
- Component styles: customize default props and variants per component.
- Responsive: array syntax
fontSize={['sm', 'md', 'lg']} maps to breakpoints.
- Accessibility: built-in ARIA attributes, keyboard navigation, focus management.
Scaffold Pattern
# Pattern: create new PWA Kit project
# Fetch live docs for current CLI options
npx @salesforce/pwa-kit-create-app
// Pattern: page component skeleton
// Fetch live docs for current data fetching API
const MyPage = ({ data }) => <Box>{data.name}</Box>
export default MyPage
Best Practices
Development
- Use Commerce SDK hooks for client-side interactions (add to cart, search).
- Leverage Chakra UI for consistent, accessible design.
- Use the extensibility framework to customize -- do not fork the base template.
- Keep
config/default.js environment-aware; never hardcode API credentials.
Performance
- Use server-side data fetching (
getProps or React Query) -- never useEffect for initial data.
- Optimize images with responsive sizing and lazy loading.
- Configure proper caching headers for CDN delivery.
- Minimize bundle size by code-splitting pages and lazy-loading non-critical components.
Deployment
- Deploy to Managed Runtime for optimal SCAPI integration and CDN performance.
- Test SSR rendering and client-side hydration before pushing.
- Manage environment variables in Runtime Admin, not in code.
- Use separate environments (dev, staging, prod) with independent configurations.
Fetch the PWA Kit docs, Commerce SDK reference, and Managed Runtime deployment guide for exact component APIs, SDK method signatures, and configuration options before implementing.
1---2name: sf-b2c-pwa-kit3description: Build headless B2C storefronts with PWA Kit — React-based framework (NOT Remix/Next.js), Managed Runtime deployment, Commerce SDK integration, server-side rendering, Chakra UI components, and extensible application shell. Use when building headless Salesforce Commerce storefronts.4---56# PWA Kit (Headless B2C Storefronts)78## Before Writing Code910**Fetch live docs:**111. Fetch `https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/overview` for PWA Kit documentation122. Web-search `site:github.com SalesforceCommerceCloud pwa-kit` for source, examples, and starter templates133. Web-search `site:developer.salesforce.com pwa-kit commerce-sdk` for Commerce SDK integration144. Web-search `site:developer.salesforce.com pwa-kit managed-runtime deployment` for deployment docs1516**Why:** PWA Kit versions, Commerce SDK hooks, and Managed Runtime deployment procedures change across releases. Always verify the version in use (v2 vs v3+) before generating code.1718## Conceptual Architecture1920### What Is PWA Kit2122PWA Kit is Salesforce's React-based framework for headless B2C Commerce:2324| Aspect | Detail |25|--------|--------|26| Framework | React with custom SSR (NOT Remix, NOT Next.js) |27| Hosting | Managed Runtime (Salesforce CDN/edge) or self-hosted Node.js |28| API Layer | Commerce SDK -- typed access to SCAPI (Shopper APIs) |29| Authentication | SLAS (Shopper Login and API Access Service) |30| UI Library | Chakra UI (accessible, themeable components) |31| Extensibility | Override templates/components without forking |3233### Project Structure3435```36pwa-kit-storefront/37├── app/38│ ├── pages/ # Route-based page components39│ ├── components/ # Shared React components40│ ├── hooks/ # Commerce SDK React hooks41│ └── routes.jsx # Centralized route definitions42├── config/default.js # Site config (API credentials, locales)43└── ssr.js # SSR server entry point44```4546### Core Concepts4748| Concept | Description |49|---------|-------------|50| Data Fetching (v2) | `getProps` static method on page components -- runs server-side on initial load |51| Data Fetching (v3+) | `withReactQuery` and React Query hooks replace `getProps` |52| Routing | Centralized in `app/routes.jsx` (NOT file-based like Next.js); React Router syntax |53| SSR | Custom server-side rendering via `ssr.js`; hydration on client |54| Commerce SDK Hooks | `useProduct`, `useCategories`, `useBasket`, `useCustomer`, `useSearchParams` |55| Chakra UI | Box, Flex, Grid, Stack for layout; responsive array syntax `fontSize={['sm', 'md']}` |56| SLAS Auth | Guest tokens (automatic), registered login (OAuth), token refresh (transparent via SDK) |5758### Key Platform Warnings5960- **NOT file-based routing**: routes must be explicitly defined in `routes.jsx`.61- **NOT Remix or Next.js**: do not use Remix loaders/actions or Next.js `getServerSideProps`.62- **Version matters**: v2 uses `getProps`; v3+ uses React Query. Check `package.json` before coding.63- **Managed Runtime constraints**: environment variables are set in Runtime Admin, not `.env` in production.64- **No direct SCAPI calls**: always use Commerce SDK; it handles auth, proxying, and token management.6566### Commerce SDK Configuration6768The Commerce SDK is configured in `config/default.js` with Commerce API credentials (clientId, organizationId, shortCode, siteId). These values come from environment variables in production. The SDK handles SLAS authentication, token refresh, and SCAPI proxy routing transparently.6970### Commerce SDK Hook Patterns7172| Hook | Purpose | Returns |73|------|---------|---------|74| `useProduct(id)` | Fetch product by ID | Product object with variants, images, prices |75| `useCategories(id)` | Fetch category tree | Category with subcategories |76| `useBasket()` | Cart management | Basket object with line items, totals |77| `useCustomer()` | Customer profile | Customer data, authentication state |78| `useSearchParams()` | Search and filtering | Search results with facets, pagination |7980Fetch live docs for current hook signatures -- return types and parameters evolve across SDK versions.8182### Routing8384Routes are defined explicitly in `app/routes.jsx` using React Router syntax. Page components in `app/pages/` are NOT auto-discovered. Each route maps a URL pattern to a component with optional data fetching.8586```jsx87// Pattern: route definition skeleton88// Fetch live docs for current route config API89const routes = [90 { path: '/', component: Home, exact: true },91 { path: '/product/:productId', component: ProductDetail },92]93```9495### Server-Side Rendering9697| Phase | Description |98|-------|-------------|99| Server render | `ssr.js` processes the request; `getProps` (v2) or React Query (v3+) fetches data |100| HTML delivery | Fully rendered HTML sent to browser with embedded state |101| Client hydration | React hydrates the server-rendered HTML and attaches event handlers |102| Client navigation | Subsequent navigation is client-side via React Router |103104### Deployment Overview105106| Target | Method |107|--------|--------|108| Managed Runtime | `npm run push -- -m "message"` via CLI; global CDN, auto-SSL, environment management |109| Self-hosted | Any Node.js host (AWS, Heroku, Vercel); manual SCAPI proxy configuration needed |110111Managed Runtime environments: development, staging, production. Each environment has independent configuration in Runtime Admin.112113### Extensibility Framework114115Override templates and components without forking the base:116- **Template overrides**: replace specific pages or components via configuration.117- **Component overrides**: wrap or replace standard components.118- **Hook overrides**: customize data fetching logic.119- **Theme overrides**: extend Chakra UI theme with custom tokens and component styles.120121### Chakra UI Theming122123Chakra UI is the default component library. Customize via `extendTheme()`:124- **Colors, fonts, spacing**: override design tokens globally.125- **Component styles**: customize default props and variants per component.126- **Responsive**: array syntax `fontSize={['sm', 'md', 'lg']}` maps to breakpoints.127- **Accessibility**: built-in ARIA attributes, keyboard navigation, focus management.128129### Scaffold Pattern130131```bash132# Pattern: create new PWA Kit project133# Fetch live docs for current CLI options134npx @salesforce/pwa-kit-create-app135```136137```jsx138// Pattern: page component skeleton139// Fetch live docs for current data fetching API140const MyPage = ({ data }) => <Box>{data.name}</Box>141export default MyPage142```143144## Best Practices145146### Development147- Use Commerce SDK hooks for client-side interactions (add to cart, search).148- Leverage Chakra UI for consistent, accessible design.149- Use the extensibility framework to customize -- do not fork the base template.150- Keep `config/default.js` environment-aware; never hardcode API credentials.151152### Performance153- Use server-side data fetching (`getProps` or React Query) -- never `useEffect` for initial data.154- Optimize images with responsive sizing and lazy loading.155- Configure proper caching headers for CDN delivery.156- Minimize bundle size by code-splitting pages and lazy-loading non-critical components.157158### Deployment159- Deploy to Managed Runtime for optimal SCAPI integration and CDN performance.160- Test SSR rendering and client-side hydration before pushing.161- Manage environment variables in Runtime Admin, not in code.162- Use separate environments (dev, staging, prod) with independent configurations.163164---165166Fetch the PWA Kit docs, Commerce SDK reference, and Managed Runtime deployment guide for exact component APIs, SDK method signatures, and configuration options before implementing.
OrcaQubits