@salesforce/b2c-dx-mcp 3.2.0 → 3.3.0

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-configuration/SKILL.md

@@ -1,160 +1,163 @@
 ---
 name: sfnext-configuration
-description: Manage Storefront Next application configuration using config.server.ts, schema types, environment variables, and multi-site setup. Use when editing config.server.ts, adding PUBLIC__ environment variables, using useConfig or getConfig, or configuring multiple sites. NOT for initial project creation — see sfnext-project-setup.
+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`).
 ---
 
-# Configuration Skill
+# Storefront Next Configuration
 
-This skill covers the Storefront Next configuration system — centralized in `config.server.ts` with environment variable overrides.
+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).
 
-## Overview
+## Model
 
-All configuration is centralized in `config.server.ts` with typed defaults. Environment variables (via `.env` files or MRT settings) override these defaults. The system provides type-safe access with automatic parsing and validation.
+`config.server.ts` default-exports `defineConfig<Config>({ metadata, runtime, app }, { protectedPaths })`, imported from `@salesforce/storefront-next-runtime/config`.
 
-## Adding Configuration
+| 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 |
 
-### 1. Define the type in `src/types/config.ts`
+Because `app` reaches the browser, never put secrets in it.
 
-```typescript
-export type Config = {
-  app: {
-    myFeature: {
-      enabled: boolean;
-      maxItems: number;
-    };
-  };
-};
-```
+## Add a config value
 
-### 2. Set defaults in `config.server.ts`
+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
-export default defineConfig({
-  app: {
-    myFeature: {
-      enabled: false,
-      maxItems: 10,
-    },
-  },
-});
-```
-
-### 3. Override via environment variables
+// src/types/config.ts (inside AppConfig)
+myFeature: { enabled: boolean; maxItems: number };
 
-```bash
-PUBLIC__app__myFeature__enabled=true
-PUBLIC__app__myFeature__maxItems=20
+// config.server.ts (inside app)
+myFeature: { enabled: false, maxItems: 10 },
 ```
 
-## Accessing Configuration
-
-### In React Components
+## Read config
 
 ```typescript
-import { useConfig } from '@salesforce/storefront-next-runtime/config';
+import { getConfig, useConfig } from '@salesforce/storefront-next-runtime/config';
 
-export function MyComponent() {
-  const config = useConfig();
-
-  if (config.myFeature.enabled) {
-    const maxItems = config.myFeature.maxItems;
-    // Feature code
-  }
+// 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 };
 }
-```
 
-### In Server Loaders/Actions
+// Components
+const config = useConfig();               // client-facing shape (no serverExtension)
+```
 
-```typescript
-import { getConfig } from '@salesforce/storefront-next-runtime/config';
+- `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`.
 
-export function loader({context}: LoaderFunctionArgs) {
-  const config = getConfig(context); // context is required on server
+## Environment variable rules
 
-  if (config.myFeature.enabled) {
-    // Loader code
-  }
-}
+```
+PUBLIC__app__<path>__<to>__<key>=value   ->   config.app.<path>.<to>.<key>
 ```
 
-### In Browser Code (Non-Route Modules)
+| 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` |
 
-```typescript
-import { getConfig } from '@salesforce/storefront-next-runtime/config';
+### Required variables
 
-export function getFeatureFlag() {
-  const config = getConfig(); // No context needed in browser (uses window.__APP_CONFIG__)
-  return config.myFeature.enabled;
-}
+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=...
 ```
 
-**Note:** `getConfig()` and `useConfig()` return `AppConfig` — the `app` section of the full config. Access properties directly (e.g., `config.myFeature.enabled`) without the `app` prefix.
+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).
 
-## Environment Variable Rules
+### Debug "my env var is not applied"
 
 ```bash
-# Pattern: PUBLIC__app__{path}__{to}__{property}=value
-PUBLIC__app__commerce__api__clientId=abc123
-# Maps to config.app.commerce.api.clientId
-# Accessed as config.commerce.api.clientId
+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)
 ```
 
-| Rule              | Detail                                         |
-| ----------------- | ---------------------------------------------- |
-| `PUBLIC__` prefix | Exposed to browser (client-safe)               |
-| No prefix         | Server-only (secrets)                          |
-| `__` separator    | Navigate nested paths                          |
-| Auto-parsing      | Numbers, booleans, JSON parsed automatically   |
-| Validation        | Paths must exist in `config.server.ts`         |
-| Depth limit       | Maximum 10 levels                              |
-| MRT limits        | Names max 512 chars; total `PUBLIC__` max 32KB |
+The `config:inspect` script echoes a tip after the command, so call `sfnext config inspect` directly when passing flags.
 
-## Multi-Site Configuration
+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.
 
-```bash
-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"]
-  }
-]'
-```
+## Protected paths
 
-```typescript
-const config = getConfig(context);
-const currentSite = config.commerce.sites[0];
-const locale = currentSite.defaultLocale; // "en-US"
-const currency = currentSite.defaultCurrency; // "USD"
-```
+`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:
 
-## Security
+- `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`
 
-```bash
-# Client-safe (PUBLIC__ prefix)
-PUBLIC__app__commerce__api__clientId=abc123
+The rest of `app.engagement` is overridable. Check the `protectedConfigPaths` export in your `config.server.ts` for the current list.
 
-# Server-only (no prefix — never sent to client)
-COMMERCE_API_SLAS_SECRET=your-secret
-```
+## 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.
 
-Read server-only secrets directly from `process.env` — never add them to the config system.
+Extension `config.ts` / `server-config.ts` must not read `process.env` (an AST check fails discovery).
 
-## Common Pitfalls
+## Extension config
 
-| Pitfall           | Problem                                    | Solution                                           |
-| ----------------- | ------------------------------------------ | -------------------------------------------------- |
-| Missing `context` | `getConfig()` returns undefined in loaders | Use `getConfig(context)` on server                 |
-| Typo in env var   | Variable silently ignored                  | Validation catches paths not in `config.server.ts` |
-| Exposing secrets  | Sensitive data in browser                  | Use no-prefix variables; access via `process.env`  |
+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` - Initial environment setup and `.env` configuration
-- `storefront-next:sfnext-data-fetching` - Using config in loader functions
-- `storefront-next:sfnext-deployment` - MRT environment variable configuration
+- `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/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-configuration/evals/trigger-evals.json

@@ -0,0 +1,5 @@
+[
+  {"query": "How do I add a new setting to config.server.ts and read it in a loader with getConfig?", "should_trigger": true},
+  {"query": "Set up a second site with its own locales and URL prefix in Storefront Next", "should_trigger": true},
+  {"query": "Push my built bundle to Managed Runtime staging", "should_trigger": false}
+]

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/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/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/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`.