Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 28 ยท APIs and Headless

Headless Storefronts with PWA Kit

Learn how PWA Kit builds a headless Salesforce B2C Commerce storefront: React, commerce-sdk-react, Managed Runtime, proxies, server-side rendering, caching and when to pick SFRA instead.

SFRA renders pages on the Commerce Cloud instance with ISML templates. A headless storefront turns that around: the storefront is a separate application that fetches data from the commerce APIs and renders it itself. Salesforce's toolkit for this is the PWA Kit, a React-based storefront framework that talks to SCAPI and runs on a hosting service called Managed Runtime.

This lesson explains the moving parts, how a page request flows through server-side rendering (SSR) and caching, and how to decide between headless and SFRA. You should be comfortable with React basics (see the React tutorial) and with the APIs from OCAPI and SCAPI. The platform code below is read-only; the stand-ins at the end model the SSR-and-cache flow in plain JavaScript.

The PWA Kit evolves quickly (major versions, new hooks, new project templates). The package names and file names here are well established, but check the current documentation and your project's generated files for exact APIs and versions.

The pieces

Piece Role
Commerce APIs (SCAPI) Source of truth for products, baskets, customers, orders
SLAS Issues shopper tokens
PWA Kit project Your React storefront code, started from a generated template
commerce-sdk-react React hooks and a provider that call SCAPI for you
Managed Runtime (MRT) Salesforce-run hosting: Node.js servers for SSR, a CDN in front, deployment "bundles"
Business Manager Still where merchants manage catalogs, prices and promotions

A new project is created with Salesforce's project generator (published as an npm package, run with npx) and started locally with npm start. The generated project contains configuration, a server entry file and an app folder with pages, components and hooks.

Configuration: pointing at your tenant

Project configuration lives in config/default.js. The important block tells the storefront which tenant and site to talk to:

JavaScript
// config/default.js (read-only excerpt, values are placeholders)
module.exports = {
    app: {
        commerceAPI: {
            proxyPath: '/mobify/proxy/api',
            parameters: {
                clientId: '1234abcd-0000-0000-0000-abcdef012345',
                organizationId: 'f_ecom_zzxx_001',
                shortCode: 'kv7kzm78',
                siteId: 'RefArch'
            }
        }
    }
};

Those four values are the same ones you saw in SCAPI URLs. The clientId belongs to a public SLAS client, so nothing secret goes here. For server-only secrets, use environment variables on Managed Runtime, never the browser bundle.

Proxies

Browsers enforce the same-origin policy and CORS. To avoid cross-domain problems and to keep API traffic cacheable on the storefront's own domain, PWA Kit proxies requests: the browser calls /mobify/proxy/api/... on your storefront domain, and the server forwards them to the real SCAPI host. Proxy rules live in the server entry file (ssr.js), where you can also add proxies for other back ends. A proxy is also the place where you can later add caching or header rules.

Fetching data with commerce-sdk-react

The React SDK wraps SCAPI in hooks built on a data-fetching library (React Query), so loading, errors and caching come for free. You wrap the app in a provider once, then use hooks in components:

JSX
// app/pages/product-detail/index.jsx (read-only sketch)
import React from 'react';
import {useParams} from 'react-router-dom';
import {useProduct} from '@salesforce/commerce-sdk-react';

const ProductDetail = () => {
    const {productId} = useParams();
    const {data: product, isLoading, error} = useProduct({parameters: {id: productId}});

    if (isLoading) return <p>Loading...</p>;
    if (error) return <p>Could not load the product.</p>;
    return <h1>{product.name}</h1>;
};

export default ProductDetail;

Behind the scenes the provider obtains and refreshes the SLAS token (guest first, registered after login), attaches it to every call, and stores it where you configured. Never build your own token handling unless you have to.

Server-side rendering and the cache

A client-only React app would send an empty page and load content afterwards, which is slow on weak devices and bad for search engines and link previews. PWA Kit therefore does SSR: the first request is rendered to HTML on a Managed Runtime server, which fetches the needed data, produces markup, and sends it together with the data so React can "hydrate" (take over) in the browser. Later navigation happens in the browser without full reloads, which is what makes it a progressive web app.

