salesforcecommercecloud/storefront-next

Build and fix accessible UI in a Storefront Next storefront (WCAG 2.1 AA): jsx-a11y lint findings, missing accessible names and labels, form error association, dialog focus management, aria-live status messages, keyboard behavior, color contrast, and verifying fixes with Storybook a11y/play() tests and the e2e axe scan with its baseline. Use for "accessibility", "a11y", "WCAG", "screen reader", "aria-label", "focus trap", "axe violation", pnpm lint:a11y, pnpm a11y, a11y-baseline.json, skip-a11y, STORYBOOK_A11Y_TEST_MODE, or an accessibility audit finding to fix. Do not use for general lint/typecheck gates (use storefront-next:sfnext-quality-gates), writing non-accessibility tests (use storefront-next:sfnext-testing), or color/token design (use storefront-next:sfnext-theming).

Storefront Next analytics: engagement adapters (Einstein, Active Data, Data 360), adding a custom adapter, tracking consent gating, PageViewTracker, useAnalytics events, and first-touch attribution (dw_attribution). Use when configuring engagement.adapters in config.server.ts, writing an adapter with hasConsent, registering it in initializeEngagementAdapters, wiring the consent banner (trackingConsent, consentCategories, dw_dnt), firing trackViewProduct/trackCartItemAdd events, debugging why no analytics events are sent, or passing campaign attribution to orders. Do not use for general config loading or env vars (use storefront-next:sfnext-configuration), CSP/script allowlisting of third-party tags (use storefront-next:sfnext-security), or SEO meta/JSON-LD (use storefront-next:sfnext-seo).

Work with Storefront Next's server-only authentication and session architecture (SLAS guest/registered tokens, httpOnly cookies, auth.server.ts middleware). Use for getAuth, useAuth, updateAuth, destroyAuth, protecting account routes, login/logout actions, guest-to-registered basket/wishlist merge, "session expired" redirects, 401 recovery loops, cc-at/cc-nx/usid/dwsid cookies, cookie names or expiry, passwordless login, social login, OTP email verification, passkeys, guest order lookup, or refresh-token lifetime settings. Do not use for Turnstile, CSP headers or cookie-domain config (use storefront-next:sfnext-security), calling SCAPI clients (use storefront-next:sfnext-scapi), or sharing sessions with SFRA (use storefront-next:sfnext-hybrid-storefronts).

Catalogue and router for optional Storefront Next commerce features: Shopper Context (qualifiers, source codes), Order Management returns/cancel/tracking (SOM/OMS), delivery estimates, feature stubs (@feature-stub), guest order lookup, the app_storefrontnext_base email cartridge, and the shipped extensions (bnpl, bopis, multiship, store-locator, ratings-reviews, customer-preferences, product-content, shipping-delivery, theme-switcher). For each: which flag, SLAS scope, Business Manager setting, cartridge, or extension registry entry it needs, and which in-project doc to read. Use when asked how to enable a feature, why a feature does not render, what prerequisites a feature has, or which stubs are mock data. Do not use for building a new extension (use storefront-next:sfnext-extensions), config loading (use storefront-next:sfnext-configuration), or SLAS login flows (use storefront-next:sfnext-authentication).

Build and modify UI components in a Storefront Next storefront: page components with Suspense and use()/Await, createPage and withSuspense, Tailwind v4 token classes, shape tokens (rounded-ui, shadow-ui, border-ui), shadcn/ui primitives in src/components/ui (sync-shadcn), CVA variants, data-slot, DynamicImage, lazy-loaded overlays, and Storybook stories with snapshot tests. Use when creating or editing a component in src/components, adding a shadcn primitive, fixing styling that ignores the theme, writing a *.stories.tsx file, or running pnpm storybook:test. Do not use for re-branding colors, fonts, or logos (use storefront-next:sfnext-theming), route loaders (use storefront-next:sfnext-data-fetching), or Page Designer registration (use storefront-next:sfnext-page-designer).

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).

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).

