@salesforce/b2c-cli 2.3.1 → 2.5.0

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

@@ -0,0 +1,163 @@
+---
+name: sfnext-configuration
+description: >-
+  Configure a Storefront Next app: config.server.ts (defineConfig, metadata/runtime/app), AppConfig types in
+  src/types/config.ts, PUBLIC__ environment variable overrides, getConfig(context) / useConfig(), extension config
+  (app.extension, app.serverExtension), protected paths, server-only secrets, and multi-site settings
+  (commerce.sites, url.prefix, seoRoutes, siteAliasMap, cookie domain). Use when editing config.server.ts, adding a
+  config value, an env var is ignored or "not applied", `pnpm config:inspect` / `config:push-env`, "Ignoring
+  environment variable" warnings, protected config path errors, setting up a second site or locale URLs, or
+  going through the pre-launch config checklist.
+  Do not use for creating a project or the npm script list (use `storefront-next:sfnext-project-setup`), pushing
+  bundles or MRT env management (use `storefront-next:sfnext-deployment` / `b2c-cli:b2c-mrt`), or hybrid
+  proxy and cookie-sharing with SFRA (use `storefront-next:sfnext-hybrid-storefronts`).
+---
+
+# Storefront Next Configuration
+
+All app settings live in one typed file, `config.server.ts`. Environment variables override its values per environment; `defineConfig()` deep-merges them at startup. Full references ship in the project: `docs/README-CONFIG.md` (required/optional variable tables) and `docs/README-CONFIG-OPTIONS.md` (every option).
+
+## Model
+
+`config.server.ts` default-exports `defineConfig<Config>({ metadata, runtime, app }, { protectedPaths })`, imported from `@salesforce/storefront-next-runtime/config`.
+
+| Section | Visible to | Contents |
+| --- | --- | --- |
+| `app` | Server and browser (`window.__APP_CONFIG__`) | Commerce API, sites, features, URL/SEO routes, images, security, engagement |
+| `runtime` | Server only | MRT settings such as `ssrParameters` (`ssrFunctionNodeVersion`, `envBasePath`), `ssrOnly`, `ssrShared` |
+| `metadata` | Server only | Project name/slug |
+
+Because `app` reaches the browser, never put secrets in it.
+
+## Add a config value
+
+1. Add the field to `AppConfig` in `src/types/config.ts` (`Config = BaseConfig<AppConfig>`; the `AppConfigShape` / `ClientFacingAppConfigShape` augmentations in that file give `getConfig` and `useConfig` their types).
+2. Set a default under `app` in `config.server.ts`. **Define the key even if the default is empty (`''`, `[]`)**; env overrides are only accepted for paths that exist here.
+3. Override per environment: `PUBLIC__app__myFeature__enabled=true`.
+4. Run `pnpm typecheck`.
+
+```typescript
+// src/types/config.ts (inside AppConfig)
+myFeature: { enabled: boolean; maxItems: number };
+
+// config.server.ts (inside app)
+myFeature: { enabled: false, maxItems: 10 },
+```
+
+## Read config
+
+```typescript
+import { getConfig, useConfig } from '@salesforce/storefront-next-runtime/config';
+
+// Loaders, actions, middleware (server): context is REQUIRED
+export function loader({ context }: LoaderFunctionArgs) {
+  const config = getConfig(context);      // full AppConfig incl. serverExtension
+  return { max: config.myFeature.maxItems };
+}
+
+// Components
+const config = useConfig();               // client-facing shape (no serverExtension)
+```
+
+- `getConfig()` with no argument is for browser-only modules (reads `window.__APP_CONFIG__`); it returns the client-facing shape. Calling it on the server without a context **throws** "Configuration not available".
+- Routes have no `clientLoader` (forbidden by the project rules), so server code always passes `context`.
+- Middleware can read `context.get(appConfigContext)` (exported from the same module).
+- In tests use `mockConfig`, `mockBuildConfig`, `ConfigWrapper`, `createConfigWrapper` from `@/test-utils/config`.
+
+## Environment variable rules
+
+```
+PUBLIC__app__<path>__<to>__<key>=value   ->   config.app.<path>.<to>.<key>
+```
+
+| Rule | Detail |
+| --- | --- |
+| `PUBLIC__` prefix | Merged into config and **exposed to the browser**. Client IDs, flags, site lists only |
+| No prefix | Server-only; not part of config. Read with `process.env` in server code |
+| Path must exist | An unknown path is skipped with `[Config Warning] Ignoring environment variable ...` in the server log, so a typo is silent to the user |
+| Parsing | Numbers, `true`/`false` (as strings), JSON arrays/objects; empty value becomes `''` |
+| Precedence | Deeper (more specific) paths win over a JSON blob at a parent path |
+| Case | Path matching is case-insensitive |
+| Depth | Max 10 segments; use a JSON value for deeper structures |
+| Restart | `.env` is read at startup; restart `pnpm dev` |
+
+### Required variables
+
+Only three are required to boot (`.env` locally; MRT environment variables when deployed):
+
+```bash
+PUBLIC__app__commerce__api__clientId=...
+PUBLIC__app__commerce__api__organizationId=...
+PUBLIC__app__commerce__api__shortCode=...
+```
+
+Do not set `PUBLIC__app__commerce__api__siteId`; that path does not exist and is ignored with a warning. To point at your own site, set `PUBLIC__app__defaultSiteId` and `PUBLIC__app__commerce__sites` (see [MULTI-SITE-URLS.md](references/MULTI-SITE-URLS.md)). Everything else is optional; see [ENV-VARIABLES.md](references/ENV-VARIABLES.md).
+
+### Debug "my env var is not applied"
+
+```bash
+pnpm config:inspect                 # shows each value and whether it comes from config.server.ts, .env, or MRT
+pnpm sfnext config inspect --project my-project --environment staging   # include MRT env values
+pnpm config:push-env                # push .env variables to an MRT environment (b2c mrt env var push)
+```
+
+The `config:inspect` script echoes a tip after the command, so call `sfnext config inspect` directly when passing flags.
+
+Checklist: `PUBLIC__` with a double underscore, path exists in `config.server.ts`, booleans are the string `true`, dev server restarted, variable set on the right MRT environment, and the path is not protected.
+
+## Protected paths
+
+`defineConfig(..., { protectedPaths })` locks paths against env override. Setting a protected path, or a parent of one (e.g. `PUBLIC__app__url`), **throws at startup**. The template protects:
+
+- `app__url__prefix`, `app__url__excludeRoutes`, `app__url__seoRoutes` (compiled into routes at build time; change `config.server.ts` and rebuild/redeploy)
+- `app__engagement__adapters__einstein`, `...__data360`, `...__activeData__enabled`, `...__activeData__eventToggles`
+
+The rest of `app.engagement` is overridable. Check the `protectedConfigPaths` export in your `config.server.ts` for the current list.
+
+## Secrets
+
+Server-only values are plain env vars read via `process.env` in server routes/middleware, never through config:
+
+- `COMMERCE_API_SLAS_SECRET`: only for a private SLAS client (`commerce.api.privateKeyEnabled`). A public client needs no secret.
+- `GUEST_ORDER_LOOKUP_COOKIE_SECRET`: required when guest order lookup is enabled.
+- `MARKETING_CLOUD_*`: only for email-mode passwordless/reset with your own Marketing Cloud tenant.
+
+Extension `config.ts` / `server-config.ts` must not read `process.env` (an AST check fails discovery).
+
+## Extension config
+
+Extensions add config without touching core files:
+
+- `src/extensions/<name>/config.ts` (default-export an object) is merged into `app.extension.<camelCaseFolder>`; override with `PUBLIC__app__extension__<key>__<setting>`.
+- `src/extensions/<name>/server-config.ts` is merged into `app.serverExtension.<camelCaseFolder>`, available only through `getConfig(context)`; no env override, and the build fails if a client chunk imports it.
+- `pnpm config:aggregate-extensions` regenerates the merged files (run automatically by `dev`, `build`, `typecheck`).
+
+## Multi-site and URLs
+
+Short version: the current site comes from the request (site-context middleware), not from `commerce.sites[0]`. Use `useSite()` from `@salesforce/storefront-next-runtime/site-context` in components and `context.get(siteContext)` (same module) on the server. URL shape, `seoRoutes`, aliases, MRT Data Store sites, cookie domain, multiple domains, and base path are in [MULTI-SITE-URLS.md](references/MULTI-SITE-URLS.md).
+
+## Pre-launch config gate
+
+Before going live, review these defaults in `config.server.ts`:
+
+1. `app.engagement.adapters` (Einstein, Active Data, Data 360): defaults carry **demo IDs/hosts**. Enable only with your own values, or disable them; also confirm consent categories.
+2. `images.host` defaults to the DIS **staging** host (`edge.disstg...`); use the production DIS host, and add `realmHostMappings` for custom domains.
+3. `.env` / MRT variables point at your own client ID, organization ID, short code, and site(s), not the demo backend.
+4. `commerce.sites`, `defaultSiteId`, and `siteAliasMap` match your Business Manager sites; `url.seoRoutes` has an entry for every active site if enabled.
+5. Cookie domain (`cookies.domain`) matches Business Manager Hybrid Auth level if used.
+6. Security headers / CSP (`app.security.headers`) and Turnstile keys are reviewed (`storefront-next:sfnext-security`).
+
+## Related Skills
+
+- `storefront-next:sfnext-project-setup` - Create the project, `.env` basics, scripts
+- `storefront-next:sfnext-deployment` - Push bundles and sync MRT env vars
+- `storefront-next:sfnext-routing` - Site-aware links and SEO route behavior
+- `storefront-next:sfnext-i18n` - Locales, translations, locale switching
+- `storefront-next:sfnext-extensions` - Extension authoring
+- `storefront-next:sfnext-hybrid-storefronts` - Hybrid proxy and shared cookies with SFRA
+- `storefront-next:sfnext-security` - Security headers, CSP, Turnstile
+- `b2c-cli:b2c-mrt` - MRT environment variable management
+
+## Finding more
+
+Project `docs/README-CONFIG.md`, `docs/README-CONFIG-OPTIONS.md`, `docs/README-MULTI-SITE.md`; `b2c docs search "<topic>" --category sfnext`.

