@salesforce/b2c-dx-mcp 2.1.2 → 3.0.0

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/README.md

@@ -0,0 +1,56 @@
+# storefront-next
+
+Agent skills for building Salesforce B2C Storefront Next projects — React 19 storefronts with routing, data fetching, Page Designer, authentication, i18n, extensions, and deployment to Managed Runtime.
+
+Part of the [B2C Developer Tooling](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling) marketplace.
+
+## Installation
+
+```bash
+# Claude Code
+claude plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling
+claude plugin install storefront-next@b2c-developer-tooling
+
+# GitHub Copilot CLI
+copilot plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling
+copilot plugin install storefront-next@b2c-developer-tooling
+```
+
+**VS Code (GitHub Copilot):** Command Palette → **Chat: Install Plugin From Source** → enter the repo `SalesforceCommerceCloud/b2c-developer-tooling`.
+
+**Codex:** open the repo as a workspace, restart Codex, then install from the **B2C Developer Tooling** marketplace in the plugin directory.
+
+For file-copy install to any supported IDE, use `b2c setup skills storefront-next`. See the [install guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/agent-skills) for details.
+
+## What's included
+
+Skills covering the full Storefront Next development lifecycle:
+
+- **`sfnext-project-setup`** — project creation, environment configuration, project structure
+- **`sfnext-routing`** — React Router 7 file-based routing with flat-routes conventions
+- **`sfnext-data-fetching`** — server-side loaders, actions, useScapiFetcher
+- **`sfnext-components`** — UI components, createPage HOC, shadcn/ui, Tailwind CSS v4
+- **`sfnext-create-component`** — design-system component authoring: layer model, CVA variants, data-slot, accessibility, Storybook coverage
+- **`sfnext-create-vertical`** — create a new brand theme / storefront variant via the brand token layer, typography, dark mode, and fixtures
+- **`sfnext-configuration`** — config.server.ts, environment variables, multi-site setup
+- **`sfnext-page-designer`** — Page Designer integration with React decorators and component registry
+- **`sfnext-extensions`** — extension system, target points, extension routes, and the base-audit decision gate (extend vs token/variant override)
+- **`sfnext-authentication`** — split-cookie SLAS architecture, auth middleware, session management
+- **`sfnext-i18n`** — internationalization with i18next, dual-instance server/client, namespaces
+- **`sfnext-state-management`** — React context, Zustand stores, basket provider
+- **`sfnext-testing`** — Vitest unit tests, Storybook stories, interaction and accessibility testing
+- **`sfnext-performance`** — bundle size limits, DynamicImage, parallel fetching, Lighthouse optimization
+- **`sfnext-scapi-management`** — manage typed SCAPI clients, discover API schemas before coding
+- **`sfnext-custom-apis`** — end-to-end custom API implementation and consumption
+- **`sfnext-deployment`** — build and deploy to Managed Runtime (MRT), cartridge deployment
+- **`sfnext-hybrid-storefronts`** — hybrid setup with SFRA/SiteGenesis, gradual migration, session bridging
+
+See [`skills/`](./skills/) for the full list.
+
+## Related plugins
+
+- **[`storefront-next-figma`](../storefront-next-figma)** — design-kit companion: duplicate the Figma kit for a vertical and sync brand tokens. Pairs with `sfnext-create-vertical`. Requires the Figma MCP server.
+
+## License
+
+Apache-2.0. See the [repo LICENSE](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/blob/main/LICENSE.txt).

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/assets/logo.svg

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 92 64">
+  <defs>
+    <style>
+      .cls-1, .cls-2 {
+        fill: #fff;
+      }
+
+      .cls-3 {
+        fill: #0d9dda;
+      }
+
+      .cls-2 {
+        fill-rule: evenodd;
+      }
+    </style>
+  </defs>
+  <path class="cls-3" d="m38.33,6.98c2.95-3.07,7.05-4.98,11.59-4.98,6.04,0,11.3,3.37,14.11,8.36,2.44-1.09,5.14-1.7,7.97-1.7,10.89,0,19.71,8.9,19.71,19.89s-8.83,19.89-19.71,19.89c-1.33,0-2.63-.13-3.88-.39-2.47,4.4-7.18,7.38-12.58,7.38-2.26,0-4.4-.52-6.3-1.45-2.5,5.89-8.34,10.02-15.13,10.02s-13.11-4.48-15.43-10.76c-1.01.21-2.06.33-3.14.33-8.43,0-15.26-6.9-15.26-15.42,0-5.71,3.07-10.69,7.63-13.36-.94-2.16-1.46-4.55-1.46-7.05C6.45,7.94,14.4,0,24.21,0,29.97,0,35.09,2.74,38.33,6.98Z"/>
+  <g>
+    <path class="cls-1" d="m13.53,33.19c-.06.15.02.18.04.21.17.12.35.21.52.32.93.49,1.81.64,2.73.64,1.88,0,3.04-1,3.04-2.6v-.03c0-1.48-1.32-2.02-2.55-2.41l-.16-.05c-.93-.3-1.73-.56-1.73-1.18v-.03c0-.52.47-.91,1.2-.91.81,0,1.77.27,2.38.61,0,0,.18.12.25-.06.04-.1.35-.94.38-1.03.04-.1-.03-.17-.09-.21-.71-.43-1.68-.72-2.69-.72h-.19c-1.72,0-2.92,1.04-2.92,2.52v.03c0,1.57,1.32,2.07,2.56,2.43l.2.06c.9.28,1.68.52,1.68,1.15v.03c0,.58-.51,1.01-1.32,1.01-.32,0-1.33,0-2.42-.7-.13-.08-.21-.13-.31-.19-.05-.03-.19-.09-.25.08l-.37,1.03Z"/>
+    <path class="cls-1" d="m40.98,33.19c-.06.15.02.18.04.21.17.12.35.21.52.32.93.49,1.81.64,2.73.64,1.88,0,3.04-1,3.04-2.6v-.03c0-1.48-1.31-2.02-2.55-2.41l-.16-.05c-.93-.3-1.73-.56-1.73-1.18v-.03c0-.52.47-.91,1.2-.91.81,0,1.77.27,2.38.61,0,0,.18.12.25-.06.04-.1.35-.94.38-1.03.04-.1-.03-.17-.09-.21-.71-.43-1.68-.72-2.69-.72h-.19c-1.72,0-2.92,1.04-2.92,2.52v.03c0,1.57,1.32,2.07,2.56,2.43l.2.06c.9.28,1.68.52,1.68,1.15v.03c0,.58-.51,1.01-1.32,1.01-.32,0-1.33,0-2.42-.7-.13-.08-.21-.13-.31-.19-.03-.02-.19-.08-.25.08l-.37,1.03Z"/>
+    <path class="cls-1" d="m61.29,28.36c-.15-.52-.39-.98-.71-1.36-.32-.38-.72-.69-1.2-.91-.48-.22-1.04-.34-1.68-.34s-1.2.11-1.68.34c-.48.22-.88.53-1.2.91-.32.38-.56.84-.71,1.36-.15.52-.23,1.08-.23,1.68s.08,1.17.23,1.68c.15.52.39.98.71,1.36.32.38.73.69,1.2.91.48.22,1.04.33,1.68.33s1.2-.11,1.68-.33c.48-.22.88-.52,1.2-.91.32-.38.56-.84.71-1.36.15-.52.23-1.08.23-1.68s-.08-1.17-.23-1.68m-1.57,1.68c0,.91-.17,1.62-.5,2.13-.33.5-.83.74-1.52.74s-1.19-.24-1.52-.74c-.33-.51-.5-1.22-.5-2.13s.17-1.62.49-2.12c.33-.5.82-.74,1.52-.74s1.19.24,1.52.74c.33.5.5,1.21.5,2.12"/>
+    <path class="cls-2" d="m74.15,32.67c-.05-.15-.2-.09-.2-.09-.23.09-.47.17-.73.21-.26.04-.55.06-.86.06-.76,0-1.36-.23-1.79-.67-.43-.45-.68-1.17-.67-2.14,0-.89.22-1.55.6-2.06.38-.51.96-.76,1.74-.76.65,0,1.14.07,1.66.24,0,0,.12.05.18-.11.14-.38.24-.65.39-1.07.04-.12-.06-.17-.1-.18-.2-.08-.68-.21-1.04-.26-.34-.05-.73-.08-1.17-.08-.66,0-1.24.11-1.75.34-.5.22-.92.53-1.26.91-.34.38-.59.84-.76,1.36-.17.52-.26,1.08-.26,1.69,0,1.3.35,2.35,1.04,3.12.69.77,1.73,1.16,3.09,1.16.8,0,1.62-.16,2.22-.4,0,0,.11-.05.06-.19l-.38-1.06Z"/>
+    <path class="cls-2" d="m82.16,28.07c-.13-.5-.46-1.01-.68-1.24-.34-.37-.67-.62-1.01-.77-.43-.19-.95-.31-1.52-.31-.66,0-1.26.11-1.75.34-.49.23-.9.54-1.22.93-.32.39-.56.85-.72,1.38-.15.52-.23,1.09-.23,1.69s.08,1.18.24,1.69c.16.52.42.97.77,1.35.35.38.8.68,1.33.88.53.21,1.18.31,1.92.31,1.53,0,2.34-.35,2.67-.53.06-.03.11-.09.05-.25l-.35-.97c-.05-.14-.2-.09-.2-.09-.38.14-.92.39-2.18.39-.82,0-1.43-.24-1.81-.62-.39-.39-.58-.96-.62-1.76h5.3s.14,0,.15-.13c0-.06.18-1.09-.16-2.28Zm-5.27,1.11c.07-.5.21-.92.43-1.25.32-.5.82-.77,1.52-.77s1.15.27,1.48.77c.22.33.31.76.35,1.25h-3.78Z"/>
+    <path class="cls-2" d="m39.72,28.07c-.13-.5-.46-1.01-.68-1.24-.34-.37-.67-.62-1.01-.77-.43-.19-.95-.31-1.52-.31-.66,0-1.26.11-1.75.34-.49.23-.9.54-1.22.93-.32.39-.56.85-.72,1.38-.15.52-.23,1.09-.23,1.69s.08,1.18.24,1.69c.16.52.42.97.77,1.35.35.38.8.68,1.33.88.53.21,1.18.31,1.92.31,1.53,0,2.34-.35,2.67-.53.06-.03.11-.09.04-.25l-.35-.97c-.05-.14-.2-.09-.2-.09-.38.14-.92.39-2.18.39-.82,0-1.43-.24-1.81-.62-.39-.39-.58-.96-.62-1.76h5.3s.14,0,.15-.13c0-.06.18-1.09-.16-2.28Zm-5.27,1.11c.07-.5.21-.92.43-1.25.33-.5.82-.77,1.52-.77s1.15.27,1.49.77c.22.33.31.76.35,1.25h-3.78Z"/>
+    <path class="cls-1" d="m25.1,28.92c-.22-.02-.49-.02-.83-.02-.45,0-.89.06-1.31.17-.41.11-.79.28-1.11.51-.32.23-.58.52-.77.87-.19.35-.28.76-.28,1.22s.08.88.24,1.21c.16.33.39.61.69.83.29.21.66.37,1.08.47.42.09.89.14,1.4.14.54,0,1.09-.05,1.61-.13.52-.09,1.16-.22,1.33-.26.18-.04.37-.09.37-.09.13-.03.12-.17.12-.17v-4.85c0-1.06-.29-1.85-.85-2.34-.56-.49-1.37-.73-2.43-.73-.4,0-1.04.05-1.42.13,0,0-1.16.22-1.63.6,0,0-.1.06-.05.21l.38,1.01c.05.13.17.09.17.09,0,0,.04-.02.09-.04,1.02-.55,2.31-.54,2.31-.54.57,0,1.01.12,1.31.34.29.22.44.56.44,1.26v.22c-.45-.07-.87-.1-.87-.1Zm-2.11,3.72c-.21-.17-.24-.21-.31-.31-.1-.16-.16-.39-.16-.69,0-.47.15-.8.47-1.03,0,0,.46-.4,1.54-.38.76,0,1.44.12,1.44.12v2.41h0s-.67.14-1.43.19c-1.08.06-1.56-.31-1.55-.31Z"/>
+    <path class="cls-2" d="m67.84,26.19c.04-.12-.04-.18-.08-.19-.09-.03-.54-.13-.89-.15-.67-.04-1.04.07-1.37.22-.33.15-.69.39-.9.66v-.65c0-.09-.06-.16-.15-.16h-1.36c-.09,0-.15.07-.15.16v7.91c0,.09.07.16.16.16h1.39c.09,0,.16-.07.16-.16v-3.95c0-.53.06-1.06.18-1.39.11-.33.27-.59.46-.78.19-.19.41-.32.65-.39.25-.08.52-.1.71-.1.28,0,.58.07.58.07.1.01.16-.05.19-.14.09-.24.35-.97.4-1.11Z"/>
+    <path class="cls-2" d="m54.77,22.53c-.17-.05-.32-.09-.52-.12-.2-.04-.45-.06-.72-.06-.96,0-1.71.27-2.24.81-.53.53-.89,1.34-1.06,2.4l-.06.36h-1.2s-.15,0-.18.15l-.2,1.1c-.01.11.03.17.17.17h1.17l-1.19,6.63c-.09.53-.2.97-.32,1.31-.12.33-.23.57-.37.75-.14.17-.26.3-.48.37-.18.06-.39.09-.62.09-.13,0-.3-.02-.43-.05-.13-.02-.19-.05-.29-.09,0,0-.14-.05-.19.09-.04.11-.36.97-.39,1.08-.04.1.02.19.08.21.16.06.27.09.48.14.29.07.54.07.78.07.49,0,.93-.07,1.3-.2.37-.13.69-.37.98-.68.31-.34.5-.7.69-1.19.18-.48.34-1.08.47-1.78l1.19-6.76h1.75s.15,0,.18-.15l.2-1.1c.01-.11-.03-.17-.17-.17h-1.69s.09-.63.28-1.2c.08-.24.24-.43.37-.57.13-.13.28-.22.44-.28.17-.05.36-.08.57-.08.16,0,.32.02.44.04.16.03.23.05.27.07.17.05.2,0,.23-.08l.41-1.11c.04-.12-.06-.17-.1-.18Z"/>
+    <path class="cls-2" d="m31.1,33.99c0,.09-.06.16-.15.16h-1.41c-.09,0-.15-.07-.15-.16v-11.31c0-.09.06-.16.15-.16h1.41c.09,0,.15.07.15.16v11.31Z"/>
+  </g>
+</svg>

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/plugin.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "storefront-next",
+  "version": "1.9.0",
+  "description": "Storefront Next development skills for building React 19 storefronts on Salesforce B2C Commerce.",
+  "author": {
+    "name": "Salesforce"
+  },
+  "homepage": "https://salesforcecommercecloud.github.io/b2c-developer-tooling/",
+  "repository": "https://github.com/SalesforceCommerceCloud/b2c-developer-tooling",
+  "license": "Apache-2.0",
+  "keywords": [
+    "salesforce",
+    "storefront-next",
+    "react",
+    "b2c-commerce",
+    "commerce-cloud"
+  ],
+  "extensions": {
+    "com.openai": {
+      "interface": {
+        "displayName": "Storefront Next",
+        "shortDescription": "Build Salesforce B2C Storefront Next projects with AI assistance.",
+        "longDescription": "Skills for developing React 19 storefronts on Salesforce B2C Commerce — routing, data fetching, components, Page Designer, authentication, i18n, extensions, testing, and deployment to Managed Runtime.",
+        "developerName": "Salesforce",
+        "category": "Productivity",
+        "capabilities": [
+          "Read"
+        ],
+        "logo": "./assets/logo.svg",
+        "composerIcon": "./assets/logo.svg",
+        "brandColor": "#0D9DDA",
+        "websiteURL": "https://salesforcecommercecloud.github.io/b2c-developer-tooling/",
+        "defaultPrompt": [
+          "Set up a new Storefront Next project",
+          "Add a new route with data fetching to my storefront",
+          "Deploy my storefront to Managed Runtime",
+          "Add Page Designer support to my storefront component"
+        ]
+      }
+    }
+  }
+}

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