Because SSR costs server time, caching is central:

  1. A CDN in front of the servers can serve a stored response for the same URL for a number of seconds, without touching the Node server at all.
  2. The page sets caching headers (Cache-Control with s-maxage) to say how long that is acceptable. Pages that are the same for everyone (product, category, content) cache well; pages that depend on a shopper (basket, account, checkout) must not be shared.
  3. API responses fetched during SSR can be cached too, at the proxy or the CDN, with their own lifetimes.

The golden rule is the same as for SFRA page caching: never cache a response that contains shopper-specific data under a shared key. In a headless storefront, the usual pattern is to render the shared page from the cache and load personal pieces (the basket count, the name in the header) from the browser after the page arrives.

sequenceDiagram
    participant B as Browser
    participant C as CDN
    participant S as MRT server (SSR)
    participant A as SCAPI
    B->>C: GET /product/123
    alt cached
        C-->>B: HTML (from cache)
    else not cached
        C->>S: forward request
        S->>A: fetch product (SLAS token)
        A-->>S: JSON
        S-->>C: HTML + s-maxage
        C-->>B: HTML
    end
    B->>A: load basket (browser, after hydration)

A cached shared page, then personal data fetched by the browser.

Deploying with Managed Runtime

You do not copy files onto a server. You push a bundle: the project's build output is uploaded to Managed Runtime with a command from the project (npm run push in generated projects, which wraps the dev-kit CLI) and a message. Each bundle gets a number; you deploy a bundle to an environment (development, staging, production), and rollbacks are redeploys of an earlier bundle. Environment variables, redirects and the custom domain are set per environment in the Managed Runtime dashboard. Your CI pipeline normally runs tests, builds, and pushes on merge.

Headless or SFRA?

Question Leans to PWA Kit Leans to SFRA
Team skills React and modern JS ISML, Script API, existing Commerce Cloud team
UX goals App-like speed, rich interaction Standard, content-focused store
Time to market Longer: you own more code Shorter with the reference app
Existing code Starting fresh Many cartridges and integrations already built
Integrations Need APIs or custom API endpoints for everything Direct Script API access
Operations Two systems to run (storefront and platform) One system

Neither is "better". A headless storefront gives more freedom and a modern front-end stack, but you rebuild things SFRA gives you out of the box and you must design caching and personalization yourself. SFRA is faster to launch and has a large base of plugins. A migration from SFRA to headless is a big project because cartridge logic must move to hooks, Custom APIs or the front end.

Live stand-ins

The first stand-in models SSR with a shared page cache. It shows why the second request for the same product is cheaper, and why a shopper-specific page needs a different cache decision.

JS SSR with a CDN-style page cache

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second stand-in does the personal data after the page trick: the cached page contains placeholders, and a small "hydration" step fills them from private data. It prints the final text for two shoppers.

JS Shared HTML, personal data filled in later

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does Managed Runtime provide for a PWA Kit storefront?

    Managed Runtime hosts the storefront application: servers that perform SSR, a CDN in front and numbered bundles you deploy to environments.
  2. 2. Why does PWA Kit use proxies such as /mobify/proxy/api?

    A proxy avoids cross-origin problems and gives a single place to add cache and header rules.
  3. 3. Which page is a good candidate for CDN caching?

    Pages that do not vary by shopper can be shared. Personal pages must not be cached under a shared key.
  4. 4. A team has ten years of cartridges and a small React skill set. What usually favours SFRA?

    Headless means rebuilding behaviour in React, Custom APIs and hooks; with strong platform skills and many cartridges, SFRA is often the cheaper route.

Summary

  • PWA Kit is a React storefront framework that uses SCAPI and SLAS and runs on Managed Runtime.
  • config/default.js carries the tenant values (client ID, organization ID, short code, site ID); commerce-sdk-react provides hooks and token handling.
  • Proxies keep API calls same-origin; SSR delivers HTML first and hydrates in the browser.
  • Cache shared pages with s-maxage; fetch personal data from the browser; never share cached personal responses.
  • Choose headless for freedom and a modern stack, SFRA for speed to launch and reuse of platform skills.

Next, the back-office side of the platform: Jobs, Feeds and Import/Export.