Use Storefront Next in a Hybrid Implementation

Hybrid Auth is a standalone solution for implementations that need both Storefront Reference Architecture (SFRA) or SiteGenesis authorization and Shopper Login and API Access Service (SLAS) authorization. Hybrid Auth maintains both a dwsid (SFRA or SiteGenesis) and a JSON Web Token (SLAS), keeping these tokens in sync.

Hybrid Auth is designed for various use cases, all of which involve using both SFRA or SiteGenesis and SLAS.

Hybrid Auth provides key advantages for implementing storefronts alongside traditional SFRA or SiteGenesis pages.

Launch faster with out-of-the-box authentication, ensuring automatic data synchronization between SFRA and Storefront Next pages.

Shoppers can navigate across your hybrid site with no disruption or loss of data. Synchronization is expanded to include Shopper Context session attributes and support for consistent analytics.

Whether you’re using SiteGenesis or SFRA, we have you covered with a fully supported and productized solution to ease your path to Storefront Next success.

B2C Commerce version 25.6 Hybrid Auth support includes:

• Storefront Next
• SLAS public and private clients
• SFRA and SiteGenesis templates
• Third-party IDP login with SLAS:
  • Configure third-party IDP logins by using SLAS, not Business Manager.
  • Perform all third-party IDP interactions by using SLAS.
  • SFRA third-party IDP logins are only supported when using SLAS.

Before you configure Storefront Next, complete the Shared Hybrid Auth Setup. It covers the architecture-neutral configuration that every hybrid storefront needs:

• Set up a SLAS client (public or private) and add the sfcc.session_bridge scope for session bridging. Use the same client ID in Hybrid Auth and in your Storefront Next application. See Shared Hybrid Auth Setup, Steps 1–2.
• (Optional) Configure third-party IDP and Social Login with SLAS, not Business Manager. The IDP name in the SLAS Admin configuration is case sensitive and must match the OAuth Provider ID in SFRA/SiteGenesis. See Shared Hybrid Auth Setup, Step 3.
• Configure Business Manager: enable the Hybrid Auth toggle, enter your SLAS client ID (select Is Public Client for a public client, or enter the client secret for a private client), and set optional features as needed—Shopper Context, Do-Not-Track Synchronization, HTTPOnly True, guest and registered refresh token TTL overrides, and the cookie domain level. Then enforce HTTPS. See Shared Hybrid Auth Setup, Step 4.
• Remove Plugin SLAS from the cartridge path if you previously used it, and review any Plugin SLAS-specific code customizations. Make sure no custom cartridge code calls session bridging endpoints; Hybrid Auth handles session bridging for you. See Shared Hybrid Auth Setup, Step 5.

Then configure the Storefront Next-specific routing and application settings:

1. For Storefront Next: Set up Embedded Content Delivery Network (eCDN) origin rules:

   • Configure the embedded content delivery network (eCDN) to send page requests at the top of the funnel to the Storefront Next: home page (/), the category listing page (/category), and the product details page (/product). These pages are deployed to a Managed Runtime (MRT) environment running on mystorefront.mobify-storefront.com. When the shopper decides to make a purchase, the eCDN redirects the shopper to the existing SFRA/SG checkout page running on www.mystorefront.com.
   • To compare route split patterns, see Choose a Hybrid Routing Matrix.
   • To configure eCDN routing rules in the Business Manager UI (recommended), see CDN Routing Rules for Hybrid Implementations. To automate or script rule management instead, use the CDN Zones API documented in the same guide.
     • Provide these values for new rules:
       • Rule Name: Any name that helps you identify that this ruleset is for hybrid storefronts. A storefront can have more than one ruleset.
       • Enable Rule Once Saved: Select this checkbox to immediately apply the ruleset when you click Save.
       • Hostnames: Click Select Hostnames and select the hostname for your hybrid storefront.
       • MRT Origin: Your MRT storefront domain, which you can find in Environment Settings in Runtime Admin.
       • Rule Expression: Your origin ruleset.

   For hybrid storefronts with Storefront Next, always include /resource/auth/.* and ^/action/.* paths to your eCDN rule expression to route all requests to server resources and actions to Storefront Next on MRT.

   • For more information about routing traffic to MRT, see:

     • TLS Certificates
     • DNS CNAME
     • Configure Your Environment

