@salesforce/b2c-dx-mcp 2.1.2 → 3.0.0

package/content/guidance/storefront-next/sfnext-extensions/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: sfnext-extensions
+description: Build extensions for Storefront Next using target-config.json, target points, extension routes, and translation namespaces. Use when creating modular features, inserting components into UI targets, adding extension routes, adding a section to an existing page, or using SFDC_EXT_ integration markers. Covers the base-audit decision gate (deciding whether to extend at all vs token/variant override), extension structure, targetId configuration, and extension registration in src/extensions/config.json.
+---
+
+# Extensions Skill
+
+This skill covers the Storefront Next extension system — modular features that plug into the storefront via target points.
+
+## Overview
+
+Extensions are self-contained feature modules that add components, routes, translations, and providers to a Storefront Next storefront without modifying core code.
+
+## Before You Build — Audit the Base First (Decision Gate)
+
+An extension is the right tool for adding something the storefront does **not already render**. Before scaffolding one, confirm you actually need it — a duplicated section costs you on every page load, every test, and every design sync.
+
+Run this gate **before writing any extension code**:
+
+1. **Find the base.** Open the relevant route in `src/routes/` and trace every component it renders.
+2. **Check each section you intend to add.** Does the base already render equivalent content at that location (a description, accordion, badge, banner, title…)?
+   - **YES** → do not create a parallel component. Restyle it through the token/brand layer (a CVA variant or `brand.css` value), or inject into a UITarget slot on the existing content. Adding a duplicate section is a bug, not a feature.
+   - **NO** → an extension is justified. Continue to the structure below and register it at the correct `targetId`.
+3. **Decide the layer for what's missing:**
+
+   ```
+   Is the change purely visual (color, font, spacing)?
+     └─ YES → Token / CVA change (brand.css or a component variant). No extension needed.
+     └─ NO  → Is the new structure needed by only one storefront/vertical?
+                 └─ YES → Extension at a UITarget slot (this skill). Never edit core.
+                 └─ NO  → It's a shared pattern — add a slot/render-prop to the BASE
+                          component instead, and let each consumer fill it.
+   ```
+
+**Rule of thumb:** extensions *add what is missing*; they never recreate what already exists. When in doubt, prefer a UITarget slot or a token override over a new component.
+
+See [Base Audit Reference](references/BASE-AUDIT.md) for worked examples of the gate.
+
+## Extension Structure
+
+```
+src/extensions/my-extension/
+├── target-config.json    # Target configuration (components/providers)
+├── components/           # Extension components
+├── routes/              # Extension routes (auto-registered)
+├── locales/             # Extension translations (auto-namespaced)
+└── providers/           # Extension context providers
+```
+
+## Target Configuration
+
+The `target-config.json` file declares how the extension integrates:
+
+```json
+{
+  "components": [
+    {
+      "targetId": "header.before.cart",
+      "path": "extensions/my-extension/components/badge.tsx",
+      "order": 0
+    }
+  ],
+  "contextProviders": [
+    {
+      "path": "extensions/my-extension/providers/my-provider.tsx",
+      "order": 0
+    }
+  ]
+}
+```
+
+### Target Points
+
+Target points are named insertion slots in the storefront layout (for example, `header.before.cart`). Extensions insert components at these points via `targetId`.
+
+Extension availability is managed in `src/extensions/config.json`, where each extension is keyed by an `SFDC_EXT_*` marker.
+
+## Extension Routes
+
+Files in the `routes/` directory auto-register as routes:
+
+```typescript
+// src/extensions/my-extension/routes/my-route.tsx
+export function loader() {
+    return { message: 'Hello' };
+}
+
+export default function MyRoute() {
+    const { message } = useLoaderData();
+    return <div>{message}</div>;
+}
+```
+
+## Extension Translations
+
+Translations are auto-namespaced as `extPascalCase` based on the directory name:
+
+```
+src/extensions/my-extension/locales/
+├── en-US/translations.json
+└── it-IT/translations.json
+```
+
+```typescript
+const {t} = useTranslation('extMyExtension');
+t('welcome');
+```
+
+## Integration Markers
+
+Mark extension integration points in core code:
+
+```typescript
+// Single line marker
+/** @sfdc-extension-line SFDC_EXT_MY_FEATURE */
+import myFeature from '@extensions/my-feature';
+
+// Block marker
+{/* @sfdc-extension-block-start SFDC_EXT_MY_FEATURE */}
+<Link to="/my-feature">My Feature</Link>
+{/* @sfdc-extension-block-end SFDC_EXT_MY_FEATURE */}
+```
+
+See [Extension Examples Reference](references/EXTENSION-EXAMPLES.md) for complete examples.
+
+## Best Practices
+
+1. **Self-contained** — Each extension should be independent
+2. **Use target points** — Insert UI via `target-config.json` rather than editing core files
+3. **Namespace translations** — Auto-namespacing prevents collisions
+4. **Order matters** — Use `order` in `target-config.json` to control rendering order
+
+## Related Skills
+
+- `storefront-next:sfnext-i18n` - Translation patterns and namespace usage
+- `storefront-next:sfnext-routing` - How extension routes integrate with the router
+- `storefront-next:sfnext-components` - Component patterns used in extensions
+
+## Reference Documentation
+
+- [Base Audit Reference](references/BASE-AUDIT.md) - Worked examples of the decision gate (extend vs token/variant vs base slot)
+- [Extension Examples Reference](references/EXTENSION-EXAMPLES.md) - Complete extension examples

