sfnext-hybrid-storefronts

What this skill does

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

```bash
# 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:

```bash
# 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:

| 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