package/content/guidance/storefront-next/sfnext-configuration/references/ENV-VARIABLES.md

@@ -0,0 +1,55 @@
+# Environment Variables
+
+Authoritative, current tables ship in the project: `docs/README-CONFIG.md` ("Required vs Optional Variables") and `docs/README-CONFIG-OPTIONS.md`. This file summarizes the categories; check those docs for defaults.
+
+## Where variables come from
+
+| Source | Used by |
+| --- | --- |
+| `.env` in the project root | `pnpm dev`, `pnpm start`, and `sfnext` commands (`push`, `config inspect`, ...). `.env.default` is a template only and is never loaded |
+| Managed Runtime environment variables | The deployed storefront. Set in Runtime Admin or with `b2c mrt env var set` / `b2c mrt env var push` (`pnpm config:push-env`) |
+
+`.env` is not uploaded by `pnpm push`. See `storefront-next:sfnext-deployment`.
+
+## Required to run
+
+`PUBLIC__app__commerce__api__clientId`, `PUBLIC__app__commerce__api__organizationId`, `PUBLIC__app__commerce__api__shortCode`.
+
+## Required to push to Managed Runtime
+
+| Variable | Notes |
+| --- | --- |
+| `MRT_PROJECT` | MRT project slug (also `--project`, `SFCC_MRT_PROJECT`, or dw.json `mrtProject`). Set it explicitly |
+| `MRT_TARGET` | Target environment (also `--environment`). Optional unless using `--wait` |
+| `MRT_API_KEY` | API key (or `MRT_CREDENTIALS_FILE` / `~/.mobify`). Also `MRT_CLOUD_ORIGIN` for a non-default MRT origin |
+
+These are read by the `sfnext` CLI; they are not storefront runtime config.
+
+## Common optional `PUBLIC__` overrides
+
+| Variable | Effect |
+| --- | --- |
+| `PUBLIC__app__defaultSiteId` | Default site ID |
+| `PUBLIC__app__commerce__sites` | JSON array of site definitions |
+| `PUBLIC__app__commerce__sitesFromDal` | `false` keeps static `commerce.sites` authoritative instead of MRT Data Store sites |
+| `PUBLIC__app__cookies__domain` | Cookie domain for all storefront cookies |
+| `PUBLIC__app__commerce__api__privateKeyEnabled` | Use a private SLAS client (needs `COMMERCE_API_SLAS_SECRET`) |
+| `PUBLIC__app__commerce__api__proxy`, `...__callback` | SCAPI proxy and OAuth callback paths |
+| `PUBLIC__app__hybrid__enabled` | Hybrid mode |
+| `PUBLIC__app__features__*` | Feature toggles (passwordless login, social login, shopper context, MRT-based Page Designer resolution, ...) |
+| `PUBLIC__app__security__turnstile__*` | Turnstile bot protection |
+| `PUBLIC__app__commerce__shopperAgent` | Shopper Agent widget config (the older `PUBLIC__app__cimulateAgent` is deprecated) |
+| `PUBLIC__app__extension__<key>__<setting>` | Extension config overrides |
+
+## Server-only (no prefix)
+
+`COMMERCE_API_SLAS_SECRET` (private client only), `GUEST_ORDER_LOOKUP_COOKIE_SECRET`, `MARKETING_CLOUD_CLIENT_ID` / `_CLIENT_SECRET` / `_AUTH_BASE_URL` / `_REST_BASE_URL`, `SFCC_LOG_LEVEL` (`error|warn|info|debug`), and local-dev hybrid proxy variables (`HYBRID_PROXY_ENABLED`, `HYBRID_ROUTING_RULES`, `HYBRID_PROXY_LOCALE`, `SFCC_ORIGIN`; see `storefront-next:sfnext-hybrid-storefronts`).
+
+## Gotchas
+
+- Unknown `PUBLIC__` paths are ignored with a server-log warning; define the key in `config.server.ts` first (an empty default is enough).
+- Protected paths (`app__url__*`, selected engagement adapter paths) throw if set via env; see SKILL.md.
+- Booleans must be the string `true`/`false`. Objects and arrays are JSON strings.
+- Multi-line JSON is supported in `.env`; on MRT, keep values compact.
+- MRT limits total variable size and name length; see Salesforce's [Environment Variables constraints](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-mrt-environment-vars.html) for the current numbers rather than relying on a figure here.
+- Vite also loads `.env.<mode>` files by build mode.