package/content/guidance/storefront-next/sfnext-extensions/references/BASE-AUDIT.md

@@ -0,0 +1,65 @@
+# Base Audit Reference
+
+Use this before building an extension or adding a section to a page. The goal is to decide **whether to extend at all**, and if so, **at which layer** — so you never ship a component that duplicates something the base template already renders.
+
+## The gate, step by step
+
+1. **Find the base component.** Open the route in `src/routes/` and trace what it renders down to the section you care about.
+2. **Check every rendered section.** For each thing you want to add, ask: does the base already render equivalent content here?
+3. **Branch:**
+   - **Already rendered** → restyle via token/brand layer or a CVA variant, or inject into a UITarget slot on the existing content. Do **not** create a parallel component.
+   - **Not rendered** → an extension (or a base slot) is justified.
+4. **Pick the layer for what's genuinely missing:**
+
+   ```
+   Purely visual (color, font, spacing)?
+     └─ YES → Token / CVA change. No extension.
+     └─ NO  → Needed by only one storefront/vertical?
+                 └─ YES → Extension at a UITarget slot.
+                 └─ NO  → Shared pattern → add a slot/render-prop to the BASE component.
+   ```
+
+## Worked examples
+
+### Example 1 — duplicate section (wrong) vs additive section (right)
+
+```
+❌ WRONG — base ProductView already renders a description accordion ("What's in it:").
+           The extension adds its own "What's in it" section → duplicate content on the PDP.
+
+✅ CORRECT — base already renders description + adapter sections (Ingredients, How to Use…).
+             The extension adds ONLY the sections the base does not have
+             (e.g. "Shipping & Fresh Guarantee", a brand story block).
+```
+
+### Example 2 — restyle, don't re-render
+
+```
+❌ WRONG — base renders the product title in ProductInfo.
+           A brand "stamp" extension renders the product title again.
+
+✅ CORRECT — the stamp adds ONLY the brand line ("ACME · Handmade")
+             above the existing ProductInfo. The title stays where the base renders it.
+```
+
+### Example 3 — pick the right layer
+
+| Desired change | Already in base? | Correct layer |
+|----------------|------------------|---------------|
+| Make the primary button green | Button exists | Token change in `brand.css` (no extension) |
+| Add a "compact" tile density | Tile exists | New CVA variant on the tile |
+| Add a site-wide promo banner above nav | Not rendered, one storefront only | Extension at `header.before.nav` |
+| Add a "sustainability meta" line every storefront will want | Not rendered, shared pattern | Slot / render-prop on the BASE tile/product component |
+
+## Finding the slots and base render points
+
+```bash
+# from packages/template-retail-rsc-app — list every UITarget slot in use
+rg "UITarget" src/ -l
+
+# read a target file to find its targetId values, e.g.
+#   <UITarget targetId="header.before.nav" />
+#   <UITarget targetId="pdp.add-to-cart.below" />
+```
+
+If no suitable slot exists where you need it and the page is one you own, a direct route edit is acceptable — but still run the audit first so you don't duplicate existing content. Prefer a UITarget slot when one fits.

