@salesforce/b2c-dx-mcp 2.1.2 → 3.0.0

package/content/guidance/storefront-next/sfnext-data-fetching/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: sfnext-data-fetching
+description: Implement server-side data fetching in Storefront Next using loaders, actions, and useScapiFetcher. Use when writing loader functions, making SCAPI calls, handling form submissions, or implementing interactive data fetching. Covers synchronous loaders, streaming patterns, createApiClients, and parallel requests. NOT for client-side Zustand state — see sfnext-state-management.
+---
+
+# Data Fetching Skill
+
+This skill covers server-side data fetching patterns in Storefront Next — loaders, actions, and the useScapiFetcher hook.
+
+## Overview
+
+Storefront Next mandates **server-only data loading**. All SCAPI requests execute on the MRT server, never in the browser. Three mechanisms exist:
+
+| Mechanism | When It Runs | Use Case |
+|-----------|-------------|----------|
+| `loader` | Route navigation | Initial page data |
+| `action` | Form submission | Mutations (add to cart, update profile) |
+| `useScapiFetcher` | User interaction | On-demand fetching (search suggestions, infinite scroll) |
+
+## Loader Patterns
+
+Loaders can be **synchronous** (returning promises for streaming) or **async** (awaiting critical data). Choose based on what the page needs:
+
+- **Sync loader** — Returns promises directly. Enables streaming SSR: the shell renders immediately while data streams in. Best when all data can render progressively.
+- **Async loader** — Awaits critical data before rendering. Use when data is required for SEO or the page shell (e.g., category name in breadcrumbs). Non-critical data can still be returned as promises for streaming.
+
+```typescript
+// Sync — full streaming (all data renders progressively)
+export function loader({ params, context }: LoaderFunctionArgs): ProductPageData {
+    const clients = createApiClients(context);
+    return {
+        product: clients.shopperProducts.getProduct({
+            params: { path: { id: params.productId } }
+        }).then(({ data }) => data),
+        reviews: clients.shopperProducts.getReviews({
+            params: { path: { id: params.productId } }
+        }).then(({ data }) => data),
+    };
+}
+
+// Async — await critical data, stream the rest (mixed strategy)
+export async function loader({ params, context }: LoaderFunctionArgs): Promise<CategoryPageData> {
+    const clients = createApiClients(context);
+
+    // Await critical data needed for page shell/SEO
+    const category = await clients.shopperProducts.getCategory({
+        params: { path: { id: params.categoryId } }
+    }).then(({ data }) => data);
+
+    return {
+        category,  // Resolved immediately
+        products: clients.shopperSearch.productSearch({
+            params: { query: { q: '', refine: { cgid: params.categoryId } } }
+        }).then(({ data }) => data),  // Streamed
+    };
+}
+```
+
+## When to Use Each Pattern
+
+| Pattern | When | Example |
+|---------|------|---------|
+| Sync (full streaming) | All data can render progressively | Product page with reviews |
+| Async (await critical) | SEO-critical data needed for page shell | Category page (needs category name) |
+| Mixed | Some data critical, some deferrable | Category name (await) + product grid (stream) |
+
+See [Loader Patterns Reference](references/LOADER-PATTERNS.md) for more patterns and data flow diagrams.
+
+## Action Functions
+
+Handle mutations (form submissions, cart updates):
+
+```typescript
+import { data, redirect } from 'react-router';
+
+export async function action({ request, context }: ActionFunctionArgs) {
+    const formData = await request.formData();
+    const productId = formData.get('productId') as string;
+
+    const clients = createApiClients(context);
+
+    try {
+        await clients.shopperBasketsV2.addItemToBasket({
+            params: {
+                path: { basketId },
+                body: { productId, quantity: 1 },
+            },
+        });
+        return data({ success: true });
+    } catch (error) {
+        return data({ success: false, error: error.message }, { status: 400 });
+    }
+}
+```
+
+## useScapiFetcher — Interactive Data Fetching
+
+For on-demand data fetching triggered by user interactions (after page load):
+
+```typescript
+import { useScapiFetcher } from '@/hooks/use-scapi-fetcher';
+
+export function useSearchSuggestions({ q, limit, currency }) {
+    const parameters = useMemo(
+        () => ({ params: { query: { q, limit, currency } } }),
+        [q, limit, currency]
+    );
+
+    const fetcher = useScapiFetcher(
+        'shopperSearch',
+        'getSearchSuggestions',
+        parameters
+    );
+
+    const refetch = useCallback(async () => {
+        await fetcher.load();
+    }, [fetcher]);
+
+    return {
+        data: fetcher.data,
+        isLoading: fetcher.state === 'loading',
+        refetch,
+    };
+}
+```
+
+See [SCAPI Fetcher Reference](references/SCAPI-FETCHER.md) for the complete useScapiFetcher API.
+
+## API Client Usage
+
+Always use `createApiClients(context)` in loaders and actions:
+
+```typescript
+import { createApiClients } from '@/lib/api-clients';
+
+export function loader({ context }: LoaderFunctionArgs) {
+    const clients = createApiClients(context);
+
+    clients.shopperProducts.getProduct({...});
+    clients.shopperCustomers.getCustomer({...});
+    clients.shopperBasketsV2.getBasket({...});
+    clients.shopperSearch.productSearch({...});
+    clients.shopperOrders.getOrder({...});
+}
+```
+
+## Parallel vs Sequential Requests
+
+```typescript
+// GOOD — Parallel requests (all start simultaneously)
+export function loader({ context }: LoaderFunctionArgs) {
+    const clients = createApiClients(context);
+    return {
+        product: clients.shopperProducts.getProduct({...}).then(({ data }) => data),
+        reviews: clients.shopperProducts.getReviews({...}).then(({ data }) => data),
+        recommendations: clients.shopperProducts.getRecommendations({...}).then(({ data }) => data),
+    };
+}
+
+// AVOID — Sequential awaits of independent requests (unnecessarily slow)
+export async function loader({ context }: LoaderFunctionArgs) {
+    const clients = createApiClients(context);
+    const product = await clients.shopperProducts.getProduct({...});  // Waits...
+    const reviews = await clients.shopperProducts.getReviews({...});  // Then waits again
+    return { product, reviews };
+}
+```
+
+## Common Pitfalls
+
+| Pitfall | Problem | Solution |
+|---------|---------|----------|
+| Awaiting all data | Blocks page transition unnecessarily | Only await SEO-critical data; stream the rest |
+| Client loaders | Not permitted in Storefront Next | Use server `loader` or `useScapiFetcher` |
+| Sequential `await` | Slow data loading | Return promises in parallel |
+| Missing `context` in `getConfig()` | Config unavailable | Pass `context` in server loaders: `getConfig(context)` |
+
+## Related Skills
+
+- `storefront-next:sfnext-scapi-management` - Adding/removing SCAPI clients and discovering API shapes
+- `storefront-next:sfnext-custom-apis` - Calling custom API endpoints from loaders/actions
+- `storefront-next:sfnext-routing` - Route file conventions and module exports
+- `storefront-next:sfnext-components` - Rendering loader data with createPage and Suspense
+- `storefront-next:sfnext-state-management` - Client-side Zustand stores (NOT data fetching)
+- `storefront-next:sfnext-authentication` - Auth context in loaders
+
+## Reference Documentation
+
+- [Loader Patterns Reference](references/LOADER-PATTERNS.md) - Data flow diagrams and advanced patterns
+- [SCAPI Fetcher Reference](references/SCAPI-FETCHER.md) - Complete useScapiFetcher API and examples