@@ -0,0 +1,120 @@
+---
+name: sfnext-authentication
+description: 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.
+---
+
+# Authentication Skill
+
+This skill covers Storefront Next's split-cookie authentication architecture with SLAS (Shopper Login and API Access Service).
+
+## Overview
+
+Storefront Next uses a split-cookie architecture separating server and client auth concerns:
+
+- **Server middleware** (`auth.server.ts`) — Manages SLAS tokens, writes cookies, handles token refresh
+- **React Context** (`AuthProvider`) — Provides public session data (non-sensitive fields) to components via `useAuth()`
+
+## Cookie Design
+
+| Cookie | Purpose | User Type | Expiry | HttpOnly |
+|--------|---------|-----------|--------|----------|
+| `cc-nx-g` | Guest refresh token | Guest | 30 days | No |
+| `cc-nx` | Registered refresh token | Registered | 90 days | No |
+| `cc-at` | Access token | Both | 30 min | No |
+| `usid` | User session ID | Both | Matches refresh | No |
+| `customerId` | Customer ID | Registered | Matches refresh | No |
+
+**Key points:**
+- Only ONE refresh token exists at a time (guest OR registered, never both)
+- User type is derived from which refresh token is present
+- Cookies are auto-namespaced with `siteId`
+- Tokens auto-refresh when expired
+
+## Usage in Loaders/Actions
+
+```typescript
+import { getAuth } from '@/middlewares/auth.server';
+
+export function loader({ context }: LoaderFunctionArgs) {
+    const auth = getAuth(context);
+
+    const { accessToken, customerId, userType } = auth;
+    const isGuest = userType === 'guest';
+    const isRegistered = userType === 'registered';
+
+    return { isGuest, customerId };
+}
+```
+
+## Usage in Components
+
+```typescript
+import { useAuth } from '@/providers/auth';
+
+export function MyComponent() {
+    const auth = useAuth();
+
+    if (auth?.userType === 'guest') {
+        return <LoginPrompt />;
+    }
+
+    return <div>Welcome, customer {auth?.customerId}</div>;
+}
+```
+
+## Common Patterns
+
+### Protected Routes
+
+```typescript
+export function loader({ context }: LoaderFunctionArgs) {
+    const auth = getAuth(context);
+
+    if (auth.userType === 'guest') {
+        throw redirect('/login');
+    }
+
+    const clients = createApiClients(context);
+    return {
+        orders: clients.shopperOrders.getOrders({
+            params: { path: { customerId: auth.customerId } }
+        }).then(({ data }) => data),
+    };
+}
+```
+
+### Conditional Data Loading
+
+```typescript
+export function loader({ context }: LoaderFunctionArgs) {
+    const auth = getAuth(context);
+    const clients = createApiClients(context);
+
+    const base = {
+        products: clients.shopperProducts.getProducts({...}).then(({ data }) => data),
+    };
+
+    if (auth.userType === 'registered') {
+        return {
+            ...base,
+            wishlist: clients.shopperCustomers.getWishlist({...}).then(({ data }) => data),
+        };
+    }
+
+    return base;
+}
+```
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| `auth` is undefined | Missing auth middleware | Ensure `auth.server.ts` middleware is configured |
+| Always guest | Refresh token expired | Check cookie expiry; SLAS auto-refreshes |
+| Token errors in SCAPI | Stale access token | Tokens auto-refresh; check SLAS client configuration |
+
+## Related Skills
+
+- `storefront-next:sfnext-data-fetching` - Using auth context in loader functions
+- `storefront-next:sfnext-configuration` - SLAS client configuration
+- `storefront-next:sfnext-hybrid-storefronts` - Session bridging with SFRA

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