package/content/guidance/storefront-next/sfnext-extensions/references/EXTENSION-EXAMPLES.md

@@ -0,0 +1,116 @@
+# Extension Examples Reference
+
+## Store Locator Extension
+
+A complete extension adding store locator functionality:
+
+```
+src/extensions/store-locator/
+├── target-config.json
+├── components/
+│   ├── store-locator-badge.tsx    # Badge in header
+│   └── store-locator-map.tsx      # Map component
+├── routes/
+│   └── store-locator.tsx          # /store-locator page
+├── locales/
+│   ├── en-US/translations.json
+│   └── de-DE/translations.json
+└── providers/
+    └── store-provider.tsx         # Store data context
+```
+
+### target-config.json
+
+```json
+{
+  "components": [
+    {
+      "targetId": "header.after.logo",
+      "path": "extensions/store-locator/components/store-locator-badge.tsx",
+      "order": 0
+    }
+  ],
+  "contextProviders": [
+    {
+      "path": "extensions/store-locator/providers/store-provider.tsx",
+      "order": 0
+    }
+  ]
+}
+```
+
+### Route
+
+```typescript
+// src/extensions/store-locator/routes/store-locator.tsx
+import { createApiClients } from '@/lib/api-clients';
+import { useTranslation } from 'react-i18next';
+
+export function loader({ context }: LoaderFunctionArgs) {
+    const clients = createApiClients(context);
+    return {
+        stores: clients.shopperStores.getStores({...}).then(({ data }) => data),
+    };
+}
+
+export default function StoreLocatorPage({ loaderData }) {
+    const { t } = useTranslation('extStoreLocator');
+
+    return (
+        <div>
+            <h1>{t('title')}</h1>
+            {/* Render store map and list */}
+        </div>
+    );
+}
+```
+
+### Translations
+
+```json
+// src/extensions/store-locator/locales/en-US/translations.json
+{
+  "title": "Find a Store",
+  "searchPlaceholder": "Enter city or zip code",
+  "noResults": "No stores found nearby"
+}
+```
+
+## Integration Marker Patterns
+
+### Single-Line Import
+
+```typescript
+/** @sfdc-extension-line SFDC_EXT_STORE_LOCATOR */
+import StoreLocatorBadge from '@extensions/store-locator/components/store-locator-badge';
+```
+
+### Block Integration
+
+```typescript
+/* @sfdc-extension-block-start SFDC_EXT_STORE_LOCATOR */
+<Link to="/store-locator" className="flex items-center gap-2">
+    <MapPinIcon className="h-4 w-4" />
+    <span>{t('storeLocator')}</span>
+</Link>
+/* @sfdc-extension-block-end SFDC_EXT_STORE_LOCATOR */
+```
+
+## BOPIS Extension (Buy Online, Pick Up In Store)
+
+```json
+{
+  "components": [
+    {
+      "targetId": "product.detail.fulfillment",
+      "path": "extensions/bopis/components/pickup-selector.tsx",
+      "order": 0
+    },
+    {
+      "targetId": "cart.item.fulfillment",
+      "path": "extensions/bopis/components/pickup-info.tsx",
+      "order": 0
+    }
+  ]
+}
+```

package/content/guidance/storefront-next/sfnext-hybrid-storefronts/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: sfnext-hybrid-storefronts
+description: Implement hybrid storefronts that run Storefront Next alongside SFRA or SiteGenesis. Use when planning gradual migration from SFRA, configuring hybrid proxy for local development, setting up session bridging between storefronts, or routing traffic between old and new implementations.
+---
+
+# 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

package/content/guidance/storefront-next/sfnext-hybrid-storefronts/references/HYBRID-PROXY-CONFIG.md