package/content/guidance/storefront-next/sfnext-configuration/references/MULTI-SITE-URLS.md

@@ -0,0 +1,137 @@
+# Multi-Site, URLs, Domains, Base Path, and Cookie Domain
+
+Everything that decides which site/locale a request is for and what URLs look like. Depth ships in the project: `docs/README-MULTI-SITE.md` (URL config, SEO routes, switchers), `docs/README-MULTI-DOMAIN.md`, `docs/README-BASE-PATH.md`, `docs/README-COOKIE-DOMAIN.md`, and `docs/migrations/seo-url-rules/README.md`. Read the relevant one before changing these settings.
+
+## Quick decision table
+
+| Goal | Setting | Rebuild needed? |
+| --- | --- | --- |
+| Add a site or locale | `commerce.sites` (or MRT Data Store sites), i18n locale files | No (env) |
+| Change what the site/locale segments look like | `app.siteAliasMap`, `app.localeAliasMap` | No |
+| Change URL shape (`/:siteId/:localeId`) | `app.url.prefix` / `search` / `excludeRoutes` | **Yes**, protected |
+| Custom product/category URL prefixes | `app.url.seoRoutes` | **Yes**, protected |
+| Many domains, one environment | CDN + `X-Forwarded-Host` (automatic), `images.realmHostMappings` | No |
+| One domain, many environments | `runtime.ssrParameters.envBasePath` | Yes, pushed with `pnpm push` |
+| Share cookies across subdomains | `app.cookies.domain` / per-site override + Business Manager | No |
+
+## Sites and locales
+
+Sites are defined in `config.server.ts` under `app.commerce.sites` and selected with `app.defaultSiteId`. Override from the environment:
+
+```bash
+PUBLIC__app__defaultSiteId=MySite
+PUBLIC__app__commerce__sites='[{"id":"MySite","defaultLocale":"en-US","defaultCurrency":"USD","supportedLocales":[{"id":"en-US","preferredCurrency":"USD"},{"id":"de-DE","preferredCurrency":"EUR"}],"supportedCurrencies":["USD","EUR"]}]'
+```
+
+- Each `supportedLocales` entry needs matching translation files under `src/locales/<locale>/` and to be listed in `app.i18n.supportedLngs`, otherwise the locale selector hides it. The currency switcher only shows when the site has more than one supported currency (`storefront-next:sfnext-i18n`).
+- `commerce.sitesFromDal` is **on by default**: live site data from the MRT Data Store replaces the static `commerce.sites` for site/locale/currency resolution. If the Data Store is unavailable, or the default site is missing from it, the static list is used. Opt out with `PUBLIC__app__commerce__sitesFromDal=false`. URL aliases always come from `siteAliasMap` / `localeAliasMap`, never from the Data Store.
+- There is no `siteId` under `commerce.api`; the site is a per-request parameter that `createApiClients(context)` adds to every SCAPI call.
+
+### Reading the current site
+
+The site is resolved per request by the site-context middleware from the URL, cookie, or header.
+
+```typescript
+// Component
+import { useSite } from '@salesforce/storefront-next-runtime/site-context';
+const { site, language, currency } = useSite();   // throws outside SiteProvider (mounted in root.tsx)
+
+// Loader / action / middleware
+import { siteContext } from '@salesforce/storefront-next-runtime/site-context';
+const siteId = context.get(siteContext)?.site?.id;
+```
+
+Never use `config.commerce.sites[0]` as "the current site".
+
+## URL shape (`app.url`)
+
+Default in the template:
+
+```typescript
+url: {
+  prefix: '/:siteId/:localeId',
+  excludeRoutes: ['/resource/**', '/action/**'],
+},
+```
+
+Pages then live at `/global/en-GB/product/...`; bare `/` is redirected to the default site/locale by the home route loader. `prefix` and `search` accept `:siteId` and `:localeId`; alternatives (locale only, site in path with `?lng=`, everything in query params) are in README-MULTI-SITE "URL Config Use Cases".
+
+Rules:
+
+- `url.prefix`, `url.excludeRoutes`, `url.seoRoutes` are **protected**: compiled into routes at build time. Edit `config.server.ts`, rebuild, redeploy. Setting `PUBLIC__app__url__...` throws.
+- If you change the prefix order or drop site/locale from the path, update `app.siteDetectionConfig` / `app.localeDetectionConfig` (`order`, `lookupFromPathIndex`, `lookupQuerystring`, `lookupHeader`) so detection reads back what `buildUrl` writes. Locale query param key must stay `lng`; the default site query key is `site`.
+- Detection defaults: site order `path, querystring, cookie, header` (header `X-Site-Id`, cookie `site_id`); locale order `path, querystring, cookie, header` (cookie `lng`).
+
+### Aliases
+
+```typescript
+siteAliasMap: { RefArchGlobal: 'global', RefArch: 'us' },   // app.siteAliasMap
+localeAliasMap: { 'en-US': 'us' },                           // app.localeAliasMap
+```
+
+Optional. Without them raw IDs appear in URLs. Changing an alias changes public URLs; plan redirects.
+
+### Building URLs correctly
+
+| Where | Use |
+| --- | --- |
+| JSX links | `Link` / `NavLink` from `@/components/link` |
+| Imperative navigation | `useNavigate` from `@/hooks/use-navigate` |
+| Loader/action redirects | `redirect(buildUrlFromContext('/login', context))` from `@/lib/url.server` |
+| `<Form action>` | Prefix manually with `buildUrl` from `@salesforce/storefront-next-runtime/site-context` + `useCurrentSiteAndLocaleRef` (`@/hooks/use-current-site-and-locale-ref`); React Router `<Form>` does not prefix |
+| Typed route patterns | `routeHref` from `@/route-paths` |
+
+Importing `Link`/`useNavigate` from `react-router` produces unprefixed URLs that 404.
+
+### SEO routes (`url.seoRoutes`)
+
+Replicate Business Manager product/category URL prefixes into the route table, keyed by Commerce site ID:
+
+```typescript
+url: {
+  prefix: '/:siteId/:localeId',
+  excludeRoutes: ['/resource/**', '/action/**'],
+  seoRoutes: {
+    RefArchGlobal: { product: { prefix: 'p' }, category: { prefix: 'c', mode: 'id-suffix' } },
+    RefArch:       { product: { prefix: 'product' }, category: { prefix: 'category', mode: 'id-suffix' } },
+  },
+},
+```
+
+- Every active site needs an entry, or the build fails for the omitted ones.
+- Category `mode`: `id-suffix` (deterministic, ID in last segment) or `slug-path` (needs Shopper Products 1.13 and Shopper Search 1.15 on the instance).
+- Prefixes are single static segments; invalid, reserved, duplicate, or colliding prefixes fail the build. The canonical product/category route modules must be leaf routes.
+- Build links with `createProductUrl` / `createCategoryUrl*` and `useSeoUrlContext()` rather than hand-built paths. Mapping from Business Manager is manual and one-directional.
+- Legacy or unmatched URLs can resolve via the Shopper SEO URL mapping fallback (`app.seoFallback.sites`). Read `docs/migrations/seo-url-rules/README.md` before enabling (redirect loops, indexed URLs).
+
+## Multiple domains, one environment
+
+One MRT environment can serve many domains. The public origin is taken per request from `X-Forwarded-Host` / `X-Forwarded-Proto`, so links, SLAS `redirect_uri`, magic-link emails, canonical/hreflang tags, and JSON-LD use the domain the shopper used. Nothing to configure in the storefront except:
+
+- Attach each domain as an external hostname on the MRT environment and add each domain's callback URLs to the SLAS client's redirect list.
+- `EXTERNAL_DOMAIN_NAME` is only a fallback when no forwarded host exists (startup, local dev); leave the default.
+- `images.realmHostMappings` (`[{ hostSuffix, realm }]`) so DIS resolves the realm on custom domains.
+- To map each domain to a different site, have the CDN set `X-Site-Id` per domain and configure `url.prefix: '/:localeId'`, `siteDetectionConfig: { order: ['header','cookie'], lookupHeader: 'X-Site-Id' }`, `localeDetectionConfig: { lookupFromPathIndex: 0 }`. If the edge cannot inject headers, keep the site in the URL path.
+- Keep cookies host-only across unrelated brand domains.
+
+## Base path (one domain, many environments)
+
+`runtime.ssrParameters.envBasePath: '/storefront-a'` in `config.server.ts` serves one environment under a path segment (single segment, `/` + up to 63 URL-safe chars). The value is sent to MRT during `pnpm push`; the CDN routes by that first segment and MRT does not strip it. Routes, bundle asset URLs, and React Router `basename` adapt automatically, and site/locale path detection skips the base path.
+
+Caveats: raw `fetch()` / `sendBeacon()` from client code must prepend `getBasePath()` from `@/lib/utils`; `redirect()` in middleware is not auto-prefixed; `request.url` still includes the base path; fixed Express routes (e.g. health check) are served without it. Locally `pnpm dev` / `pnpm start` read it from `config.server.ts` and redirect unprefixed requests.
+
+## Cookie domain
+
+Cookies are host-only by default. To share a session across subdomains (or with SFRA in a hybrid setup):
+
+```bash
+PUBLIC__app__cookies__domain=.example.com     # global default
+```
+
+Per-site override: `commerce.sites[].cookies.domain` (wins over the global value). The domain applies to every cookie the storefront writes (auth/session and site-context). It must be a parent of the serving host or browsers silently drop the cookies. Do **not** set `app.siteContext.cookieOptions.domain` (ignored).
+
+Business Manager must agree: **Merchant Tools > Site Preferences > Hybrid Auth Settings** cookie-domain level `0` (host only) when unset, `2` (first-level parent domain) when set. Level `1` is rejected. A mismatch breaks cross-subdomain sessions or creates duplicate cookies. Verify with `curl -sI https://www.example.com/ | grep -i set-cookie` (same `Domain=` on every cookie, no duplicates). See `storefront-next:sfnext-hybrid-storefronts` for the hybrid side.
+
+## Switchers
+
+Site, locale, and currency switchers post to `/action/set-site-context` (which sets `site_id`, `lng`, and the currency cookie and redirects). Currency resolution order: cookie, then the locale's `preferredCurrency`, then the site's `defaultCurrency`.

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

