@salesforce/b2c-dx-mcp 0.0.1 → 0.3.1

package/content/page-designer.md

@@ -0,0 +1,86 @@
+# Page Designer Integration
+
+## Overview
+
+Page Designer is Commerce Cloud's visual editor in Business Manager: merchants build and edit storefront pages (home, category, etc.) without code. The app gets page structure (regions, components, attributes) from the **Shopper Experience API** and renders it via a **component registry** and `<Region>`.
+
+## Concepts
+
+| Concept | Role |
+|--------|------|
+| **Page** | Fetched in route loaders via `fetchPageFromLoader(args, { pageId })`. |
+| **Region** | Named area on a page; rendered with `<Region page={...} regionId="..." componentData={...} />`. |
+| **Component** | Content block (hero, grid, carousel, etc.) with a `typeId` and attributes; registered in `@/lib/registry`. |
+| **Registry** | Static registry in `@/lib/static-registry.ts` is **auto-generated** by the staticRegistry Vite plugin — do not edit by hand. |
+
+## Which pages use Page Designer
+
+Only **content pages** that merchants edit in Business Manager use Page Designer; cart, checkout, account, and auth do not.
+
+| Uses Page Designer | Does not |
+|--------------------|----------|
+| Home (`pageId: 'homepage'`), Category/PLP (`plp`), Search (`search`), Product/PDP (`pdp`) | Cart, Checkout, Account, Order confirmation, Auth |
+
+To add a new content page: define a page type and ID in Commerce Cloud, then in your route use `fetchPageFromLoader(args, { pageId })` and `collectComponentDataPromises(args, pagePromise)`, and render `<Region>` for each region.
+
+## Getting started
+
+### Route (new Page Designer page)
+
+- **In the loader**: call `fetchPageFromLoader(args, { pageId: '...' })` and `collectComponentDataPromises(args, pagePromise)`; return `page` and `componentData` (keep loaders synchronous; return promises for streaming).
+- **In the layout**: for each region, render `<Region page={loaderData.page} regionId="..." componentData={loaderData.componentData} />` with optional `fallbackElement` and `errorElement` for Suspense/error boundaries.
+- **On the route module**: add `@PageType({ name, description, supportedAspectTypes })` and `@RegionDefinition([{ id, name, description, maxComponents }])` so Business Manager knows the page type and regions. Example routes: home (`_app._index.tsx`), category/PLP (`_app.category.$categoryId.tsx`).
+
+### Component (new Page Designer component)
+
+- **Add a metadata class** with `@Component('typeId', { name, description })` and `@AttributeDefinition()` (and optionally `@AttributeDefinition({ type: 'image' })`, `type: 'url'`, etc.) for each prop you want editable in Page Designer. Use `@RegionDefinition([...])` if the component has nested regions (e.g. a grid with slots).
+- **Implement the React component** so it accepts those props (and strips Page Designer–only props like `component`, `page`, `componentData`, `designMetadata` before spreading to the DOM). If the component needs server data (e.g. products for a carousel), export a `loader({ componentData, context })` and optionally a `fallback` component; the registry calls the loader during `collectComponentDataPromises` and passes resolved data as the `data` prop.
+- **Use the MCP tool `storefront_next_design_decorator`** to generate decorators instead of writing them by hand. Example components: `components/hero/index.tsx`, `components/content-card/index.tsx`, `components/product-carousel/index.tsx`.
+
+### After changes
+
+- **Rebuild the app** so the static registry (`lib/static-registry.ts`) is regenerated by the staticRegistry Vite plugin. Do not edit the static registry by hand.
+
+### Design mode
+
+- **Edit** and **Preview** mode are detected from the request via `isDesignModeActive(request)` and `isPreviewModeActive(request)` from `@salesforce/storefront-next-runtime/design/mode`. The root layout exposes `pageDesignerMode` in loader data (`'EDIT' | 'PREVIEW' | undefined`) so the tree can adapt (e.g. show outlines, disable interactions) when running inside Page Designer.
+
+
+## MCP tools (recommended)
+
+Use the **B2C DX MCP server** for Page Designer work instead of hand-writing decorators and metadata. Configure the B2C DX MCP server in your IDE (e.g. in MCP settings) so these tools are available.
+
+### 1. `storefront_next_design_decorator` (STOREFRONTNEXT toolset)
+
+Adds Page Designer decorators to an existing React component so it can be used in Business Manager. The tool analyzes the component, picks suitable props, infers types (e.g. `*Url`/`*Link` → url, `*Image` → image, `is*`/`show*` → boolean), and generates `@Component('typeId', { name, description })`, `@AttributeDefinition()` on a metadata class, and optionally `@RegionDefinition([...])` for nested regions. It skips complex or UI-only props (e.g. className, style, callbacks).
+
+- **Auto mode** (fast): Ask in your IDE: *"Add Page Designer support to [ComponentName] with autoMode"*. The tool runs in one turn with no prompts.
+- **Interactive mode** (control): Ask *"Add Page Designer support to [ComponentName]"* and answer questions about typeId, which props to expose, types, and optional nested regions.
+
+### 2. `storefront_next_generate_page_designer_metadata` (STOREFRONTNEXT toolset)
+
+Generates Page Designer metadata JSON from decorated components, page types, and aspects. Writes files under the cartridge experience folder (e.g. `cartridges/app_storefrontnext_base/cartridge/experience/`). Use after adding or changing decorators so Business Manager has up-to-date component and page-type definitions.
+
+- **Full scan**: Run with no file list to process the whole project.
+- **Incremental**: Pass specific file paths to regenerate only those components.
+- **Dry run**: Use `dryRun: true` to see what would be generated without writing files.
+
+### 3. `cartridge_deploy` (CARTRIDGES toolset)
+
+Packages the cartridge, uploads it to Commerce Cloud via WebDAV, and unpacks it on the server. Requires Commerce Cloud credentials (e.g. `dw.json` or explicit config). Use after generating metadata so the new/updated metadata is available in Business Manager.
+
+### Typical workflow
+
+1. **`storefront_next_design_decorator`** — Add decorators to the component (use autoMode for a quick first pass).
+2. **`storefront_next_generate_page_designer_metadata`** — Generate metadata JSON so the component and regions appear in Page Designer.
+3. **`cartridge_deploy`** — Deploy to Commerce Cloud so merchants can use the component in Business Manager.
+
+## Best Practices
+
+1. **Keep loaders synchronous**: Return promises for Page Designer pages to enable streaming
+2. **Use registry for components**: Register all Page Designer components with proper `typeId`
+3. **Handle design mode**: Adapt UI when `pageDesignerMode` is `'EDIT'` or `'PREVIEW'`
+4. **Rebuild after registry changes**: Static registry is generated at build time
+5. **Use MCP tools**: Leverage `storefront_next_design_decorator` and `storefront_next_generate_page_designer_metadata` for faster development
+
+**Reference:** See README.md for complete Page Designer documentation and MCP tool setup.

