Hybrid Storefronts Skill Skill

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:

User clicks <Link to="/checkout">
React Router begins client-side navigation
Middleware checks if /checkout matches any pattern in legacyRoutes
If yes → forces a full-page navigation so the CDN/proxy routes to SFRA
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:

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

SFRA to Storefront Next

When navigating from SFRA to Storefront Next:

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

Storefront Next to SFRA

When navigating from Storefront Next to SFRA:

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

Traffic Routing Patterns

Gradual Migration Strategy

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

Required Routing Rules

Some patterns must always route to Storefront Next:

| Pattern | Why | | -------------- | ---------------------------------------------- | | ^/resource.* | React Router resource routes (data endpoints) | | ^/action/.* | React Router actions (form submissions) |

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

| Issue | Cause | Solution | | --------------------------------- | -------------------------- | ------------------------------------------------- | | Lost session crossing storefronts | Cookie domain mismatch | Ensure shared parent domain | | Cart items disappear | Basket not synced | Verify session bridge cookies (dwsid, cc-*) | | Redirect loops | Conflicting routing rules | Check eCDN rules and legacyRoutes consistency | | 404 on SFRA pages (local dev) | Missing from routing rules | Add path to HYBRID_ROUTING_RULES | | React Router 404 on legacy route | Missing from legacyRoutes | Add path to PUBLIC__app__hybrid__legacyRoutes |

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

Agent Skills: Hybrid Storefronts Skill

Install this agent skill to your local

Skill Files