Hybrid Storefront Guidance

A B2C Commerce hybrid implementation allows you to combine 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.

For Composable Storefront implementation details, see Use Composable Storefront in a Hybrid Implementation.

The following sections provide best practices for hybrid storefront implementations. For additional hybrid implementation guidance, see Use Composable Storefront in a Hybrid Implementation.

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 implemnt your PDP in SFRA or SG, use the Script API getCurrentOrNewBasket(). 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.

Minimize the use of session bridging (POST sessions and POST customers/auth). Only create new sessions when necessary, and reuse existing sessions as long as possible.

Apply this same approach to JWT creation for SCAPI/OCAPI calls to ensure optimal performance.