@@ -0,0 +1,191 @@
+---
+name: sfnext-components
+description: 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.
+---
+
+# Components Skill
+
+This skill covers component development patterns in Storefront Next — createPage HOC, Suspense boundaries, shadcn/ui integration, and Tailwind CSS styling.
+
+## Page Component Pattern
+
+Most routes export a default function component that receives `loaderData` as props:
+
+```typescript
+import { Suspense } from 'react';
+import { Await } from 'react-router';
+import { SeoMeta } from '@/components/seo-meta';
+
+type ProductPageData = {
+    product: Promise<Product>;
+    reviews: Promise<Reviews>;
+};
+
+export default function ProductPage({ loaderData }: { loaderData: ProductPageData }) {
+    return (
+        <>
+            <SeoMeta title="Product" />
+            <Suspense fallback={<ProductHeaderSkeleton />}>
+                <Await resolve={loaderData.product}>
+                    {(product) => <ProductHeader product={product} />}
+                </Await>
+            </Suspense>
+            <Suspense fallback={<ReviewsSkeleton />}>
+                <Await resolve={loaderData.reviews}>
+                    {(reviews) => <ProductReviews reviews={reviews} />}
+                </Await>
+            </Suspense>
+        </>
+    );
+}
+```
+
+### createPage HOC (Optional)
+
+For pages needing standardized Suspense wrappers and page key management:
+
+```typescript
+import { createPage } from '@/components/create-page';
+
+export default createPage({
+    component: ProductView,
+    fallback: <ProductSkeleton />,
+});
+```
+
+## Suspense Boundaries and Code Splitting
+
+Use `<Suspense>` + `<Await>` for streaming loader data, and `lazy()` for code-splitting heavy components:
+
+```typescript
+import { lazy, Suspense } from 'react';
+
+// Code-split a heavy component
+const CustomerReviewsSection = lazy(() =>
+    import('@/components/customer-reviews-section/customer-reviews-section')
+);
+
+export default function ProductPage({ loaderData }: { loaderData: ProductPageData }) {
+    return (
+        <>
+            {/* Stream loader data */}
+            <Suspense fallback={<ProductHeaderSkeleton />}>
+                <Await resolve={loaderData.product}>
+                    {(product) => <ProductHeader product={product} />}
+                </Await>
+            </Suspense>
+
+            {/* Code-split component */}
+            <Suspense fallback={<ReviewsSkeleton />}>
+                <CustomerReviewsSection productId={loaderData.productId} />
+            </Suspense>
+        </>
+    );
+}
+```
+
+## shadcn/ui Components
+
+shadcn/ui provides pre-built accessible components. Add them via CLI:
+
+```bash
+npx shadcn@latest add button
+npx shadcn@latest add card
+npx shadcn@latest add dialog
+```
+
+**Rules:**
+
+- Add components via CLI only (do not manually create files in `src/components/ui/`)
+- `src/components/ui/` components are copied into your project and can be customized directly
+- Keep app/domain components outside `src/components/ui/`:
+
+```typescript
+// Optional wrapper for app-specific styling
+import { Button } from '@/components/ui/button';
+
+export function PrimaryButton(props: React.ComponentProps<typeof Button>) {
+    return <Button {...props} className={cn('rounded-full', props.className)} />;
+}
+```
+
+## Tailwind CSS Styling
+
+Tailwind CSS v4 is the only permitted styling approach:
+
+```typescript
+import { cn } from '@/lib/utils';
+
+export function ProductCard({ featured }: { featured?: boolean }) {
+    return (
+        <div className={cn(
+            'rounded-lg border border-border bg-card p-4',
+            featured && 'ring-2 ring-primary'
+        )}>
+            <h2 className="text-lg font-semibold text-card-foreground">
+                Product Name
+            </h2>
+        </div>
+    );
+}
+```
+
+**Rules:**
+
+- Use Tailwind utility classes as the primary styling approach
+- Use `cn()` for conditional class merging
+- Follow mobile-first responsive design (`md:`, `lg:` breakpoints)
+- Prefer Tailwind over inline styles; inline styles are acceptable for truly dynamic values (e.g., `backgroundColor` from API data)
+- No CSS modules or separate CSS files
+- Custom global CSS only in `src/app.css`
+
+### Dark Mode
+
+Theme variables automatically adapt via CSS variables:
+
+```typescript
+<div className="bg-background text-foreground border-border">
+    <button className="bg-primary text-primary-foreground">Click me</button>
+</div>
+```
+
+### Responsive Design
+
+```typescript
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+    {products.map(p => <ProductCard key={p.id} product={p} />)}
+</div>
+```
+
+## File Organization
+
+```
+src/components/product-tile/
+├── index.tsx              # Component implementation
+├── index.test.tsx         # Vitest unit tests
+└── stories/
+    ├── index.stories.tsx  # Storybook stories
+    └── __snapshots__/     # Storybook snapshots (optional)
+
+src/components/product-skeleton/
+├── index.tsx              # Skeleton component (separate from main)
+├── index.test.tsx
+└── stories/
+    └── index.stories.tsx
+```
+
+## Best Practices
+
+1. **Export default function components** — Receive `loaderData` as props
+2. **Granular Suspense boundaries** — Show content progressively as data resolves
+3. **Use `lazy()` for heavy components** — Code-split below-the-fold or conditional UI
+4. **Reusable skeleton components** — Consistent loading states
+5. **Colocate tests and stories** — Keep test files next to source files
+6. **TypeScript interfaces** — Define proper types for all props
+
+## Related Skills
+
+- `storefront-next:sfnext-data-fetching` - Loader patterns that feed data to components
+- `storefront-next:sfnext-testing` - Writing Vitest tests and Storybook stories
+- `storefront-next:sfnext-page-designer` - Page Designer component integration
+- `storefront-next:sfnext-i18n` - Translating component text

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

