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 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:

Example for eCDN:

1. 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.
2. 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.

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

• 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:

• PUBLIC__app__hybrid__legacyRoutes:

• 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:

• PUBLIC__app__hybrid__legacyRoutes:

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

• PUBLIC__app__hybrid__legacyRoutes:

• 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:

• PUBLIC__app__hybrid__legacyRoutes:

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

• PUBLIC__app__hybrid__legacyRoutes:

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

• PUBLIC__app__hybrid__legacyRoutes:

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.