Hybrid Storefront Routing Matrix

Use this routing matrix to choose a hybrid storefront split between Storefront Next and SFRA/SiteGenesis.

The examples in this guide apply to all hybrid setups:

For local hybrid proxy setups, set HYBRID_ROUTING_RULES in your environment variables.
For on-demand sandbox (ODS) and production setups, paste the same rule expression directly into eCDN routing rules.

Use the Right Rule Syntax by Setup Type

Use the same expression pattern in every setup, but use different input formats:

Local hybrid proxy (.env): Assign the rule to HYBRID_ROUTING_RULES and wrap the expression in single quotes.
ODS and production (eCDN UI): Paste only the rule expression in Rule expression. Do not include HYBRID_ROUTING_RULES= and do not wrap the expression in single quotes.

Example for local hybrid proxy:

1HYBRID_ROUTING_RULES='(http.request.uri.path matches "^/category.*" or http.request.uri.path matches "^/product.*")'

Example for eCDN:

1(http.request.uri.path matches "^/category.*" or http.request.uri.path matches "^/product.*")

Architectural Foundations

HYBRID_ROUTING_RULES: A single Cloudflare expression used by the edge routing layer. The pattern supports optional /:siteId/:locale prefixes using ^(/[^/]+/[^/]+)?.
PUBLIC__app__hybrid__legacyRoutes: A JSON array used by the Storefront Next client-side routing middleware to force a full-page navigation to SFRA/SiteGenesis routes.

Matrix Configurations

Check out some examples of the different ways you can set up your hybrid storefront.

Matrix-01: Modern Core (Home, PDP, PLP on Storefront Next)

Strategy: The active customer discovery funnel, search, account, and social authentication routes run on Storefront Next. Only checkout (/cart and /checkout) stays on SFRA/SiteGenesis.
HYBRID_ROUTING_RULES:

1HYBRID_ROUTING_RULES='(http.request.uri.path matches "^(/[^/]+/[^/]+)?/(|home|category|product|search|account|login|signup|logout|reset-password|social-callback)(/.*)?$" or http.request.uri.path matches "^/resource.*" or http.request.uri.path matches "^/action/.*" or http.request.uri.path matches ".*\.data.*" or http.request.uri.path matches "^/assets/.*" or http.request.uri.path matches "^/favicon\.ico$")'

PUBLIC__app__hybrid__legacyRoutes:

1PUBLIC__app__hybrid__legacyRoutes='["/cart", "/checkout"]'

Matrix-02: Modern Checkout (Cart and Checkout on Storefront Next)

Strategy: Use this split to test or roll out a Storefront Next checkout while keeping browse and discovery routes on SFRA/SiteGenesis.
HYBRID_ROUTING_RULES:

1HYBRID_ROUTING_RULES='(http.request.uri.path matches "^(/[^/]+/[^/]+)?/(cart|checkout)(/.*)?$" or http.request.uri.path matches "^/resource.*" or http.request.uri.path matches "^/action/.*" or http.request.uri.path matches ".*\.data.*" or http.request.uri.path matches "^/assets/.*" or http.request.uri.path matches "^/favicon\.ico$")'

PUBLIC__app__hybrid__legacyRoutes:

1PUBLIC__app__hybrid__legacyRoutes='["/", "/category/:id", "/product/:id", "/search", "/account", "/login", "/signup", "/reset-password"]'

Matrix-03: Modern Entry Only (Home on Storefront Next)

Strategy: Use this split during early pilots when only the home page is modernized and deeper flows remain on SFRA/SiteGenesis.
HYBRID_ROUTING_RULES:

1HYBRID_ROUTING_RULES='(http.request.uri.path matches "^(/[^/]+/[^/]+)?/(|)(/.*)?$" or http.request.uri.path matches "^/resource.*" or http.request.uri.path matches "^/action/.*" or http.request.uri.path matches ".*\.data.*" or http.request.uri.path matches "^/assets/.*" or http.request.uri.path matches "^/favicon\.ico$")'

PUBLIC__app__hybrid__legacyRoutes:

1PUBLIC__app__hybrid__legacyRoutes='["/category/:id", "/product/:id", "/search", "/account", "/login", "/signup", "/reset-password", "/cart", "/checkout"]'

Matrix-04: Legacy Entry Only (Home on SFRA)

Strategy: Use this split when the home page stays on SFRA/SiteGenesis, while deeper browse and transactional routes move to Storefront Next.
HYBRID_ROUTING_RULES:

1HYBRID_ROUTING_RULES='(http.request.uri.path matches "^(/[^/]+/[^/]+)?/(category|product|search|account|login|signup|logout|reset-password|social-callback|cart|checkout)(/.*)?$" or http.request.uri.path matches "^/resource.*" or http.request.uri.path matches "^/action/.*" or http.request.uri.path matches ".*\.data.*" or http.request.uri.path matches "^/assets/.*" or http.request.uri.path matches "^/favicon\.ico$")'

PUBLIC__app__hybrid__legacyRoutes:

1PUBLIC__app__hybrid__legacyRoutes='["/"]'

Matrix-05: Catalog-Only Migration (PLP/PDP on Storefront Next)

Strategy: Move high-volume catalog routes (category, product, search) to Storefront Next while preserving legacy account and checkout routes.
HYBRID_ROUTING_RULES:

1HYBRID_ROUTING_RULES='(http.request.uri.path matches "^(/[^/]+/[^/]+)?/(category|product|search)(/.*)?$" or http.request.uri.path matches "^/resource.*" or http.request.uri.path matches "^/action/.*" or http.request.uri.path matches ".*\.data.*" or http.request.uri.path matches "^/assets/.*" or http.request.uri.path matches "^/favicon\.ico$")'

PUBLIC__app__hybrid__legacyRoutes:

1PUBLIC__app__hybrid__legacyRoutes='["/", "/account", "/login", "/signup", "/reset-password", "/cart", "/checkout"]'

Matrix-06: Account and Auth Only (Identity Flows on Storefront Next)

Strategy: Move account and authentication experiences to Storefront Next while leaving catalog and checkout on SFRA/SiteGenesis.
HYBRID_ROUTING_RULES:

1HYBRID_ROUTING_RULES='(http.request.uri.path matches "^(/[^/]+/[^/]+)?/(account|login|signup|logout|reset-password|social-callback)(/.*)?$" or http.request.uri.path matches "^/resource.*" or http.request.uri.path matches "^/action/.*" or http.request.uri.path matches ".*\.data.*" or http.request.uri.path matches "^/assets/.*" or http.request.uri.path matches "^/favicon\.ico$")'

PUBLIC__app__hybrid__legacyRoutes:

1PUBLIC__app__hybrid__legacyRoutes='["/", "/category/:id", "/product/:id", "/search", "/cart", "/checkout"]'

Global Framework Requirements

Keep these route clauses in every matrix configuration:

^/resource.* and ^/action/.* to avoid loop routing on modern layouts and handlers.
.*\.data.* to prevent React Router 7 data prefetch requests from being routed to SFRA/SiteGenesis.
^/assets/.* and ^/favicon\.ico$ for core Storefront Next static assets.