salesforcecommercecloud/storefront-next

Implement authentication in Storefront Next using split-cookie architecture, SLAS tokens, and auth middleware. Use when accessing user identity in loaders, detecting guest vs registered users, using getAuth or useAuth, or understanding session management and token refresh.

Build UI components in Storefront Next using createPage HOC, Suspense/Await patterns, shadcn/ui, and Tailwind CSS v4. Use when creating page components, adding Suspense boundaries, integrating shadcn/ui, styling with Tailwind, or organizing component files. Covers server vs client rendering patterns and the cn() utility.

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.

Author a new Storefront Next design-system component the right way — pick the correct layer (primitive vs composite), reuse-or-extend before creating, define CVA variants bound to semantic tokens, add data-slot attributes, satisfy the accessibility checklist, and ship a Storybook story. Use when asked to create, add, or build a new UI component, button/badge/tile/card variant, or design-system primitive. This is the design-system authoring discipline; for createPage/Suspense/shadcn page-rendering patterns see sfnext-components.

Create a new Storefront Next vertical (brand theme / storefront variant) by editing brand design tokens, typography, dark mode, and the Figma kit. Use when asked to create a new vertical, brand, theme, or storefront variant, re-skin the storefront, or change the brand palette. Covers the brand.css token layer, semantic token rules, fixture-based local development, and the extension-vs-base decision. NOT for engineering component patterns — see sfnext-components.

End-to-end workflow for consuming custom SCAPI endpoints from a Storefront Next project — adding them as typed clients via b2c sfnext scapi add custom, discovering their schema, and calling them from loaders/actions/useScapiFetcher. Use this skill whenever the user wants to call a custom API from their Storefront Next app, gets a 404 or 401 when calling a custom endpoint from their sfnext loader, needs to add a custom API as a typed client in their storefront, asks about the full workflow from custom API cartridge to sfnext consumption, or says 'custom API in storefront next'. Also use when they ask how createApiClients exposes custom API methods or how to use useScapiFetcher with a custom endpoint. NOT for writing the custom API cartridge files (schema.yaml/script.js) from scratch — see b2c:b2c-custom-api-development. NOT for just checking registration status — see b2c-cli:b2c-scapi-custom.

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.

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.

Build extensions for Storefront Next using target-config.json, target points, extension routes, and translation namespaces. Use when creating modular features, inserting components into UI targets, adding extension routes, adding a section to an existing page, or using SFDC_EXT_ integration markers. Covers the base-audit decision gate (deciding whether to extend at all vs token/variant override), extension structure, targetId configuration, and extension registration in src/extensions/config.json.

Implement hybrid storefronts that run Storefront Next alongside SFRA or SiteGenesis. Use when planning gradual migration from SFRA, configuring hybrid proxy for local development, setting up session bridging between storefronts, or routing traffic between old and new implementations.

Implement internationalization in Storefront Next using i18next with useTranslation for components and getTranslation for server-side code. Use when adding translations, configuring locales, handling pluralization, using the Zod schema factory pattern, or managing extension translations. Covers namespaces, interpolation, and language switching.

Integrate Page Designer with Storefront Next using React decorators, component registry, and Region rendering. Use when creating merchant-editable pages, adding Page Designer components with @Component/@AttributeDefinition decorators, using fetchPageFromLoader, or rendering Regions. This is for the React/Storefront Next implementation — for classic ISML Page Designer, see b2c:b2c-page-designer.

Optimize Storefront Next performance with bundle size limits, DynamicImage component, Lighthouse audits, and progressive streaming. Use when checking bundle sizes, optimizing images, improving page load speed, or configuring performance metrics. Covers parallel data fetching, image optimization, and performance monitoring.

Create and configure Storefront Next projects. Use when creating a new storefront, understanding project structure, setting up environment variables, or running the sfnext CLI for the first time. Covers project creation, directory layout, .env configuration, and sfnext CLI basics.

Implement file-based routing in Storefront Next with React Router 7. Use when adding new pages, creating layout routes, defining route parameters, or understanding route module exports (loader, action, component, meta). Covers flat-routes conventions, nested layouts, and the _app prefix.

Add, remove, and list typed SCAPI clients in a Storefront Next project using b2c sfnext scapi commands, and browse API schemas to discover endpoints before writing loaders. Use this skill whenever the user says 'sfnext scapi', 'add an API to my storefront next project', 'what SCAPI clients does my sfnext project have', 'remove an API client', 'list available APIs for sfnext', 'browse schema before writing a loader', or asks how to integrate a specific SCAPI (shopper-baskets, shopper-search, etc.) into their Storefront Next project as a typed client. Also use when they want to check what parameters an endpoint accepts before coding. NOT for making actual SCAPI calls from loaders — see sfnext-data-fetching. NOT for standalone schema browsing outside a Storefront Next project — see b2c-cli:b2c-scapi-schemas.

Manage client-side state in Storefront Next using React context providers and feature-level Zustand stores. Use when handling basket/auth UI state, creating extension stores (for example store locator), or syncing client-visible state after server mutations. NOT for server-side data loading — see sfnext-data-fetching for loader patterns.

Write tests for Storefront Next using Vitest unit tests, Storybook stories, interaction tests, snapshot tests, and accessibility tests. Use when writing component tests, creating Storybook stories, running test coverage, or setting up test utilities. Covers testing-library patterns, play functions, and coverage thresholds.