Hybrid Implementation Guidance

A hybrid storefront allows the combination of traditional storefronts built on Salesforce Commerce Cloud with decoupled, headless Composable Storefront sites. B2C Commerce supports hybrid storefront implementations so that you can execute on your headless strategy with reduced cost and faster time to market.

A B2C Commerce hybrid implementation allows you to combine Storefront Reference Architecture (SFRA) and script API with Composable Storefront and SCAPI. For example, you can implement PWA Kit for your product detail pages (PDP) and product listing pages (PLP) while providing your checkout in SFRA. Implementations using Sitegenesis with Composable Storefront are not officially supported.

This hybrid approach offers the following benefits:

• Flexibility and Customization: You can create tailored storefronts that meet specific business needs and customer expectations.
• Scalability: The modular nature of Composable Storefront allows for easy scaling and adaptation to changing requirements.
• Seamless Integration: SCAPI ensures seamless integration with B2C Commerce Cloud, providing access to a wide range of commerce functionalities.
• Enhanced User Experience: By combining the power of SCAPI and the flexibility of Composable Storefront, businesses can deliver personalized and engaging shopping experiences.

Starting with B2C Commerce version 25.3, Hybrid Authentication replaces Plugin SLAS. Hybrid Auth is a standalone solution for implementations that need both SFRA/SiteGenesis authorization and Shopper Login and API Access Service (SLAS) authorization. This means you need both a dwsid (SFRA/SiteGenesis) and a JSON Web Token (SLAS), and these tokens must be kept in sync. Hybrid Auth is an improvement over the Plugin SLAS approach, offering enhanced performance and stability of hybrid storefronts by moving the feature directly into the B2C Commerce platform.

Hybrid storefronts that use Plugin SLAS will continue to work, but we highly encourage adopting hybrid auth.

For implementation details, see Hybrid Authentication.

Decide on the goals, scope, and timeline for your hybrid (phased headless) rollout. Keep in mind that the longer your site is in hybrid mode, the more time you have to spend on the operating complexity involved. Set a due date for transitioning to a 100% Composable site.

A principal benefit of a single page application (SPA) like PWA Kit is that the app bundle is sent to the client and subsequent page requests can often be served without server requests. For this reason, we highly recommend having more than 1 page on PWA Kit to gain performance and shopper UX efficiencies, for example: instead of just your homepage - migrate your homepage and next 1-2 most common journey steps (homepage & search; homepage & our brand). Use the analytics tools at your disposal to chart these common customer journey paths through your site.

The following sections provide best practices for hybrid storefront implementations, with particular focus on basket management and technical implementation details.

Only create a basket when there is a need, for example, when adding the first product or storing customer information such as address information. This is a general best practice but is especially important for hybrid storefronts.

SFRA/SG (controller-based) storefronts use the Script API getCurrentOrNewBasket() to create baskets, while PWA Kit uses SCAPI POST baskets to create baskets.

When implementing a hybrid site, utilize the API that best fits your use case. For example, if you implement your PDP in SFRA or SG, use the Script API getCurrentBasket(). If your hybrid site uses PWA Kit for the PDP, use SCAPI POST baskets.

This best practice aligns with only creating a basket when adding items to it, not beforehand, in order to avoid empty baskets.

Use caution with asynchronous functions when managing baskets:

• Single page applications (SPA) such as PWA Kit follow a different request execution style than traditional platform development models like SFRA. SPAs provide more focus on a non-blocking architecture, in which APIs are used in an asynchronous way for lazy loading, preloading data, or handling user interactions.
• Consider this request architecture carefully and understand what type of requests are executed when, where, and in what sequence.
• If the same type of request (updating the same data) executes in parallel, those requests can overwrite each other and the last one to complete produces the final result, potentially causing unexpected behavior. For example, a basket that is created through multiple steps, including various data validations and dependencies, can increase the likelihood of race conditions if not correctly implemented. An asynchronous design pattern, for example: promises, async/await, or callbacks, is required to manage dependencies where requests rely on each other's completion and avoid potential issues.

• Do not create baskets in hooks with getCurrentOrNewBasket().
• Avoid using getCurrentBasket() in hooks. Instead, use the basket that is passed, for example: dw.ocapi.shop.basket.afterPATCH:

• In general, outgoing calls in hooks should be avoided due to potential challenges with connectivity and latency to other systems. Instead, these calls should be initiated by the client system, such as the server runtime, Backend for Frontend (BFF), or client browser. Specifically, avoid making calls to OCAPI and SCAPI, because internal calls can bind resources, impacting performance and scalability. Additionally, when the same objects are modified in a hook and in an outgoing call, race conditions can occur, leading to unpredictable behavior. The recommended approach is to call the respective Script API function from the hook or call the respective SCAPI resource outside of a hook from the client side.

These are general best practices but are especially important for hybrid storefronts.

• For hybrid implementation details that apply to hybrid authentication, see Hybrid Authentication.
• For hybrid implementation details that apply to Plugin SLAS, see Configure a Hybrid Storefront with Plugin SLAS.