Hybrid Storefronts Skill

This skill covers running Storefront Next alongside an existing SFRA or SiteGenesis storefront — enabling gradual migration without a full rewrite.

Overview

A hybrid storefront splits traffic between Storefront Next (for new or migrated pages) and an existing SFRA/SiteGenesis storefront (for pages not yet migrated). Session bridging ensures users maintain authentication and cart state across both implementations.

Architecture

Customer Request
      ↓
  CDN / eCDN (Cloudflare)        ← Production: routes based on URL patterns
      ↓
  ┌─────────────────────────────┐
  │ Storefront Next │ SFRA/SiteGenesis │
  │  (MRT)          │  (B2C Instance)  │
  └────────┴────────────────────┘
       ↕ Session Bridge (shared cookies) ↕

Production: Cloudflare eCDN handles routing between Storefront Next and SFRA based on origin rules.

Local Development: A Vite dev server plugin (hybridProxyPlugin from @salesforce/storefront-next-dev) proxies non-matching requests to your SFCC sandbox, simulating the eCDN split at localhost:5173.

Configuration

Hybrid mode is configured entirely through environment variables — there is no extension directory.

Application Config (All Environments)

These PUBLIC__ variables are bundled into the app and required in all environments:

# Enable hybrid mode — activates the client-side legacy-routes middleware
PUBLIC__app__hybrid__enabled=true

# Routes that belong to SFRA — client-side <Link> clicks to these trigger full-page loads
# Supports exact paths and React Router parameterized routes
PUBLIC__app__hybrid__legacyRoutes='["/cart", "/checkout", "/product/:id"]'

Proxy Plugin Config (Local Development Only)

These configure the Vite dev server proxy and have no effect in production:

# Enable the proxy
HYBRID_PROXY_ENABLED=true

# Your SFCC sandbox origin
SFCC_ORIGIN=https://zzrf-001.dx.commercecloud.salesforce.com

# Routing rules: Cloudflare eCDN expression format
# Paths matching → Storefront Next; paths not matching → proxied to SFCC
HYBRID_ROUTING_RULES='(http.request.uri.path matches "^/$" or http.request.uri.path matches "^/product.*" or http.request.uri.path matches "^/category.*" or http.request.uri.path matches "^/resource.*" or http.request.uri.path matches "^/action/.*")'

# Optional: locale for SFRA path transformation (falls back to PUBLIC__app__i18n__fallbackLng)
HYBRID_PROXY_LOCALE=en-GB

Client-Side Navigation Middleware

The legacy-routes.client.ts middleware intercepts client-side navigation to SFRA-owned routes:

1. User clicks <Link to="/checkout">
2. React Router begins client-side navigation
3. Middleware checks if /checkout matches any pattern in legacyRoutes
4. If yes → forces a full-page navigation so the CDN/proxy routes to SFRA
5. If no → continues normal client-side rendering

This prevents React Router from trying to render pages that belong to SFRA.

Session Bridging

Both storefronts share the same session cookies (dwsid, cc-*) on a common domain:

Cookie Handling (Local Dev)

The proxy handles cookies in three layers:

1. Set-Cookie header rewriting — SFCC response Domain=.salesforce.com → Domain=localhost
2. Storefront Next server cookies — Written directly to localhost, no rewriting needed
3. Client-side cookie interception — Injected script patches document.cookie for SFRA’s JS

SFRA to Storefront Next

When navigating from SFRA to Storefront Next:

1. SFRA provides session credentials (dwsgst/dwsrst tokens)
2. Storefront Next exchanges the bridge token for SLAS tokens
3. Normal SLAS cookie-based auth resumes

Storefront Next to SFRA

When navigating from Storefront Next to SFRA:

1. Shared dwsid cookie maintains session continuity
2. Full-page navigation triggered by legacy-routes middleware
3. CDN/proxy routes request to SFCC origin

Traffic Routing Patterns

Gradual Migration Strategy

1. Phase 1 — Homepage, product, and category pages on Storefront Next
2. Phase 2 — Account and search pages
3. Phase 3 — Cart and checkout flow
4. Phase 4 — Full migration, remove SFRA

Required Routing Rules

Some patterns must always route to Storefront Next:

Keep Rules in Sync

HYBRID_ROUTING_RULES (what Storefront Next owns) and PUBLIC__app__hybrid__legacyRoutes (what SFRA owns) are complementary. Any path not in routing rules that could be a <Link> target should be in legacyRoutes.

Common Considerations

• Cookie domains — Both storefronts must share a cookie domain for session bridging
• CDN configuration — Update eCDN origin rules as pages migrate
• SEO continuity — Maintain URL structure to preserve search rankings
• Cart synchronization — Basket state is consistent via shared session cookies

Troubleshooting

Related Skills

• storefront-next:sfnext-authentication - SLAS token management and session cookies
• storefront-next:sfnext-deployment - MRT deployment for hybrid setup
• storefront-next:sfnext-configuration - Environment configuration for hybrid mode