@@ -0,0 +1,160 @@
+---
+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.
+---
+
+# Configuration Skill
+
+This skill covers the Storefront Next configuration system — centralized in `config.server.ts` with environment variable overrides.
+
+## Overview
+
+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.
+
+## Adding Configuration
+
+### 1. Define the type in `src/types/config.ts`
+
+```typescript
+export type Config = {
+  app: {
+    myFeature: {
+      enabled: boolean;
+      maxItems: number;
+    };
+  };
+};
+```
+
+### 2. Set defaults in `config.server.ts`
+
+```typescript
+export default defineConfig({
+  app: {
+    myFeature: {
+      enabled: false,
+      maxItems: 10,
+    },
+  },
+});
+```
+
+### 3. Override via environment variables
+
+```bash
+PUBLIC__app__myFeature__enabled=true
+PUBLIC__app__myFeature__maxItems=20
+```
+
+## Accessing Configuration
+
+### In React Components
+
+```typescript
+import { useConfig } from '@salesforce/storefront-next-runtime/config';
+
+export function MyComponent() {
+  const config = useConfig();
+
+  if (config.myFeature.enabled) {
+    const maxItems = config.myFeature.maxItems;
+    // Feature code
+  }
+}
+```
+
+### In Server Loaders/Actions
+
+```typescript
+import { getConfig } from '@salesforce/storefront-next-runtime/config';
+
+export function loader({context}: LoaderFunctionArgs) {
+  const config = getConfig(context); // context is required on server
+
+  if (config.myFeature.enabled) {
+    // Loader code
+  }
+}
+```
+
+### In Browser Code (Non-Route Modules)
+
+```typescript
+import { getConfig } from '@salesforce/storefront-next-runtime/config';
+
+export function getFeatureFlag() {
+  const config = getConfig(); // No context needed in browser (uses window.__APP_CONFIG__)
+  return config.myFeature.enabled;
+}
+```
+
+**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.
+
+## Environment Variable Rules
+
+```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
+```
+
+| 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 |
+
+## Multi-Site Configuration
+
+```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"]
+  }
+]'
+```
+
+```typescript
+const config = getConfig(context);
+const currentSite = config.commerce.sites[0];
+const locale = currentSite.defaultLocale; // "en-US"
+const currency = currentSite.defaultCurrency; // "USD"
+```
+
+## Security
+
+```bash
+# Client-safe (PUBLIC__ prefix)
+PUBLIC__app__commerce__api__clientId=abc123
+
+# Server-only (no prefix — never sent to client)
+COMMERCE_API_SLAS_SECRET=your-secret
+```
+
+Read server-only secrets directly from `process.env` — never add them to the config system.
+
+## Common Pitfalls
+
+| 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`  |
+
+## 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