@@ -0,0 +1,140 @@
+---
+name: sfnext-data-fetching
+description: >-
+  Load and mutate data in a Storefront Next project: route loaders that call SCAPI through createApiClients from @/lib/api-clients.server, critical versus streamed (deferred) data, createBasketAction and BasketAction for cart actions, createActionError and ErrorCode, data() responses, useFetcher and the useScapiFetcher hook with its server allowlist, request-scoped dedupe and MRT timeouts, non-personalized SCAPI responses, shopper context, and custom API clients. Use for "fetch products in a loader", "stream data", "add a cart action", "call SCAPI from a component", "resource route", "NormalizedApiError", or "loader blocks the page". Do not use for route files or links (use `storefront-next:sfnext-routing`), when loaders re-run after actions (use `storefront-next:sfnext-revalidation`), Suspense/LCP tuning (use `storefront-next:sfnext-performance`), or defining SCAPI custom APIs (use `storefront-next:sfnext-scapi`).
+---
+
+# Storefront Next Data Fetching
+
+All data comes from the server. Loaders and actions run on the server with the shopper's session; the browser never calls SCAPI directly. Your project ships `docs/README-DATA.md`, `docs/README-SUSPENSE.md`, `docs/README-SCAPI-NON-PERSONALIZED-RESPONSES.md` and `docs/README-SHOPPER-CONTEXT.md`, plus the "Performance & Data Rules" in `AGENTS.md`; this skill is the quick path, those are authoritative.
+
+## The rules (same as AGENTS.md)
+
+1. Fetch on the server in `loader` (reads) and `action` (writes). There is no `clientLoader` or `clientAction`.
+2. Classify every piece of data:
+   - **Critical** (needed for SEO, LCP, layout stability or the HTTP status): `await` it in the loader.
+   - **Non-critical** (below the fold, recommendations, reviews, secondary panels): start the request, do not await it, and return the unresolved promise so it streams.
+   - **Interaction-driven** (only after a click, hover or input): fetch on demand with a fetcher.
+3. Never block a loader on non-critical data.
+4. Pass the promise through `loaderData` and read it under its own `<Suspense>` with `use()` or `<Await>`. Keep the promise identity stable (compose it in the loader, never `Promise.all` or `.then` in render).
+5. Export `shouldRevalidate` on routes whose loaders depend on URL filters (see `storefront-next:sfnext-revalidation`).
+
+## Loader with critical and streamed data
+
+```tsx
+import { Suspense } from 'react';
+import { Await } from 'react-router';
+import type { Route } from './+types/_app.example';
+import { createApiClients } from '@/lib/api-clients.server';
+import { fetchProductById } from '@/lib/api/products.server';
+import { NormalizedApiError } from '@/lib/api/normalized-api-error';
+
+export async function loader({ context, params }: Route.LoaderArgs) {
+    const clients = createApiClients(context);
+
+    // Non-critical: start now, do not await.
+    const related = clients.shopperSearch
+        .productSearch({ params: { query: { q: 'shirt', limit: 8 } } })
+        .then(({ data }) => data.hits ?? []);
+
+    // Critical: needed for status, SEO and LCP.
+    try {
+        const product = await fetchProductById(context, params.id ?? '', { expand: ['images', 'prices'] });
+        if (!product) throw new Response('Not found', { status: 404 });
+        return { product, related };
+    } catch (e) {
+        if (e instanceof NormalizedApiError && e.status) throw new Response(e.message, { status: e.status });
+        throw e;
+    }
+}
+
+export default function Example({ loaderData }: Route.ComponentProps) {
+    return (
+        <>
+            <h1>{loaderData.product.name}</h1>
+            <Suspense fallback={<div className="h-40" aria-busy="true" />}>
+                <Await resolve={loaderData.related}>{(hits) => <ul>{hits.map((h) => <li key={h.productId}>{h.productName}</li>)}</ul>}</Await>
+            </Suspense>
+        </>
+    );
+}
+```
+
+Real precedent: `src/routes/_app.p.$.tsx` awaits the product (404 becomes `throw new Response(..., { status: 404 })`) and streams the Page Designer page, schema and extras; `src/components/product-grid/deferred.tsx` is the streamed-grid pattern.
+
+## SCAPI clients
+
+`createApiClients(context)` from `@/lib/api-clients.server` returns `AppClients`: every generated Shopper API client (`shopperProducts`, `shopperSearch`, `shopperBasketsV2`, `shopperCustomers`, `shopperOrders`, `shopperLogin`, and more) plus generated clients for your custom APIs (`@/scapi/custom-clients`). Call shape:
+
+```ts
+const { data } = await clients.shopperBasketsV2.addItemToBasket({
+    params: { path: { basketId }, query: {} },
+    body: [{ productId, quantity: 1 }],   // body is a sibling of params; this endpoint takes an array
+});
+```
+
+Results are `{ data }`; failures throw. Prefer the thin wrappers in `src/lib/api/*.server.ts` (`fetchProductById`, `fetchProductsByIds` which chunks to the 24-id limit, category, search, order, customer and basket helpers): they log and rethrow as `NormalizedApiError` (`@/lib/api/normalized-api-error`, with `.status` and `.cause`). Add new wrappers there rather than calling clients inline in many routes.
+
+The clients already wrap `fetch` with request-scoped GET/HEAD dedupe (identical calls in one request share one response; any mutation clears the cache), a hard timeout from the `MRT_REQUEST_TIMEOUT` environment variable when set, and a health observer that logs 429 and load-status headers. Do not re-implement them. More: [API-CLIENTS.md](references/API-CLIENTS.md).
+
+Trim payloads: pass only the `expand`/`select` values you render. Availability is cached about 60 seconds and prices/promotions about 15 minutes, so short-TTL data is a good candidate for streaming. Shopper-agnostic responses can be cached using the policy in `src/lib/scapi/non-personalized-response-policy.server.ts` (see the shipped README-SCAPI-NON-PERSONALIZED-RESPONSES); request `personalized: 'none'` only where the response truly is the same for all shoppers, as the navigation loader in `_app.tsx` does.
+
+## Mutations: actions
+
+Prefer an `action.*` route and a `<Form>` (navigating) or `useFetcher` (non-navigating).
+
+Basket mutations use the factory, which loads the basket, parses `FormData`, catches errors and wraps the result:
+
+```ts
+// src/routes/action.example-remove-item.ts
+import { data } from 'react-router';
+import { BasketAction, createBasketAction } from '@/lib/cart/basket-action.server';
+import { createActionError } from '@/lib/action-error-helpers.server';
+import { ErrorCode } from '@/lib/error-codes';
+
+export const action = createBasketAction(
+    { method: 'POST', action: BasketAction.CartItemRemove, parse: (fd) => ({ itemId: String(fd.get('itemId') ?? '') }) },
+    async ({ input, basketId, clients }) => {
+        if (!input.itemId) {
+            return data({ success: false, error: createActionError({ code: ErrorCode.REQUIRED_FIELD, message: 'itemId is required' }) }, { status: 400 });
+        }
+        const { data: basket } = await clients.shopperBasketsV2.removeItemFromBasket({ params: { path: { basketId, itemId: input.itemId } } });
+        return basket; // factory returns { success: true, basket } and syncs the basket resource
+    }
+);
+```
+
+Return the updated `Basket` for success. Return `data(payload, { status })` for validation errors (use `data()` from `react-router`, not `Response.json`). Thrown SCAPI 4xx errors pass their status through; others become 500. Available `BasketAction` values are listed in `src/lib/cart/basket-action.server.ts`. See the existing `action.cart-item-*.tsx` files. Details and non-basket actions: [ACTIONS.md](references/ACTIONS.md).
+
+## Fetching from components
+
+- Use `useFetcher` against your own `action.*`/`resource.*` routes (`resourceRoutes` in `@/route-paths`).
+- Use `useScapiFetcher(client, method, { params, body })` from `@/hooks/use-scapi-fetcher` for a small allowlisted set of Shopper calls without writing a route. It returns `.load()`, `.submit(payload)`, `.data`, `.errors`, `.success`. The server enforces an allowlist in `src/lib/scapi/resource-policy.ts` (for example `shopperProducts.getProduct`, `shopperBasketsV2.getBasket`, `shopperSearch.getSearchSuggestions`, and selected `shopperCustomers` address and profile mutations). Anything else needs a dedicated route. See [SCAPI-FETCHER.md](references/SCAPI-FETCHER.md).
+- Do not fetch in `useEffect` on mount what the loader could fetch (see the performance review checklist in `storefront-next:sfnext-performance`).
+- Fetchers and raw `fetch` calls that do not go through a submission do not trigger revalidation; actions do, for every active loader.
+
+## Checklist
+
+1. Can the loader fetch this at request time? If yes, do it there.
+2. Is it critical? `await`; otherwise return the promise with its own Suspense and a sized skeleton.
+3. Did you request only the fields you render?
+4. Mutation errors: `createActionError` with an `ErrorCode`, return with `data(..., { status })`.
+5. New shared fetch logic goes in `src/lib/api/*.server.ts` with a test (`storefront-next:sfnext-testing`).
+6. Run `pnpm typecheck` and `pnpm test`.
+
+Deeper: [LOADERS.md](references/LOADERS.md).
+
+## Finding more
+
+Open `AGENTS.md` ("Key Documentation") and `docs/README-DATA.md` in your project. Search product docs with `b2c docs search "<term>"` or the `docs_search` MCP tool.
+
+## Related Skills
+
+- `storefront-next:sfnext-routing` - route files and links
+- `storefront-next:sfnext-revalidation` - avoid wasted loader re-runs after actions
+- `storefront-next:sfnext-performance` - Suspense placement, LCP, review checklist
+- `storefront-next:sfnext-state-management` - basket provider and client state
+- `storefront-next:sfnext-scapi` - SCAPI access and custom APIs
+- `storefront-next:sfnext-authentication` - sessions behind loaders
+- `b2c-cli:b2c-scapi-custom` - inspect custom API endpoints
+- `b2c:b2c-custom-api-development` - build a custom API

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