package/content/guidance/storefront-next/sfnext-data-fetching/references/LOADER-PATTERNS.md

@@ -0,0 +1,102 @@
+# Loader Patterns Reference
+
+## Data Flow
+
+### Initial Page Load (SSR)
+
+```
+Browser request → MRT Server
+                  ↓
+             loader() runs on server
+                  ↓
+             SCAPI requests on MRT
+                  ↓
+             HTML response streamed → Browser
+```
+
+### Subsequent Navigation (SPA)
+
+```
+User clicks link → React Router intercepts
+                   ↓
+              Browser fetches from server
+                   ↓
+              MRT Server runs same loader()
+                   ↓
+              SCAPI requests on MRT
+                   ↓
+              JSON response → Browser
+                   ↓
+              React updates DOM
+```
+
+The loader code is identical for SSR and SPA navigation — only the response format differs (HTML vs JSON).
+
+## Decision Tree: Which Pattern to Use
+
+```
+Need data for page render?
+├── Critical for SEO / above-the-fold?
+│   └── Use awaited data (async loader with await)
+├── Non-critical / below-the-fold?
+│   └── Use deferred data (sync loader, return promises)
+└── Mix of both?
+    └── Use mixed strategy (await critical, stream rest)
+
+Need to handle mutations?
+└── Use action function
+
+Need data after page load (user interaction)?
+└── Use useScapiFetcher
+```
+
+## Pattern: Multiple API Calls with Dependencies
+
+When one API call depends on another's result:
+
+```typescript
+export async function loader({ params, context }: LoaderFunctionArgs) {
+    const clients = createApiClients(context);
+
+    // First call — must resolve before dependent calls
+    const category = await clients.shopperProducts.getCategory({
+        params: { path: { id: params.categoryId } }
+    }).then(({ data }) => data);
+
+    // Dependent calls — can run in parallel with each other
+    return {
+        category,
+        products: clients.shopperSearch.productSearch({
+            params: { query: { refine: `cgid=${category.id}` } }
+        }).then(({ data }) => data),
+        refinements: clients.shopperSearch.getSearchSuggestions({
+            params: { query: { q: category.name } }
+        }).then(({ data }) => data),
+    };
+}
+```
+
+## Pattern: Conditional Data Loading
+
+```typescript
+export function loader({ params, context }: LoaderFunctionArgs) {
+    const clients = createApiClients(context);
+    const auth = getAuth(context);
+
+    const base = {
+        product: clients.shopperProducts.getProduct({
+            params: { path: { id: params.productId } }
+        }).then(({ data }) => data),
+    };
+
+    // Only fetch wishlist for registered users
+    if (auth.userType === 'registered') {
+        return {
+            ...base,
+            wishlist: clients.shopperCustomers.getWishlist({...}).then(({ data }) => data),
+        };
+    }
+
+    return base;
+}
+```