package/content/performance.md

@@ -0,0 +1,80 @@
+# Performance Optimization
+
+## Bundle Size Limits
+
+The application enforces strict bundle size limits defined in `package.json` under the `bundlesize` configuration. Refer to `package.json` for the complete list of limits.
+
+**Check bundle size:**
+
+```bash
+pnpm bundlesize:test      # Verify limits
+pnpm bundlesize:analyze   # Analyze composition
+```
+
+## Built-in Metrics
+
+Enable in `config.server.ts`:
+
+```typescript
+{
+    performance: {
+        metrics: {
+            serverPerformanceMetricsEnabled: true,
+            clientPerformanceMetricsEnabled: true,
+            serverTimingHeaderEnabled: false  // Debug only
+        }
+    }
+}
+```
+
+Tracks:
+
+- SSR operations and rendering time
+- SCAPI API calls with parallelization
+- Authentication operations
+- Client-side navigations
+
+## Best Practices
+
+### 1. Parallel Data Fetching
+
+**Key principle:** Return all promises simultaneously in loaders to enable parallel requests. Avoid sequential `await` calls.
+
+**Reference:** See `data-fetching` section for detailed parallel vs sequential patterns and code examples.
+
+### 2. Image Optimization
+
+Use the `DynamicImage` component with WebP format:
+
+```typescript
+import { DynamicImage } from '@/components/dynamic-image';
+
+<DynamicImage
+    src={product.image.link}
+    alt={product.image.alt}
+    width={400}
+    height={400}
+    format="webp"  // Default format
+/>
+```
+
+### 3. Progressive Streaming
+
+**Key principle:** Use synchronous loaders returning promises to enable progressive streaming. Await only critical data, stream the rest.
+
+**Reference:** See `data-fetching` section for detailed streaming patterns including mixed strategies (awaited + streamed).
+
+### 4. Lighthouse Audits
+
+Monitor performance metrics:
+
+- Preload critical CSS
+- Use WebP images by default
+- Lazy load below-the-fold content
+- Optimize font loading
+
+```bash
+pnpm lighthouse:ci   # Run Lighthouse CI
+```
+
+**Reference:** See README-PERFORMANCE.md for complete performance optimization documentation.