@@ -0,0 +1,53 @@
+# Actions and errors
+
+## Where to put a mutation
+
+Create `src/routes/action.<name>.ts(x)` exporting only `action`. Add an entry to `resourceRoutes` in `src/route-paths.ts`. The `/action/**` paths are excluded from the site prefix. Use `<Form method="post" action={resourceRoutes.x}>` when the user should navigate or when a native form must work without JavaScript; use `useFetcher` for in-place changes (add to cart, quantity changes, toggles).
+
+## Basket actions: `createBasketAction`
+
+`import { BasketAction, createBasketAction } from '@/lib/cart/basket-action.server'`
+
+```ts
+createBasketAction(
+    { method: 'POST' | 'PATCH', action: BasketAction.X, parse: (fd: FormData) => input },
+    async ({ input, basketId, basket, context, clients, logger }) => Basket | ReturnType<typeof data>
+)
+```
+
+- The factory enforces the HTTP method, ensures a basket exists, parses form data, runs the handler and converts the result.
+- Returning a `Basket` yields `{ success: true, basket }` (status 200) and updates the basket resource through `updateBasketResource` so the provider picks it up.
+- Returning `data({ success: false, error }, { status })` sends validation errors.
+- Throwing yields `{ success: false, error }`; a SCAPI 4xx keeps its status, anything else is 500.
+- Enum values: CartItemRemove, CartItemUpdate, CartItemAdd, CartSetAdd, CartBundleAdd, CartBundleUpdate, PromoCodeAdd, PromoCodeRemove, BonusProductAdd, SwatchOrder. Add new ones in the same file when a new kind of basket mutation needs its own name.
+- Request bodies for some calls are arrays (`addItemToBasket` takes `[payload]`).
+
+Read `action.cart-item-add.tsx`, `action.cart-item-update.tsx` and `action.cart-item-remove.tsx` for complete examples.
+
+## Other actions
+
+For non-basket work (customer, wishlist, consent, checkout), write a plain `action({ request, context })`: read `await request.formData()`, call `createApiClients(context)` or a `src/lib/api/*.server.ts` wrapper, and return `data(...)`. Check authentication with `getAuth(context)` where needed (`NOT_AUTHENTICATED`).
+
+## Error shape
+
+```ts
+import { createActionError } from '@/lib/action-error-helpers.server';
+import { ErrorCode } from '@/lib/error-codes';
+
+createActionError({ code: ErrorCode.INVALID_INPUT, message: 'Invalid quantity' });
+createActionError({ error: caughtError });            // normalizes SCAPI/unknown errors
+```
+
+`ErrorCode` members: NOT_FOUND, NOT_AUTHENTICATED, NOT_AUTHORIZED, INVALID_INPUT, REQUIRED_FIELD, CONFLICT, EXPIRED, OPERATION_FAILED, OUT_OF_STOCK, RATE_LIMITED, METHOD_NOT_ALLOWED, UNKNOWN, SCAPI_UNSUPPORTED, CONFIGURATION_ERROR.
+
+Response types live in `@/routes/types/action-responses` (`ActionResponse<T>`, `BasketActionResponse`). Return status codes with `data(payload, { status })` from `react-router`.
+
+## Client side
+
+- `useItemFetcher({ itemId, componentName })` (`@/hooks/use-item-fetcher`) gives per-line-item fetcher keys so a row shows its own pending state.
+- Optimistic UI: read `fetcher.formData`, `useNavigation`, or `useOptimistic`.
+- Side effects after a fetcher finishes: `useFetcherEffect` (`@/hooks/use-fetcher-effect`) or `useScapiFetcherEffect` (`@/hooks/use-scapi-fetcher-effect`) instead of hand-written `useEffect` chains.
+
+## After an action
+
+React Router revalidates every active loader by default. Decide which should re-run and declare it with `shouldRevalidate` or tags: `storefront-next:sfnext-revalidation`.