package/content/guidance/storefront-next/sfnext-data-fetching/references/SCAPI-FETCHER.md

@@ -0,0 +1,93 @@
+# SCAPI Fetcher Reference
+
+## How useScapiFetcher Works
+
+```
+Component calls useScapiFetcher()
+        ↓
+Hook builds URL: /resource/api/client/{encoded-params}
+        ↓
+fetcher.load() or fetcher.submit()
+        ↓
+resource.api.client.$resource.ts loader/action runs ON SERVER
+        ↓
+createApiClients(context) makes SCAPI call (server-side)
+        ↓
+JSON response returned to component
+```
+
+Even though `useScapiFetcher` is called from the browser, the actual SCAPI requests happen **on the server** through the resource route, keeping credentials secure.
+
+## API
+
+```typescript
+const fetcher = useScapiFetcher(
+    clientName,    // SCAPI client: 'shopperSearch', 'shopperProducts', etc.
+    methodName,    // Method: 'getSearchSuggestions', 'productSearch', etc.
+    parameters     // SCAPI parameters object
+);
+
+// Properties
+fetcher.data       // Response data (undefined until loaded)
+fetcher.state      // 'idle' | 'loading' | 'submitting'
+fetcher.load()     // Trigger a GET request
+fetcher.submit()   // Trigger a POST request
+```
+
+## loader vs useScapiFetcher
+
+| Scenario | Use |
+|----------|-----|
+| Load product data on page visit | `loader` |
+| Load checkout data | `loader` |
+| Search suggestions as user types | `useScapiFetcher` |
+| Update customer profile in modal | `useScapiFetcher` |
+| Load recommendations after page loads | `useScapiFetcher` |
+| Fetch bonus products when modal opens | `useScapiFetcher` |
+| Infinite scroll / Load more | `useScapiFetcher` |
+
+## Timeline Comparison
+
+```
+loader (Server):
+  [navigate] → [server fetch] → [stream to client]
+  Data available: Streamed during render via Suspense
+
+useScapiFetcher:
+  [render] → [user action] → [fetch] → [re-render]
+  Data available: AFTER user action, component re-renders
+```
+
+## Complete Example: Search Suggestions
+
+```typescript
+import { useScapiFetcher } from '@/hooks/use-scapi-fetcher';
+import { useMemo, useCallback } from 'react';
+
+export function useSearchSuggestions({ q, limit, currency }) {
+    const parameters = useMemo(
+        () => ({
+            params: {
+                query: { q, limit, currency }
+            }
+        }),
+        [q, limit, currency]
+    );
+
+    const fetcher = useScapiFetcher(
+        'shopperSearch',
+        'getSearchSuggestions',
+        parameters
+    );
+
+    const refetch = useCallback(async () => {
+        await fetcher.load();
+    }, [fetcher]);
+
+    return {
+        data: fetcher.data,
+        isLoading: fetcher.state === 'loading',
+        refetch
+    };
+}
+```

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