@@ -0,0 +1,123 @@
+# Hybrid Proxy Configuration Reference
+
+## Overview
+
+The hybrid proxy is a **Vite dev server plugin** (`hybridProxyPlugin` from `@salesforce/storefront-next-dev`) that routes requests between Storefront Next and SFRA based on URL patterns during local development. In production, Cloudflare eCDN handles routing.
+
+## Environment Variables
+
+### All Environments
+
+```bash
+# Enable hybrid mode (activates client-side legacy-routes middleware)
+PUBLIC__app__hybrid__enabled=true
+
+# Routes owned by SFRA — Link clicks to these force full-page navigation
+# Supports exact paths and React Router parameterized routes (/product/:id)
+PUBLIC__app__hybrid__legacyRoutes='["/cart", "/checkout"]'
+```
+
+### Local Development Only
+
+```bash
+# Enable the Vite proxy
+HYBRID_PROXY_ENABLED=true
+
+# SFCC sandbox URL (the actual hostname, not the SCAPI base URL)
+SFCC_ORIGIN=https://zzrf-001.dx.commercecloud.salesforce.com
+
+# Cloudflare-style routing expression
+# 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 "^/search.*" or http.request.uri.path matches "^/account.*" or http.request.uri.path matches "^/resource.*" or http.request.uri.path matches "^/action/.*")'
+
+# Optional: locale for SFRA path transformation
+HYBRID_PROXY_LOCALE=en-GB
+
+# Commerce Cloud site ID (likely already set)
+PUBLIC__app__defaultSiteId=RefArchGlobal
+```
+
+## Routing Rules Format
+
+Each clause follows `http.request.uri.path matches "<regex>"`, joined with `or`:
+
+```
+(http.request.uri.path matches "^/$" or http.request.uri.path matches "^/category.*")
+```
+
+This is the same format used by Cloudflare eCDN origin rules — keep local and production in sync.
+
+### Required Patterns
+
+| Pattern        | Why                                              |
+| -------------- | ------------------------------------------------ |
+| `^/resource.*` | React Router resource routes (server endpoints)  |
+| `^/action/.*`  | React Router actions (form submissions)          |
+
+### Automatically Excluded Paths (never proxied)
+
+- `/@*`, `/__*` — Vite internals
+- `/src/*`, `/node_modules/*` — Source files
+- `*.data` — React Router data requests
+- `/mobify/*` — SCAPI proxy paths
+- Static asset extensions (`.js`, `.css`, `.png`, `.woff2`, etc.)
+
+SFRA static assets (`/on/demandware.static/*`, `/on/demandware.store/*`) are always proxied.
+
+## Path Transformation
+
+The proxy rewrites paths to SFRA format automatically:
+
+| Browser URL    | Proxied to SFCC as                    |
+| -------------- | ------------------------------------- |
+| `/cart`        | `/s/RefArchGlobal/en-GB/cart`         |
+| `/checkout`    | `/s/RefArchGlobal/en-GB/checkout`     |
+
+The `siteId` comes from `PUBLIC__app__defaultSiteId`. The locale uses `HYBRID_PROXY_LOCALE` → `PUBLIC__app__i18n__fallbackLng` → `default`.
+
+## Cookie Handling (Local Dev)
+
+Three layers keep cookies working on localhost:
+
+1. **Set-Cookie header rewriting** — `Domain=.salesforce.com` → `Domain=localhost`
+2. **Storefront Next server cookies** — Written directly to localhost
+3. **Client-side cookie interception** — Injected script patches `document.cookie` for SFRA JS
+
+## Custom Route Matching
+
+Override the default `shouldRouteToNext` matcher in `vite.config.ts`:
+
+```typescript
+import { hybridProxyPlugin, shouldRouteToNext } from '@salesforce/storefront-next-dev';
+
+hybridProxyPlugin({
+    routeMatcher: (pathname, rules) => {
+        if (pathname === '/my-custom-page') return true;  // → Storefront Next
+        if (pathname === '/legacy-only') return false;    // → SFRA
+        return shouldRouteToNext(pathname, rules);        // default
+    },
+});
+```
+
+## CDN Routing (Production)
+
+In production, Cloudflare eCDN origin rules handle the split:
+
+```
+# Conceptual — configured in Cloudflare dashboard
+/                       → Storefront Next (MRT origin)
+/product/*              → Storefront Next (MRT origin)
+/category/*             → Storefront Next (MRT origin)
+/cart                   → SFRA (B2C Instance origin)
+/checkout/*             → SFRA (B2C Instance origin)
+/on/demandware.static/* → SFRA (B2C Instance origin)
+```
+
+## Shared Cookie Requirements
+
+Both storefronts must share a parent cookie domain:
+
+| Storefront      | Domain              | Cookie Domain   |
+| --------------- | ------------------- | --------------- |
+| Storefront Next | `www.example.com`   | `.example.com`  |
+| SFRA            | `legacy.example.com`| `.example.com`  |