package/content/guidance/storefront-next/sfnext-data-fetching/references/API-CLIENTS.md

@@ -0,0 +1,34 @@
+# API clients
+
+`createApiClients(context)` (`@/lib/api-clients.server`) builds, per request, the typed clients used in loaders and actions. Cost is low; call it in each function that needs it.
+
+## What you get
+
+`AppClients` (type in `@/scapi/custom-clients`) is the generated Shopper API clients merged with clients generated for your custom APIs. Authentication (shopper access token), `siteId`, locale and currency come from the request context. The `@/scapi` barrel exports schema and operation types, for example `ShopperProducts.schemas['Product']` and `ApiError`.
+
+## Fetch layers
+
+Each client uses `dedupe(timeout(healthObserver(originBoundFetch)))`:
+
+| Layer | Behavior |
+|---|---|
+| dedupe | within one request, identical GET/HEAD calls share one promise; any non-GET call clears the whole registry |
+| timeout | aborts calls after `MRT_REQUEST_TIMEOUT` ms when that variable is set (no-op otherwise) |
+| health observer | logs 429 and SCAPI load-status signals |
+
+Consequences: it is safe for several components' loaders to request the same product; do not add your own in-memory cache keyed by request; after a write in the same request, re-reads are real calls.
+
+## Errors
+
+Clients throw. In `src/lib/api/*.server.ts`, catch and `throw new NormalizedApiError(error)`; route code checks `e.status`. Map 404 to a `Response` with status 404; let unexpected errors reach the route `ErrorBoundary`.
+
+## Custom APIs
+
+Generated custom-API clients appear on `AppClients` (for example a notification client). To add one: define the API with `storefront-next:sfnext-scapi` guidance, generate the client as described there, and call it as `clients.<name>.<operation>({ params, body })`.
+
+## Request shaping checklist
+
+- `expand`/`select` only what the UI renders.
+- `fetchProductsByIds` chunks at 24 ids; do not loop single `getProduct` calls.
+- Start independent calls before awaiting (parallel), but keep non-critical calls un-awaited.
+- Pass `personalized: 'none'` only for shopper-independent data, following `docs/README-SCAPI-NON-PERSONALIZED-RESPONSES.md`.