@@ -0,0 +1,141 @@
+---
+name: sfnext-deployment
+description: Build and deploy Storefront Next storefronts to Managed Runtime (MRT) using the sfnext CLI. Use when running production builds, pushing bundles to MRT with sfnext push, configuring deployment environments, or deploying Page Designer cartridges. This is for Storefront Next deployment — for general MRT management via b2c CLI, see b2c-cli:b2c-mrt.
+---
+
+# Deployment Skill
+
+This skill covers building and deploying Storefront Next storefronts to Managed Runtime (MRT).
+
+## Overview
+
+Storefront Next storefronts are deployed to MRT as bundles. The `sfnext` CLI handles building and pushing bundles, while environment configuration is managed through MRT environment variables.
+
+Reuse the MRT project, environment, and credentials created by Business Manager
+storefront setup. Follow the [deployment guide](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-push-mrt-auto.html)
+for source deployments and the [launch guide](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-mrt-launch-storefront.html)
+for staging/production rollout. Creating new SLAS clients or MRT resources is not
+a prerequisite to each deployment.
+
+## Production Build
+
+```bash
+# Build for production
+pnpm build
+
+# The build output goes to build/ directory
+```
+
+The production build:
+
+- Compiles TypeScript to JavaScript
+- Bundles client and server code separately
+- Optimizes and minifies assets
+- Generates the static Page Designer registry
+
+## Deploying to MRT
+
+### Using the Template's Push Script
+
+Use the project's `push` script (`sfnext push --project-directory .`). Build first;
+the push command requires existing build output. With the template's pnpm setup:
+
+```bash
+# Push the current build to MRT
+pnpm run push
+
+# Push with a specific message
+pnpm run push --message "Release v1.2.0"
+
+# Push to a specific environment
+pnpm run push --environment staging --wait
+```
+
+### Deployment Flow
+
+```
+pnpm run build → pnpm run push → MRT receives bundle → Deployed to environment
+```
+
+See [MRT Deployment Reference](references/MRT-DEPLOYMENT.md) for detailed deployment options.
+
+## Environment Configuration
+
+Environment variables for MRT are configured through:
+
+1. **Runtime Admin or `b2c mrt env var set/push`** — Set application variables per environment; `PUBLIC__` values merge into runtime configuration and are browser-visible. Changes redeploy the environment.
+2. **CLI flags or `MRT_*` environment variables** — Control push/deploy targets
+3. **`.env` files** — Local development only (not deployed)
+
+Use `b2c mrt env var push --file .env.staging --project <project> --environment <environment>`
+to explicitly apply a reviewed file. It shows a diff and prompts; omit local-only
+values and use credentials for the target instance. See [Environment Variables](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-mrt-environment-vars.html)
+for visibility, naming, and limits. MRT variable management uses the B2C CLI. For live logs, prefer MCP
+`mrt_logs_watch` / `mrt_logs_watch_poll`; CLI alternative: `b2c mrt tail-logs`.
+
+### MRT Deployment Variables
+
+```bash
+# Project slug (required for push)
+MRT_PROJECT=my-project-slug
+
+# Target environment (optional — if omitted, bundle is uploaded but not deployed)
+MRT_TARGET=development
+```
+
+### Application Variables (set in MRT Dashboard)
+
+```bash
+PUBLIC__app__commerce__api__clientId=prod-client-id
+PUBLIC__app__commerce__api__organizationId=prod-org-id
+PUBLIC__app__commerce__api__shortCode=prod-short-code
+```
+
+## Page Designer Cartridge Deployment
+
+Page Designer metadata must be deployed separately to Commerce Cloud (not MRT):
+
+```bash
+# Generate cartridge metadata
+pnpm generate:cartridge
+
+# Deploy cartridge to B2C instance
+pnpm deploy:cartridge
+
+# Deploy with clean (removes old cartridge first)
+pnpm deploy:cartridge:clean
+
+# Validate cartridge structure
+pnpm validate:cartridge
+```
+
+Cartridge metadata is also auto-generated as part of `pnpm build`.
+
+## Pre-Deployment Checklist
+
+1. **Run tests** — `pnpm test`
+2. **Check bundle size** — `pnpm bundlesize:test`
+3. **Verify environment variables** — All required vars set in target environment
+4. **Build successfully** — `pnpm build` completes without errors
+5. **Verify SCAPI credentials** — Client ID and org ID match the target environment
+
+## Troubleshooting
+
+| Issue                          | Cause                         | Solution                                    |
+| ------------------------------ | ----------------------------- | ------------------------------------------- |
+| Build fails                    | TypeScript errors             | Fix type errors; run `pnpm typecheck`       |
+| Push rejected                  | Authentication issue          | Verify sfnext CLI credentials               |
+| 500 errors after deploy        | Missing environment variables | Check all required vars in MRT dashboard    |
+| Stale Page Designer components | Cartridge not deployed        | Re-deploy cartridge via MCP tool or b2c CLI |
+
+## Related Skills
+
+- `storefront-next:sfnext-project-setup` - Project structure and build configuration
+- `storefront-next:sfnext-configuration` - Environment variable configuration
+- `storefront-next:sfnext-page-designer` - Page Designer cartridge deployment
+- `storefront-next:sfnext-performance` - Bundle size optimization before deployment
+- `b2c-cli:b2c-mrt` - General MRT management via b2c CLI (NOT Storefront Next specific)
+
+## Reference Documentation
+
+- [MRT Deployment Reference](references/MRT-DEPLOYMENT.md) - Detailed deployment options and configuration

