Configure a Hybrid Storefront with Hybrid Auth (PWA Kit)

Starting with B2C Commerce version 25.3, hybrid authentication (Hybrid Auth) replaces Plugin SLAS. Hybrid Auth keeps the SFRA/SiteGenesis session (dwsid) and SLAS authorization (JWT) synchronized across a storefront that spans PWA Kit (Composable Storefront) and platform-rendered routes.

This guide covers the PWA Kit / Composable Storefront implementation path on PWA Kit v3. It’s the path for new Hybrid Auth implementations—new customers must start on PWA Kit v3.

Build your PWA Kit site with:

• commerce-sdk-react@4.0.0 or later
• Progressive Web App (PWA) Kit version 3.12 or later

For details, see Get Started with Composable Storefront.

Before configuring PWA Kit, complete the Shared Hybrid Auth Setup:

• Create a SLAS client (public or private) and add the sfcc.session_bridge scope.
• Enable Hybrid Auth in Business Manager (Merchant Tools > Select Site > Site Preferences > Hybrid Auth Settings) using the same SLAS client ID.
• (Optional) Enable Shopper Context and Do-Not-Track synchronization.
• Remove plugin_slas from the cartridge path if you previously used Plugin SLAS.

After you complete the shared setup, configure your PWA Kit project with the following steps.

Do either of these:

• Create a Retail React App with a SLAS public or private client configuration:
  • Run the generator command in a terminal window: npx @salesforce/pwa-kit-create-app my-hybrid-storefront.
  • Select The Retail app using your own B2C Commerce instance and follow the terminal instructions.
• Or generate a Retail React App with a preset configuration, then change the SLAS client ID to your public or private client after generation:
  • Follow the steps in the Quick Start.
  • Use a SLAS public or private client.
  • Make sure the SLAS client used for Hybrid Auth includes the sfcc.session_bridge scope.

In app/components/_app-config/index.jsx (or overrides/app/components/_app-config/index.jsx if you use template extensibility), find the CommerceApiProvider component and uncomment the hybridAuthEnabled prop:

1<CommerceApiProvider
2    ...
3    hybridAuthEnabled={true}
4    ...
5>

Do not set this prop for hybrid storefronts that still use Plugin SLAS. Enable it only for sites that use Hybrid Auth.

By default, PWA Kit uses the History API for navigation. When a shopper clicks a link made with a React Router component, it triggers a soft navigation to the component matching the path in app/routes.jsx. To link to a non-PWA Kit page (one powered by SFRA, for example), remove any route matching that URL pathname from app/routes.jsx.