package/content/pitfalls.md

@@ -0,0 +1,141 @@
+# Common Pitfalls
+
+## 1. Using Client Loaders/Actions
+
+```typescript
+// ❌ NEVER USE - Client loaders are not permitted
+export function clientLoader() { ... }
+
+// ❌ NEVER USE - Client actions are not permitted  
+export function clientAction() { ... }
+
+// ✅ REQUIRED - Server-only data loading
+export function loader({ context }: LoaderFunctionArgs) {
+    const clients = createApiClients(context);
+    return { product: clients.shopperProducts.getProduct({...}) };
+}
+
+// ✅ REQUIRED - Server-only actions
+export async function action({ request, context }: ActionFunctionArgs) {
+    const clients = createApiClients(context);
+    // Handle mutation on server
+}
+```
+
+**Decision tree:**
+
+```text
+Need data for page render?
+└─ Use server `loader`
+
+Need to handle mutations (form submissions, cart updates)?
+└─ Use server `action`
+
+Need on-demand fetching after page load?
+└─ Use `useScapiFetcher` (search, modals, infinite scroll)
+```
+
+**Key Point:** ALL SCAPI requests happen on the server:
+- `loader`: Runs on server, SCAPI direct (prod) or proxied (dev)
+- `action`: Runs on server, handles mutations securely
+- `useScapiFetcher`: Triggers server route that calls SCAPI
+
+## 2. Module-Level i18n in Schemas
+
+```typescript
+// ❌ RACE CONDITION
+const schema = z.object({
+  email: z.string().email(t('error')),
+});
+
+// ✅ FACTORY PATTERN
+export const createSchema = (t: TFunction) => {
+  return z.object({
+    email: z.string().email(t('error')),
+  });
+};
+```
+
+## 3. Using Async Loaders (Blocks Page Transitions)
+
+```typescript
+// ❌ BLOCKS PAGE TRANSITIONS - Async loader with await
+export async function loader({ context }: LoaderFunctionArgs) {
+    const product = await fetchProduct();    // Blocks!
+    const reviews = await fetchReviews();    // Blocks!
+    return { product, reviews };
+}
+
+// ✅ NON-BLOCKING - Synchronous loader returning promises
+export function loader({ context }: LoaderFunctionArgs): PageData {
+    return {
+        product: fetchProduct(),    // Streams progressively
+        reviews: fetchReviews(),    // Streams progressively
+    };
+}
+```
+
+**Key insight:** Defining loaders as `async` and using `await` causes the entire page transition to block until all data resolves. Use synchronous loaders returning promises for streaming.
+
+**Reference:** See `data-fetching` section for comprehensive loader patterns including mixed strategies (awaited + streamed).
+
+## 4. Modifying shadcn/ui
+
+```typescript
+// ❌ NEVER modify src/components/ui/
+
+// ✅ Create wrapper
+import { Button } from '@/components/ui/button';
+export function MyButton(props) {
+    return <Button {...props} className="custom" />;
+}
+```
+
+## 5. Missing Namespace in i18n
+
+```typescript
+// ❌ MISSING NAMESPACE
+const {t} = useTranslation();
+t('title'); // Won't work
+
+// ✅ USE NAMESPACE
+const {t} = useTranslation('product');
+t('title'); // Works
+```
+
+## 6. Not Using Context in Server Loaders
+
+```typescript
+// ❌ MISSING CONTEXT
+export function loader() {
+    const config = getConfig(); // Wrong!
+}
+
+// ✅ PASS CONTEXT
+export function loader({ context }: LoaderFunctionArgs) {
+    const config = getConfig(context); // Correct
+}
+```
+
+## 7. Forgetting to Namespace i18n Keys
+
+```typescript
+// ❌ MISSING NAMESPACE
+const { t } = useTranslation();
+t('title'); // Won't work without namespace
+
+// ✅ USE NAMESPACE
+const { t } = useTranslation('product');
+t('title'); // Works
+
+// OR
+const { t } = getTranslation();
+t('product:title'); // Works
+```
+
+## 8. Using JavaScript Files
+
+```text
+❌ .js, .jsx, .mjs, .cjs files are BLOCKED
+✅ Use .ts, .tsx files only
+```

