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 both unprefixed paths and paths with a /:siteId/:locale prefix. Prefix values can be aliases or raw IDs.
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.

The examples use the optional prefix pattern ^(/[^/]+/[^/]+)?. The first segment matches any site value, and the second segment matches any locale value. Each value can be an alias or a raw ID, so the eCDN rule doesn’t need an allowlist of every site-locale combination. If your application uses a different url.prefix shape, replace the entire sample prefix with a pattern for that shape.

For configurations where Storefront Next handles the Home route, use a separate Home expression: ^(/|/[^/]+/[^/]+/)$. It matches / and a prefixed Home path such as /us/en-US/. When an exactly two-segment path represents prefixed Home, end it with a trailing slash; an unprefixed two-segment route must use its canonical form without a trailing slash, such as /product/123. This convention lets eCDN distinguish the two shapes without maintaining site and locale allowlists. The expression intentionally doesn’t match /us/en-US or /us/en-US/home. Configure url.prefix, generated Home links, and SFRA/SiteGenesis redirects to use the canonical trailing-slash Storefront Next root.

A prefixed Home URL must end with a trailing slash, for example, /us/en-US/. Reserve the exactly-two-segment trailing-slash shape for prefixed Home; don’t use that shape for an unprefixed two-segment route such as /product/123.

Important

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 "^(/|/[^/]+/[^/]+/)$" or http.request.uri.path matches "^(/[^/]+/[^/]+)?/(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.