1. If your PWA Kit project was generated with version 3.x of the Retail React App template using template extensibility, override the overrides/app/routes.jsx file to filter out links to non-PWA Kit pages using JavaScript. For an example override that filters out /cart and /checkout, see this public gist.
2. Update the PWA catch-all route (/*) in app/routes.jsx. In this example, the PWA <PageNotFound /> component is replaced with a redirect to the default origin:

1import {withRouter} from 'react-router-dom'
2    ...
3    {
4        path: '*',
5        component: withRouter((props) => {
6            const {location} = props
7            const urlParams = new URLSearchParams(location.search)
8
9            useEffect(() => {
10                const newURL = new URL(window.location)
11                if (!urlParams.has('redirected')) {
12                    newURL.searchParams.append('redirected', '1')
13                    window.location.href = newURL
14                }
15            }, [window.location.href])
16            if (urlParams.has('redirected')) {
17                return <PageNotFound {...props} />
18            }
19            return null
20        })
21    }

As part of Hybrid Auth, SLAS token calls include the dwsid in the Set-Cookie response header. Make sure the Set-Cookie headers from SLAS API calls are respected and the cookies are set in the browser.

When Hybrid Auth is enabled, SLAS /oauth2/token requests contain a session-bridged dwsid using the Set-Cookie header in the response. In Managed Runtime, enable cookie passthrough:

1. Log in to Managed Runtime Admin.
2. Navigate to your project and environment.
3. Select Environment Settings.
4. Scroll to the Advanced section and select Edit.
5. Enable the switch next to Cookies.
6. Scroll back to the Advanced section and select Update.
7. Wait for your storefront bundle to redeploy.

Route top-of-funnel pages (home /, category /category, product /product) to your PWA Kit storefront on Managed Runtime (MRT), and route transactional routes (such as /cart and /checkout) to SFRA/SiteGenesis.

• To configure eCDN routing rules, see CDN Routing Rules for Hybrid Implementations.
• To compare route split patterns, see the Hybrid Storefront Routing Matrix (PWA Kit).
• (Optional) Get analytics with Einstein Activities for Hybrid Implementations.

Applies to: PWA Kit

On-demand sandbox (ODS) instances include an embedded CDN (eCDN), so configure hybrid routing on ODS the same way you do on a Primary Instance Group (PIG) instance—through the eCDN UI in Business Manager—rather than with the local hybrid proxy. This lets you validate hybrid behavior in a deployed environment that mirrors production routing.

1. Deploy your PWA Kit bundle to a Managed Runtime environment connected to the ODS instance.
2. Complete the shared Hybrid Auth setup and the PWA Kit configuration steps above (Steps 1–5).
3. Configure eCDN origin routing rules for the ODS zone using the Business Manager UI. Route top-of-funnel pages (home, category, product, search) to Managed Runtime, and keep transactional routes (such as /cart and /checkout) on SFRA/SiteGenesis. For the UI steps, see CDN Routing Rules for Hybrid Implementations.
4. Verify routing and cookie/session behavior as described in Verify Your Hybrid Auth Setup.

Applies to: PWA Kit

For local development on localhost, eCDN isn’t available, so use a reverse proxy instead. The PWA Kit hybrid proxy feature is available starting in PWA Kit v3.14 in the pwa-kit-runtime package.

Enable hybrid proxy for local development only. On PIG and ODS instances, use eCDN to direct requests to the PWA Kit Composable Storefront or SFRA/SiteGenesis store. Don’t enable hybrid proxy on PIG or ODS instances: because hybrid proxy sets localAllowCookies: true, it can cause security issues on deployed instances.

Follow these steps to enable hybrid proxy locally.

1. Upgrade the pwa-kit-runtime package dependency to v3.14.0 or later.

2. Configure the hybridProxy value in your Composable Storefront ssr.js for a server-side reverse proxy:

   • localAllowCookies: true
   • hybridProxy.enabled: true
   • hybridProxy.sfccOrigin: [your SFCC store]

3. Update default.js to configure client-side routing:

   • Update app.commerceAPI.parameters to point to the correct Commerce API SIG instance.
   • Add app.enableHybrid: true so that you can toggle hybrid mode on and off.
   • Add a proxy config for the dwrestatic path:
   1ssrParameters.proxyConfigs: add
   2{
   3  host: [your SFCC store],
   4  path: 'dwrestatic'
   5}

4. In app/components/_app-config/index.jsx, uncomment hybridAuthEnabled (see Step 2). Don’t set this flag for hybrid storefronts that still use Plugin SLAS.

5. Update app/routes.jsx to exclude routes from PWA Kit so that the matching pages render on SFRA/SiteGenesis. This example removes the /cart and /checkout routes from the PWA Kit store and uses the catch-all * route to trigger server-side rendering of the proxied SFRA/SiteGenesis cart and checkout pages. For reference, see this public gist.

   1// Remove SFRA/SiteGenesis routes from PWA Kit
   2const ecomRoutes = ['/cart', '/checkout', '*']
   3
   4const hybridRoutes = [
   5  ...routes.filter((route) => !ecomRoutes.includes(route.path)),
   6  {
   7    path: '*',
   8    component: withRouter((props) => {
   9      const config = getConfig()
   10      const {location} = props
   11      const urlParams = new URLSearchParams(location.search)
   12      const {site} = useMultiSite()
   13      const siteId = site && site.id ? site.id : config?.app?.defaultSite
   14
   15      if (typeof window !== 'undefined') {
   16        useEffect(() => {
   17          const newURL = new URL(window.location)
   18          if (!urlParams.has('redirected')) {
   19            newURL.searchParams.append('redirected', '1')
   20            newURL.pathname = `/s/${siteId}/${window.location.pathname
   21              .split('/')
   22              .slice(2)
   23              .join('/')}`
   24            window.location.replace(newURL)
   25          }
   26        }, [window.location.href])
   27      }
   28
   29      if (urlParams.has('redirected')) {
   30        return <PageNotFound {...props} />
   31      }
   32      return null
   33    })
   34  }
   35]
   36
   37export default () => {
   38  const config = getConfig()
   39  // Use these routes only in hybrid mode; otherwise use the defaults.
   40  // This is driven by the config and environment variables.
   41  const routesToConfigure = config.app.enableHybrid ? hybridRoutes : routes
   42  return configureRoutes(routesToConfigure, config, {
   43    ignoredRoutes: ['/callback', '*']
   44  })
   45}

For environment-specific differences (PIG, ODS, localhost), see Hybrid Auth Environments and Routing.

1. Go to your storefront using the vanity domain configured in eCDN.
2. Navigate to a page on SFRA/SiteGenesis.
3. Open browser Developer Tools and inspect cookies. Confirm these cookies are set:
   • cc-nx-g_{Site_ID}: Guest refresh token
   • dwsid: B2C Commerce session ID
   • usid: SLAS customer ID
   • cc-at_{Site_ID}: SLAS access token (appears only when the user lands on an SFRA page; not seen when navigating from a PWA Kit page to an SFRA page)
4. Navigate to any PWA Kit page and verify:
   • cc-nx-g_{SiteID} is unchanged.
   • dwsid is unchanged.
   • usid_{SiteID} is unchanged.
   • cc-at_{SiteID} is no longer present, because PWA Kit consumes it and moves the access token to localStorage. Confirm the accesstoken{SiteID} value in localStorage matches the original cc-at_{SiteID} cookie.
5. In Developer Tools, switch to the Network tab.
6. Add an item to the cart on PWA Kit.
7. Inspect the SCAPI Add to Cart request. In Request Headers, confirm the sfdc_dwsid header is set to the dwsid cookie value. This header is required to keep hybrid storefront behavior stable at production scale when traffic is distributed across multiple app servers. If you’re not using PWA Kit, set this header from your headless application whenever the dwsid cookie is available.

The following table compares PWA Kit feature support for Plugin SLAS versus Hybrid Auth.

• Hybrid Authentication Overview
• Hybrid Storefront Routing Matrix (PWA Kit)
• Hybrid Auth Implementation with PWA Kit v2.x
• Hybrid Storefront Basket Guidance
• Hybrid Auth Troubleshooting

j

Announcements

Choose Your B2C Commerce Storefront Type

B2C Commerce

SCAPI

Storefront Next

Composable Storefront

Composable Storefront Overview

Quick Start

Deploy Your Code

Skills for Success

Introduction to Composable Storefront

Use Composable Storefront in a Hybrid Implementation

Configure with Hybrid Auth

Hybrid Auth Implementation with PWA Kit v2.x

Hybrid Storefront Routing Matrix

Plugin SLAS Setup

PWA Kit Framework

Performance Guide for Composable Storefronts

Get Set Up

Build Your Site

Enable Your Merchant Team

Test, Launch, and Monitor

Maintain

Composable Storefront Specifications

Storefront Reference Architecture (SFRA)

Commerce Apps ISV Developer Guide

B2C Commerce Solutions

B2C Commerce Release Notes

B2C Commerce Reference Information

Ask the Community