package/content/quick-reference.md

@@ -0,0 +1,226 @@
+# Storefront Next - Development Guidelines (Quick Reference)
+
+⚠️ **READ THESE CRITICAL RULES BEFORE WRITING ANY CODE** ⚠️
+
+## 🏗️ Architecture Overview
+
+**Server-rendered SPA** built on React Server Components:
+- **React Router 7** in framework mode
+- **Managed Runtime (MRT)** as data orchestration layer
+- **All SCAPI requests execute on MRT server** (both SSR and client-side navigation)
+
+**Key Point**: Client-side routing does NOT mean client-side data fetching. Loaders always run on the server.
+
+---
+
+## 🚨 Non-Negotiable Rules
+
+### 1. Server-Only Data Loading
+
+✅ **REQUIRED**: Use server `loader` for all SCAPI data fetching
+
+```typescript
+export function loader({ context }: LoaderFunctionArgs): PageData {
+    const clients = createApiClients(context);
+    return {
+        product: clients.shopperProducts.getProduct({...}),  // Promise - streams
+        reviews: clients.shopperProducts.getReviews({...}),  // Promise - streams
+    };
+}
+```
+
+**Why?** Keeps SCAPI requests on MRT server for security, performance, and bundle size.
+
+### 2. Synchronous Loaders (Not Async)
+
+✅ **CRITICAL**: Loaders must be **synchronous functions that return promises**, NOT async functions.
+
+```typescript
+// ✅ CORRECT - Enables streaming
+export function loader({ context }: LoaderFunctionArgs): PageData {
+    const clients = createApiClients(context);
+    return {
+        product: clients.shopperProducts.getProduct({...}),  // Promise - streams
+    };
+}
+
+// ❌ AVOID - Blocks page transitions
+export async function loader({ context }: LoaderFunctionArgs) {
+    const product = await clients.shopperProducts.getProduct({...}); // Blocks!
+    return { product };
+}
+```
+
+**Why?** Async loaders block page transitions. Synchronous loaders enable progressive streaming.
+
+### 3. TypeScript-Only
+
+✅ **REQUIRED**: Use `.ts` and `.tsx` file extensions  
+❌ **BLOCKED**: `.js`, `.jsx`, `.mjs`, `.cjs` files are forbidden by ESLint
+
+### 4. Use createPage() HOC
+
+✅ **RECOMMENDED**: Use `createPage()` for standardized page patterns
+
+```typescript
+import { createPage } from '@/components/create-page';
+
+const ProductPage = createPage({
+    component: ProductView,
+    fallback: <ProductSkeleton />
+});
+
+export default ProductPage;
+```
+
+### 5. Tailwind CSS 4 Only
+
+✅ **REQUIRED**: Use Tailwind utility classes only  
+❌ **BLOCKED**: No inline styles (`style={{...}}`), no CSS modules, no separate CSS files
+
+```typescript
+// ✅ CORRECT - Tailwind utilities
+<div className="rounded-lg border border-border bg-card p-4">
+    <h2 className="text-lg font-semibold text-card-foreground">
+        {product.name}
+    </h2>
+</div>
+
+// ❌ AVOID - Inline styles
+<div style={{ padding: '1rem' }}>
+
+// ❌ AVOID - CSS modules
+import styles from './product-card.module.css';
+```
+
+**Why?** Consistent styling approach, better performance, automatic dark mode support via theme variables.
+
+---
+
+## 📋 Quick Patterns
+
+### Data Fetching
+
+```typescript
+import { createApiClients } from '@/lib/api-clients';
+
+export function loader({ context }: LoaderFunctionArgs): PageData {
+    const clients = createApiClients(context);
+    return {
+        product: clients.shopperProducts.getProduct({...}),
+        reviews: clients.shopperProducts.getReviews({...}),
+    };
+}
+```
+
+**See `data-fetching` section for:** loaders, actions, useScapiFetcher, parallel requests, data flow
+
+### Authentication
+
+```typescript
+import { getAuth } from '@/middlewares/auth.server';
+
+export function loader({ context }: LoaderFunctionArgs) {
+    const auth = getAuth(context);
+    return { 
+        isGuest: auth.userType === 'guest',
+        customerId: auth.customer_id 
+    };
+}
+```
+
+**See `auth` section for:** cookie architecture, client usage, token management
+
+### Configuration
+
+```typescript
+// Components
+import { useConfig } from '@/config';
+const config = useConfig();
+
+// Loaders/Actions
+import { getConfig } from '@/config';
+const config = getConfig(context);
+```
+
+**See `config` section for:** adding config, environment variables, security
+
+### Internationalization
+
+```typescript
+// Components
+import { useTranslation } from 'react-i18next';
+const { t } = useTranslation('product');
+
+// Loaders/Actions
+import { getTranslation } from '@/lib/i18next';
+const { t } = getTranslation(context);
+```
+
+**See `i18n` section for:** validation schemas (factory pattern), language switching, extensions
+
+### Components
+
+```typescript
+// Suspense boundaries
+import { Suspense } from 'react';
+import { Await } from 'react-router';
+
+<Suspense fallback={<ProductSkeleton />}>
+    <Await resolve={product}>
+        {(data) => <ProductHeader product={data} />}
+    </Await>
+</Suspense>
+```
+
+**See `components` section for:** createPage HOC, file organization, best practices
+
+### Styling
+
+```typescript
+// Tailwind utility classes
+<div className="bg-background text-foreground border-border">
+    <button className="bg-primary text-primary-foreground rounded-md px-4 py-2">
+        Click me
+    </button>
+</div>
+
+// shadcn/ui: Add via npx shadcn@latest add <component-name>
+import { Button } from '@/components/ui/button';
+import { Card } from '@/components/ui/card';
+```
+
+**See `styling` section for:** Tailwind CSS 4 rules, Shadcn/ui components, dark mode, responsive design
+
+---
+
+## 🔍 Get Detailed Guidelines
+
+Use the `storefront_next_development_guidelines` MCP tool with specific sections:
+
+```json
+{
+  "sections": ["data-fetching", "components", "testing"]
+}
+```
+
+**Available sections:**
+- `data-fetching` - Loaders, actions, useScapiFetcher, data flow
+- `components` - createPage HOC, Suspense, file organization
+- `styling` - Tailwind CSS 4, Shadcn/ui, styling guidelines
+- `testing` - Vitest, Storybook, coverage requirements
+- `auth` - Authentication and session management
+- `config` - Configuration system
+- `i18n` - Internationalization patterns
+- `state-management` - Client-side state with Zustand
+- `page-designer` - Page Designer integration
+- `performance` - Optimization techniques
+- `extensions` - Extension development
+- `pitfalls` - Common mistakes to avoid
+
+---
+
+**When in doubt:**
+1. Check existing code for similar examples
+2. Use the MCP tool to get detailed section guidance
+3. Follow architectural principles: server-only, streaming, TypeScript

