Every SFCC headless project we’ve walked into starts with the same sentence: “we just want to go headless.” Nobody ever means that literally. What they actually want is faster pages, a storefront their design team isn’t fighting with SFRA’s templates to change, and the freedom to eventually put that same backend behind a mobile app or a kiosk. Headless is the means, not the goal; and losing sight of that is exactly how a PWA Kit build turns into an eight-month slog instead of a three-month one.
We’ve built and migrated Salesforce Commerce Cloud storefronts onto Composable Storefront for retail brands that couldn’t afford downtime during peak season, which means we’ve hit most of the sharp edges this stack has to offer. This is the technical rundown we wish someone had handed us the first time: what PWA Kit actually is under the hood, how the pieces fit together, where the real implementation risk hides, and the decisions that are much cheaper to get right on day one than to unwind in month four.
What “Headless” Actually Means on SFCC
SFRA, Salesforce’s older storefront reference architecture, renders pages server-side using ISML templates that are tightly coupled to Business Manager. Want to change how a product card looks? You typically update an ISML template or its supporting scripts within an SFRA cartridge and deploy those changes to the storefront. The frontend remains closely tied to SFCC’s cartridge architecture and release process whether you like it or not.
Headless commerce breaks that coupling. The commerce backend becomes a pure API; product, cart, pricing, and checkout logic exposed as data, with no opinion about how it’s displayed. The frontend becomes a separate application that can be a React storefront, a mobile app, a voice interface, or all three at once, each calling the same backend independently.
On Salesforce Commerce Cloud specifically, this isn’t a bring-your-own-stack free-for-all. Salesforce ships its own supported implementation, called Composable Storefront, built from two components: PWA Kit, the frontend framework, and Managed Runtime, the hosting layer purpose-built to run it. Since its 2021 launch, Composable Storefront has been Salesforce’s recommended path for any new SFCC headless build, not just one option among many.
The Architecture: PWA Kit + Managed Runtime
PWA Kit is an open-source, React-based framework distributed as a monorepo of packages; SDKs, project templates, shared libraries, and tooling. Most projects start from its Retail React App template, which already ships with a product listing page, product detail page, cart, and checkout scaffolding built in, rather than starting from a blank React app.
Inside every Managed Runtime environment, the compiled React bundle doesn’t just run as static files; it runs inside a Node.js process, with the Express framework handling routing and rendering through what Salesforce calls the App Server. This detail matters more than it sounds like it should: teams that treat a PWA Kit project as “just a React app” tend to get their caching and payload decisions wrong, because there’s a real server process making real decisions on every request, not a static bundle being served from a CDN edge.
Managed Runtime itself is the serverless hosting layer purpose-built for this framework; deployment, scaling, and monitoring are handled for you, and a CDN sits in front of the App Server to cache rendered output. It’s a good trade for most teams: less infrastructure to own, at the cost of working within Salesforce’s opinionated stack rather than a fully custom one.
Rendering: Why SSR + Hydration Isn’t Optional
The first page load of a PWA Kit storefront is server-side rendered; the App Server builds the full HTML for that page before it ever reaches the browser. This matters for two reasons: search crawlers see a fully formed page instead of an empty div waiting on JavaScript, and Managed Runtime’s CDN can cache that rendered HTML and serve it instantly to the next visitor who requests the same page.
After that first render, control hands off to the browser through hydration; the same React app boots up client-side, attaches event handlers, and takes over rendering for every subsequent interaction. You get the SEO and performance benefits of server rendering on arrival, and the responsiveness of a single-page app afterward.
The catch is that this only pays off if the caching layer is configured deliberately. We’ve seen teams leave cache-control headers at their defaults, or fail to strip irrelevant URL parameters before they hit the CDN; both of which fragment the cache into thousands of near-duplicate entries and quietly cancel out the entire benefit of server-side rendering.
Talking to the Backend: SCAPI and commerce-sdk-react
The Salesforce Commerce API; SCAPI; is the actual interface a headless storefront talks to. Rather than calling it directly, most PWA Kit projects use commerce-sdk-react, a library of React hooks that wraps SCAPI and, for newer projects, integrates with React Query to manage data fetching and caching on both the server and client.
That React Query integration is worth taking seriously, because it prevents the client from re-fetching data the server already rendered; a mistake that quietly doubles your API calls without anyone noticing until a load test surfaces it. The two habits we push every team to build early: request only the fields a page actually needs instead of pulling full default objects, and parallelize independent API calls instead of chaining them one after another. Both sound like minor hygiene until you watch them account for most of a slow time-to-first-byte in a real diagnostic session.
Authentication Is Where Projects Slow Down
Shopper sessions and tokens are managed through SLAS; the Shopper Login and API Access Service. On PWA Kit 3.5 and later, the recommended pattern is hybrid auth using a private client, which keeps token exchange on the server side rather than exposing it to the browser.
This is the part of a PWA Kit build that looks like a checkbox in the documentation and turns into the slowest part of the project in practice, because authentication touches guest checkout, saved carts, single sign-on, and loyalty program integrations all at once. Our advice, every time: run a dedicated auth spike in week one, not week six. Finding out your SSO provider doesn’t play nicely with SLAS token refresh is a much cheaper discovery on day three than on the week before launch.
Performance Engineering That Actually Moves the Needle
PWA Kit is preconfigured for code splitting through Webpack, and the `loadable` utility lets you load page-level code on demand; product detail page logic shouldn’t be part of your homepage bundle. Running Webpack Bundle Analyzer periodically catches the dependency that quietly crept back in.
Custom components are the other place performance quietly erodes. A component that recomputes something expensive on every render, or triggers a cascade of re-renders in its children, will show up as a worse Interaction to Next Paint score long before anyone thinks to profile it. We treat custom component performance as a code review checklist item, not an afterthought fixed post-launch.
None of this matters, though, if the CDN caching underneath it is misconfigured; it’s worth repeating, because we’ve seen well-optimized frontends undone by cache-control headers nobody revisited after the initial setup.
Migrating Without a Big-Bang Cutover
Very few of our SFCC headless projects are greenfield. Most are migrations off an existing SFRA storefront that can’t simply go dark for a weekend cutover. A phased rollout lets PWA Kit run alongside the existing SFRA site, routing traffic to the new storefront by URL path or by a percentage of sessions, and expanding coverage page-type by page-type rather than all at once.
The sequencing matters. Product listing and product detail pages are the lowest-risk, highest-learning place to start; they’re read-heavy, easy to compare against the old site, and forgiving if something’s slightly off. Checkout is the highest-value page and, not coincidentally, the one we migrate last, once the team has already worked out its caching, auth, and data-fetching patterns on lower-stakes pages.
Lessons We’d Pass On
- Treat PWA Kit as Salesforce’s opinionated stack, not a blank canvas. Fighting the App Server’s rendering model instead of designing around it is the single biggest source of schedule slip we see.
- Auth and caching look simple in the docs and eat the most real calendar time. Budget for both accordingly, and spike them early rather than late.
A Practical Pre-Launch Checklist
- Cache-control headers are explicitly configured per route and content type, not left at defaults
- URL parameters that don’t affect page content are stripped before hitting the CDN cache layer
- SCAPI calls request only the fields needed, not default full-object payloads
- Independent data fetches are parallelized, not chained
- Auth uses hybrid auth with a private client (PWA Kit 3.5+), not the legacy public client flow
- Code splitting is in place for page-specific bundles (PDP, checkout, etc.)
- Proxy configuration uses HTTPS ahead of the August 31, 2026 deprecation deadline
- A phased rollout plan exists for SFRA migrations, with checkout migrated last
FAQ
What’s the difference between SFRA and Composable Storefront (PWA Kit)?
SFRA renders pages server-side using ISML templates tightly coupled to Business Manager. Composable Storefront decouples the frontend entirely, using a React-based PWA Kit application that talks to the backend purely through the Salesforce Commerce API (SCAPI), hosted on Salesforce’s serverless Managed Runtime.
Do I need Managed Runtime to use PWA Kit?
For full Salesforce support, yes. Managed Runtime is the purpose-built serverless hosting layer for PWA Kit storefronts, handling deployment, scaling, and CDN caching. Self-hosting the same React app elsewhere is technically possible but falls outside Salesforce’s supported path.
How does PWA Kit handle SEO if it’s a React app?
PWA Kit server-side renders the first page load so crawlers see fully rendered HTML, then hands off to client-side rendering through hydration for subsequent interactions; giving both the SEO benefits of server rendering and the responsiveness of a single-page app.
What’s the most common cause of poor performance in a PWA Kit storefront?
Misconfigured CDN caching and over-fetched API payloads. Requesting more data than a page needs, chaining fetches instead of parallelizing them, and leaving cache-control headers at their defaults account for most of the performance issues we see in real implementations.
Can I migrate to headless without relaunching the entire site at once?
Yes; a phased rollout lets you run PWA Kit alongside your existing SFRA storefront, migrating page types incrementally, typically product pages first and checkout last, rather than cutting over all at once.
Exper Labs has deep hands-on experience with Salesforce Commerce Cloud (formerly Demandware), from greenfield PWA Kit builds to phased SFRA-to-headless migrations. If you’re evaluating a headless move, talk to our e-commerce team.
