My SFCC Pills.

1. Why Hybrid?

A hybrid architecture lets you combine the strengths of both SFRA and headless development. Use SFRA for checkout, account management, and promotions: where built-in Commerce Cloud modules offer robust features. For product listings, landing pages, and marketing-driven frontends, headless technologies like PWA Kit shine.

This approach enables a phased migration strategy. Brands can launch faster with SFRA and later integrate headless for flexibility and innovation, without disrupting core commerce processes.

2. Core Components

• SFRA (Storefront Reference Architecture): Provides controllers, business logic, promotion engine, and integrated checkout with Business Manager configuration. It supports full customization through cartridge layering. (Official Documentation)
• Composable Storefront (PWA Kit + Managed Runtime): React-based headless frontend that uses Salesforce Commerce API (SCAPI) to interact with B2C backend. Ideal for PDP, PLP, search, and marketing pages. (Official Documentation)

3. Key Integration Principles

• Use SCAPI in Headless, Script API in SFRA: Do not mix API strategies. SCAPI endpoints (e.g. POST /baskets) are intended for headless clients. SFRA should continue using platform-side Script APIs like BasketMgr.getCurrentOrNewBasket(). (Hybrid Storefront Guide)
• Session & Basket Sync:
  • Before v25.3: Use the Plugin SLAS integration to manually sync session data.
  • From v25.3+: Use Hybrid Auth to natively sync SLAS and dwsid between SFRA and Composable Storefront. (Hybrid Auth Documentation)
• Routing via CDN: Configure your CDN (e.g. Cloudflare, Fastly, eCDN) to forward specific paths (e.g. /product/, /category/) to PWA Kit, and others (e.g. /checkout/, /account/) to the SFRA controllers.

4. Implementation Workflow

1. Identify which parts of the site benefit most from headless (PDP, PLP, landing pages).
2. Set up the Composable Storefront and integrate it with SCAPI.
3. Enable Hybrid Authentication and remove legacy session sync methods if applicable.
4. Configure CDN and routing to ensure correct traffic flow between SFRA and headless layers.
5. Ensure session and basket data is correctly maintained across layers.
6. Test performance, session integrity, and customer experience across both storefronts.

5. Benefits

• Faster innovation cycles: Marketing teams can update headless components without full platform releases.
• Improved scalability: Decouple performance bottlenecks by scaling frontend and backend independently.
• Minimized risk: Gradual migration ensures checkout and promotions remain stable while modernizing frontend UI.

6. Considerations

• Architectural complexity: Teams must manage two codebases and environments.
• Monitoring and troubleshooting: Requires observability across both SFRA and PWA Kit layers.
• Session and identity management: Misconfigurations can result in broken basket or login flows.

Conclusion

A hybrid SFRA and headless strategy allows brands to modernize at their own pace while maintaining stability and leveraging existing investments. With Salesforce’s native support for Hybrid Auth, SCAPI, and composable storefronts, this approach is now fully supported and recommended for scalable, future-ready commerce architecture.