package/content/state-management.md

@@ -0,0 +1,75 @@
+# Client-Side State Management
+
+## Zustand Store Pattern
+
+Storefront Next uses Zustand for client-side state (basket, wishlist):
+
+```typescript
+// src/middlewares/basket.client.ts
+import {create} from 'zustand';
+
+interface BasketStore {
+  basket: Basket | null;
+  setBasket: (basket: Basket | null) => void;
+  clearBasket: () => void;
+}
+
+export const useBasketStore = create<BasketStore>((set) => ({
+  basket: null,
+  setBasket: (basket) => set({basket}),
+  clearBasket: () => set({basket: null}),
+}));
+```
+
+## Context Integration
+
+Access Zustand state via context helpers:
+
+```typescript
+import { getBasket, updateBasket } from '@/middlewares/basket.client';
+
+// In clientLoader
+export const clientLoader: ClientLoaderFunction = ({ context }) => {
+    const basket = getBasket(context);
+    return { basket, itemCount: basket?.productItems?.length ?? 0 };
+};
+
+// In components
+function CartIcon() {
+    const basket = getBasket(context);
+    return <Badge count={basket?.productItems?.length ?? 0} />;
+}
+```
+
+## Update Pattern
+
+After mutations, update the store:
+
+```typescript
+export async function clientAction({request, context}: ActionFunctionArgs) {
+  const formData = await request.formData();
+  const productId = formData.get('productId') as string;
+
+  const basket = getBasket(context);
+  const clients = createApiClients(context);
+
+  const {data: updatedBasket} = await clients.shopperBasketsV2.addItemToBasket({
+    params: {path: {basketId: basket.basketId}},
+    body: [{productId, quantity: 1}],
+  });
+
+  // Update Zustand store
+  updateBasket(context, updatedBasket);
+
+  return Response.json({success: true, basket: updatedBasket});
+}
+```
+
+## Best Practices
+
+1. **Use for ephemeral client state**: Shopping cart, UI state, temporary selections
+2. **Don't duplicate server state**: Prefer React Router loaders for server data
+3. **Keep stores focused**: Separate stores for basket, wishlist, etc.
+4. **Sync with server**: Update store after successful mutations
+
+For full documentation on client-side state management patterns, see the Zustand documentation and React Router state management patterns.