package/content/guidance/storefront-next/sfnext-deployment/references/MRT-DEPLOYMENT.md

@@ -0,0 +1,90 @@
+# MRT Deployment Reference
+
+## Managed Runtime (MRT)
+
+MRT is the hosting platform for Storefront Next storefronts. It provides:
+
+- **Server-side rendering** — Node.js runtime for SSR and loader execution
+- **CDN** — Global content delivery for static assets
+- **Environment management** — Separate environments for development, staging, production
+- **Bundle management** — Versioned deployments with rollback capability
+
+## Deployment Commands
+
+```bash
+# Build, then run the template's push script
+pnpm run build && pnpm run push
+
+# Push with deployment message
+pnpm run push --message "Fix checkout flow"
+
+# Push to specific environment
+pnpm run push --environment production --wait
+
+# Create a bundle without deploying (inspection/custom pipelines)
+pnpm sfnext create-bundle -d . -o .bundle
+```
+
+## Environment Variables on MRT
+
+### Setting Variables
+
+Environment variables are set per-environment through:
+
+1. **Runtime Admin or `b2c mrt env var set/push`** — Application variables on the selected environment; changes redeploy it.
+2. **`MRT_PROJECT`, `MRT_TARGET`, `MRT_API_KEY`** — Deployment target and credentials for `pnpm sfnext push`; these do not upload application variables from `.env`.
+
+### Variable Limits
+
+See Salesforce's [Environment Variables constraints](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-mrt-environment-vars.html#constraints)
+for current limits. The 32 KB value-size limit covers all environment variables,
+not only `PUBLIC__` values. Public configuration paths must exist in `config.server.ts`.
+
+### Production Configuration Example
+
+```bash
+# Commerce API credentials
+PUBLIC__app__commerce__api__clientId=prod-client-id
+PUBLIC__app__commerce__api__organizationId=f_ecom_abcd_001
+PUBLIC__app__commerce__api__siteId=RefArchGlobal
+PUBLIC__app__commerce__api__shortCode=kv7kzm78
+
+# Site configuration
+PUBLIC__app__defaultSiteId=RefArchGlobal
+PUBLIC__app__commerce__sites='[{"id":"RefArchGlobal","defaultLocale":"en-US","defaultCurrency":"USD","supportedLocales":[{"id":"en-US","preferredCurrency":"USD"},{"id":"de-DE","preferredCurrency":"EUR"}],"supportedCurrencies":["USD","EUR"]}]'
+
+# Server-only secrets (not exposed to client)
+COMMERCE_API_SLAS_SECRET=production-slas-secret
+```
+
+## Bundle Management
+
+Each `sfnext push` creates a versioned bundle on MRT:
+
+```
+Bundle v1 (active) ← current production
+Bundle v2          ← previous deployment
+Bundle v3          ← two deployments ago
+```
+
+### Rollback
+
+If a deployment causes issues, roll back to a previous bundle via the MRT Dashboard or CLI.
+
+## Multi-Environment Setup
+
+| Environment | Purpose                   | Auto-deploy           |
+| ----------- | ------------------------- | --------------------- |
+| Development | Feature testing           | From feature branches |
+| Staging     | Pre-production validation | From main branch      |
+| Production  | Live storefront           | Manual promotion      |
+
+## Deployment Verification
+
+After deploying, verify:
+
+1. **Health check** — Site loads without errors
+2. **SCAPI connectivity** — Products and categories display correctly
+3. **Authentication** — Login/logout flow works
+4. **Page Designer** — Merchant-editable pages render correctly
+5. **Performance** — No regression in page load times