Build and deploy a Storefront Next storefront: pnpm build, pnpm push / sfnext push to Managed Runtime (MRT), MRT credentials (MRT_API_KEY, MRT_PROJECT, MRT_TARGET), syncing env vars with pnpm config:push-env, deploying the base cartridge and Page Designer metadata (pnpm cartridge:generate|validate|deploy), the shipped GitHub Actions deploy workflow, bundle size checks, the pre-launch checklist, and upgrading a project (template vs SDK compatibility, react-router pin). Use when a push fails or is rejected, a deployed site returns 500 or shows stale Page Designer components, "deploy to staging/production", or before go-live. Do not use for generic MRT project/environment/redirect/member management or log tailing (use b2c-cli:b2c-mrt), for config.server.ts and PUBLIC__ variable rules (use storefront-next:sfnext-configuration), or for creating the project (use storefront-next:sfnext-project-setup).

Add or remove modular features in a Storefront Next project with the extension system: src/extensions/<name>/ folders, target-config.json (UITarget components, contextProviders, actionHooks), sfcc.-prefixed UITarget ids, extension routes, per-extension config.ts and locales, SFDC_EXT_ integration markers, the sfnext extensions create|install|remove|list commands, and the agent-driven instructions/*.mdc install flow. Use when inserting a component into a UITarget slot (for example sfcc.header.before.cart or sfcc.pdp.bnpl.message), adding a checkout action hook, installing or removing store locator, BOPIS, multiship or a demo extension, listing extension points with pnpm extensions:list, or deciding whether to extend, restyle, or edit the base at all. Do not use for styling or brand changes (use storefront-next:sfnext-theming), for new merchant-editable Page Designer blocks (use storefront-next:sfnext-page-designer), or for analytics/engagement adapters (use storefront-next:sfnext-analytics-consent).

Run Storefront Next alongside an existing SFRA or SiteGenesis storefront for a gradual migration. Use for hybrid mode, PUBLIC__app__hybrid__enabled, legacyRoutes (exact, :param, * wildcard, { pattern, suffix }), HYBRID_PROXY_ENABLED, SFCC_ORIGIN, HYBRID_ROUTING_RULES, vite-plugins/hybrid-proxy.ts, the dwsid session bridge, sharing login/cart between SFRA and Storefront Next, eCDN routing rules, cookie domain for hybrid, "[Hybrid Proxy] SFCC returned a redirect to 404", blank proxied pages, or lost sessions when crossing storefronts. Do not use for the cookie-domain settings themselves beyond the hybrid checklist (use storefront-next:sfnext-security), auth code (use storefront-next:sfnext-authentication), or MRT deployment (use storefront-next:sfnext-deployment).

Translate and localize a Storefront Next storefront with i18next: useTranslation in components, getTranslation in loaders/actions/utilities, translations.json namespaces, pluralization and interpolation, Zod validation-message factories, adding a new language or locale, extension translations, and locale/currency switching. Use when adding or editing strings, "add a Brazilian Portuguese locale", supportedLngs / fallbackLng / supportedLocales, src/locales, locales:aggregate-extensions, LocaleSwitcher, mockI18nContext, hydration mismatch on translated text, or missing-key problems. Do not use for site/locale URL prefix routing (use storefront-next:sfnext-routing), site and currency configuration keys (use storefront-next:sfnext-configuration), or extension scaffolding (use storefront-next:sfnext-extensions).

Start here for any Salesforce Commerce Storefront Next (sfnext) task: a router that maps what you want to do to the right storefront-next skill, says to read your project's AGENTS.md and docs/README-*.md first, and carries a cheat sheet for the sfnext CLI, the b2c CLI, the b2c-dx-mcp tools, and the docs search fallback. Use when starting work in a Storefront Next project, when unsure which skill applies, when asked "how do I do X in Storefront Next", "what commands exist", or "where is the documentation". Do not use once a specific area is clear; go straight to that skill (for example storefront-next:sfnext-routing or storefront-next:sfnext-seo).

Build merchant-editable Page Designer content in a Storefront Next project: components decorated with @Component/@AttributeDefinition/@RegionDefinition, page routes decorated with @PageType, <Region> rendering, fetchPageWithComponentData, component loaders and fallbacks, the generated static registry, and the pnpm cartridge:generate / cartridge:validate / cartridge:deploy workflow. Use when adding or editing a Page Designer component, exposing a region on a route (home, PDP, PLP, search), fetching a page by pageId or aspectType, marking a Region critical, debugging a component that does not appear in the Business Manager palette or renders empty, or reviewing Page Designer code. Do not use for classic ISML/SFRA Page Designer (use b2c:b2c-page-designer), for turning a Figma frame into blocks (use figma-to-sfnext-pagedesigner:figma-to-sfnext-pagedesigner), or for plain React components that merchants never edit (use storefront-next:sfnext-components).

Keep a Storefront Next storefront fast and self-review changes for performance: LCP, CLS and TBT, Suspense placement and granularity, stable promise identity, lazy-loaded modals and drawers with useDeferredUnmount, useDeferredRender, Region critical, DynamicImage and image priority, font loading, resource hints (links.preconnect), bundle size checks (pnpm bundlesize, BUNDLES_SIZE_ANALYZE), Lighthouse CI, and the performance.metrics / Server-Timing flags. Use for "page is slow", "LCP regression", "skeleton flashes", "bundle too big", "review my diff for performance", "hydration mismatch or extra re-renders", "waterfall of fetches", or before merging feature work that adds loaders, fetchers, modals and drawers or images. Do not use for loader/action mechanics (use storefront-next:sfnext-data-fetching), revalidation policy (use storefront-next:sfnext-revalidation), or accessibility (use storefront-next:sfnext-accessibility).

Create and bootstrap a Storefront Next project, and learn its layout, npm scripts, and first-run workflow. Use when creating a new storefront, running sfnext create-storefront (--vertical starter theme, --defaults, --template, --output-dir), choosing between Business Manager Storefront Setup and the CLI, fixing pnpm install / Node 24 problems, copying .env.default to .env, asking "what does this folder do" or "which pnpm script do I run", or running b2c sfnext / pnpm sfnext commands for the first time. Do not use for config.server.ts or PUBLIC__ env var rules (use storefront-next:sfnext-configuration), building/pushing to Managed Runtime (use storefront-next:sfnext-deployment), or a conceptual tour of the architecture (use storefront-next:sfnext-overview).

Run and fix the Storefront Next quality gates before a PR or deploy: OxLint (type-aware, --max-warnings 0) plus Biome formatting, lint:a11y, lint:css, typecheck, the TypeScript-only check, bundle-size budgets, Lighthouse CI, and the pre-PR checklist. Use when pnpm lint, pnpm format:check, pnpm typecheck, pnpm bundlesize or pnpm lighthouse:ci fails, for custom/color-linter or custom/header-format errors, "unused Tailwind class" findings, oxlint-disable comments, "what should I run before opening a PR", or CI red on lint. Do not use for writing tests (use storefront-next:sfnext-testing), accessibility fixes themselves (use storefront-next:sfnext-accessibility), or runtime performance tuning (use storefront-next:sfnext-performance).

Control which Storefront Next loaders re-run after an action or navigation: shouldRevalidate exports, the policy modules in src/lib/revalidation/routes (root, cart, product, category, checkout, home, wishlist, api-client, shared), getActionPath and isAmbientMutation, and the tag primitives in src/lib/revalidation/tags (withRevalidateTags, shouldRevalidateForTags, tagGroup, tagImplications). Use for "page re-fetches after add to cart", "loader runs too often", "stale data after a mutation", "flash of skeleton after changing a swatch", "add shouldRevalidate", or when a new action or route changes which loaders fire. Do not use for writing loaders or actions (use storefront-next:sfnext-data-fetching), Suspense and LCP tuning (use storefront-next:sfnext-performance), or client-side state (use storefront-next:sfnext-state-management).

Add and change pages in a Storefront Next project: flat-file routes in src/routes, layout routes (_app, _checkout, _empty), splat routes for product and category pages, action.* and resource.* routes, src/route-paths.ts (routes, resourceRoutes, routeHref), site-aware Link and useNavigate wrappers, SeoMeta and JsonLd head tags, multi-site /:siteId/:localeId URL prefixes, url.seoRoutes and excludeRoutes, extension routes, and the SLAS callback routes. Use for "add a page", "new route", "why is my link missing the site prefix", "route file naming", "redirect to login", or a 404 on a new URL. Do not use for loader/action/fetcher data code (use storefront-next:sfnext-data-fetching), shouldRevalidate (use storefront-next:sfnext-revalidation), SEO strategy such as sitemaps and canonical rules (use storefront-next:sfnext-seo), or Page Designer regions (use storefront-next:sfnext-page-designer).

Use and extend SCAPI clients in a Storefront Next project: createApiClients, the @/scapi type barrel, typing c_* custom attributes by overriding a built-in client, and adding your own custom API end to end with b2c sfnext scapi (add, available, list, remove). Use for "clients.shopperProducts", "c_ attribute is not typed", "sfnext scapi add", "add custom API to the storefront", src/scapi/ generated files, custom-clients.ts, calling a loyalty/notify-style custom endpoint from a loader or action, useScapiFetcher, personalized=none for custom clients, or 404 from a custom endpoint. Do not use for writing the cartridge/schema.yaml itself (use b2c:b2c-custom-api-development), endpoint registration status (use b2c-cli:b2c-scapi-custom), loader/caching strategy (use storefront-next:sfnext-data-fetching), or login/session code (use storefront-next:sfnext-authentication).

Configure Storefront Next security response headers, Content Security Policy (CSP), CSP contributors, Cloudflare Turnstile bot protection, and the shared cookie domain. Use for "Refused to load the script/connect/image" CSP violations, adding a third-party origin, app.security.headers, defaultCspDirectives, csp reportOnly rollout, writing a CSP contributor under src/middlewares/csp-contributors, HSTS or Permissions-Policy, Turnstile widget or enforceTurnstile, TURNSTILE_SECRET_KEYS, log-only rollout, or app.cookies.domain across subdomains. Do not use for auth tokens, cookie names or login flows (use storefront-next:sfnext-authentication), SFRA proxy routing (use storefront-next:sfnext-hybrid-storefronts), or consent banners and tracking (use storefront-next:sfnext-analytics-consent).

Storefront Next SEO and AEO/GEO: the SeoMeta component (title, description, noIndex, Open Graph, X cards), JsonLd structured data, canonical URLs and the query-parameter allowlist, hreflang, configurable product/category URLs via url.seoRoutes, semantic URL builders (createProductUrl, createCategoryUrl, useSeoUrlContext), redirectToCanonicalPath, crawler rendering and pagination, and how multi-domain and base path affect generated URLs. Use when adding meta tags or JSON-LD to a route, enabling or changing seoRoutes, fixing duplicate or wrong canonical or og:url URLs, or when a build fails for a missing site in seoRoutes. Do not use for route file naming (use storefront-next:sfnext-routing), site/locale config in general (use storefront-next:sfnext-configuration), or translations (use storefront-next:sfnext-i18n).

Choose the right state mechanism in a Storefront Next project: loader and action data, useRouteLoaderData, URL state with useSearchParams, cookies and sessions, optimistic UI (fetcher.formData, useNavigation, useOptimistic), React context providers (BasketProvider, AuthProvider, wishlist, product-context), and small useSyncExternalStore stores such as the mini-cart store. Use for "where should this state live", "useBasket", "useAuth", "share state between components", "optimistic add to cart", "global client state", "hydration mismatch from a store", or "do I need Zustand". Do not use for fetching or mutating data (use storefront-next:sfnext-data-fetching), controlling loader re-runs (use storefront-next:sfnext-revalidation), or login flows and sessions (use storefront-next:sfnext-authentication).

Write and run tests for a Storefront Next project: Vitest + React Testing Library unit tests, route loader/action tests (createLoaderArgs, createTestContext), Storybook stories with snapshot, interaction (play) and a11y runs, and a pointer to the CodeceptJS/Playwright e2e suite. Use for "write a test for this component/loader", "add a story", pnpm test, pnpm storybook:test --type=snapshot|interaction|a11y, coverage thresholds, routeLoaderData / scapiMock / mockRoutes story parameters, MSW mocking, fixtures in @/components/__mocks__, failing snapshot updates, or pnpm e2e. Do not use for lint, typecheck, format, bundle-size or Lighthouse gates (use storefront-next:sfnext-quality-gates), accessibility rules and fixes (use storefront-next:sfnext-accessibility), or translations (use storefront-next:sfnext-i18n).

Re-brand and re-skin a Storefront Next storefront: change the color palette, corner radius and shadows (shape tokens), header and footer colors, typography and web fonts, logo, favicon, hero scrims, and brand copy, with WCAG contrast checks. Use when asked to rebrand or restyle the storefront, change the primary color, swap the font, make the header dark, make cards rounded or flat, replace the logo, edit src/theme, core.css, header.css, brand.css, tailwind.css, base.css, or src/lib/fonts.ts, or verify a theme change in the Design System Storybook stories. Do not use for building or styling an individual component (use storefront-next:sfnext-components), Figma kit sync (use storefront-next-figma:sfnext-create-figma-kit), or site configuration (use storefront-next:sfnext-configuration).