package/content/styling.md

@@ -0,0 +1,51 @@
+# Styling Guidelines
+
+## Rules
+
+- ✅ **Use Tailwind utility classes** in component JSX
+- ✅ **Use `cn()` utility** for conditional classes (`import { cn } from '@/lib/utils'`)
+- ✅ **Follow mobile-first** responsive patterns (`md:`, `lg:` breakpoints)
+- ❌ **NO inline styles** (`style={{...}}`)
+- ❌ **NO CSS modules** (`.module.css` files)
+- ❌ **NO separate CSS files** for component styles
+- ✅ **Custom CSS** only in `src/app.css` for global styles and theme configuration
+
+## Shadcn/ui Components
+
+**Adding components:**
+
+```bash
+npx shadcn@latest add <component-name>
+```
+
+**Rules:**
+
+- ✅ **DO** customize components by editing files in `src/components/ui/`
+- ❌ **DON'T** create custom components inside `src/components/ui/`
+- ❌ **DON'T** manually copy components (use CLI instead)
+
+## Dark Mode
+
+Dark mode is supported via CSS variables and the `.dark` class. Theme variables automatically adapt:
+
+```typescript
+<div className="bg-background text-foreground border-border">
+    <button className="bg-primary text-primary-foreground">
+        Click me
+    </button>
+</div>
+```
+
+## Responsive Design
+
+Follow mobile-first responsive design:
+
+```typescript
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+    {/* Content */}
+</div>
+```
+
+---
+
+**Reference:** See [README-UI-STYLING.md](README-UI-STYLING.md) for complete UI and styling documentation.