2. For Storefront Next: Update Storefront Next configuration.

   This guide assumes that you’ve already set up a Storefront Next application. If you haven’t created a Storefront Next application yet, complete the initial setup before proceeding with hybrid configuration.

   To enable hybrid mode in your Storefront Next application, update your config.server.ts file to set hybrid.enabled: true and specify which routes to redirect to SFRA/SiteGenesis using legacyRoutes:

   Configuration options:

   • enabled: Set to true to enable hybrid mode. This setting allows your Storefront Next application to coexist with SFRA/SiteGenesis pages.
   • legacyRoutes: An array of route patterns to redirect to SFRA/SiteGenesis instead of being handled by Storefront Next.

   Route parameterization:

   The legacyRoutes configuration supports parameterization using React Router syntax:

   • Exact path matches: /checkout, /cart — Matches only the exact path
   • Dynamic segments: /checkout/:confirmationId, /product/:id — The :parameter syntax matches any value in that segment
   • Multiple parameters: /category/:categoryId/item/:itemId — Supports multiple dynamic segments in a single route

   Any request matching a pattern in legacyRoutes is redirected to the corresponding SFRA/SiteGenesis page, maintaining the full URL path and query parameters.

   Update the configuration directly in config.server.ts or use environment variable overrides for per-environment customization. To override via environment variables:

   For more information about configuration options and environment variable overrides, see Project Configuration.

Include these patterns so React Router server endpoints continue to work.

Add patterns for Storefront Next pages that your team has already migrated.

This example keeps homepage, auth, product, category, search, account, and server endpoints on Storefront Next.

Storefront Next implements merging basket on Shopper Login. The B2C Commerce platform provides a default, out-of-the-box implementation for merging baskets. Some customers need further customization and can use the sample implementation in Github GIST, which behaves like the default implementation, making it an ideal starting point for customization.

After a guest shopper logs in as a registered shopper, manage the shopper basket with the dw.order.mergeBasket hook (added in B2C Commerce version 25.10). Invoke this merge hook using either of these options:

• With a REST API call for headless storefronts
• Within the controller logic for non-headless storefronts

After invoking the hook, verify that the guest shopper’s basket is appropriately combined with the registered shopper’s basket.

When you use the transferBasket endpoint with the parameter merge=true, the guest basket is transferred and becomes the current basket. The dw.order.mergeBasket hook is then invoked, merging the registered shopper’s basket into the current basket. This API behavior is described in the transferBasket specification.

To add the basket merge hook into an existing controller, use the Script API to transfer the basket from the guest shopper to the registered shopper by calling BasketMgr.getCurrentBasket(). Personal information, such as payment/address information, is removed from the guest basket, and it becomes the current basket. Invoke the dw.order.mergeBasket hook to process the merge ensuring a seamless and consistent shopper experience. Use BasketMgr.getStoredBasket() to access the registered shopper’s basket, which is deleted when the request ends.

For example: to add the basket merge hook for Account-Login, append the merge handling to the login function. The Github GIST contains a detailed explanation of how to accomplish this, but the following example provides a quick summary of how baskets can be obtained and merged using Script API with the dw.order.mergeBasket hook:

For basket best practices in a hybrid implementation, see Hybrid Storefront Basket Guidance.

For Hybrid Auth, we recommend the use of Shopper Context to drive geolocation-based personalizations for:

• Promotions and other experiences based on request.geolocation.* attributes in Customer Groups
• Region-specific content based on client IP

To maintain consistency across a hybrid storefront, use the same geolocation for both SCAPI and controller calls:

• Call Shopper Context with the clientIp.

• Set the evaluateContextWithClientIp query parameter to true. Set &evaluateContextWithClientIp=true for the IP-related context features to work correctly.

• For example:

For additional details, see:

• Shopper Context Guides
• Shopper Context API Docs
• Shopper Context Script API You can use the Shopper Context Script API to personalize shopper experiences for hybrid implementations that use SFRA/SiteGenesis pages.

To enable or disable DNT synchronization in Business Manager, navigate to Merchant Tools > Select Site > Site Preferences > Hybrid Auth Settings.

SFRA-only sites: The DNT value is automatically synchronized to the extended session, providing a seamless experience across sessions.

SFRA and Storefront Next hybrid implementations: When you enable both Hybrid Auth and DNT synchronization, the tracking consent provided by a shopper on one site is automatically synchronized with the other site. For example, in a hybrid site where the home page runs on Storefront Next and the cart page runs on SFRA:

• On the home page (Storefront Next), the shopper is presented with a consent form and provides their tracking preference.
• When the shopper navigates to the cart page (SFRA), the DNT value from Storefront Next is synchronized with SFRA.
• As a result, the SFRA cart page doesn’t prompt the shopper for tracking consent again.