@salesforce/b2c-dx-mcp 2.0.0 → 2.1.0

package/content/sfnext/extensions.md

@@ -1,80 +0,0 @@
-# Extension Development
-
-## Structure
-
-```
-src/extensions/my-extension/
-├── plugin-config.json    # Plugin configuration
-├── components/           # Extension components
-├── routes/              # Extension routes
-├── locales/             # Extension translations
-└── providers/           # Extension providers
-```
-
-## Plugin Configuration
-
-**Insert component into plugin point**:
-
-```json
-{
-  "components": [
-    {
-      "pluginId": "header.before.cart",
-      "path": "extensions/my-extension/components/badge.tsx",
-      "order": 0
-    }
-  ],
-  "contextProviders": [
-    {
-      "path": "extensions/my-extension/providers/my-provider.tsx",
-      "order": 0
-    }
-  ]
-}
-```
-
-## Extension Routes
-
-Files in `routes/` auto-register:
-
-```typescript
-// src/extensions/my-extension/routes/my-route.tsx
-export function loader() {
-    return { message: 'Hello' };
-}
-
-export default function MyRoute() {
-    const { message } = useLoaderData();
-    return <div>{message}</div>;
-}
-```
-
-## Extension Translations
-
-Auto-namespaced as `extPascalCase`:
-
-```
-src/extensions/my-extension/locales/
-├── en-US/translations.json
-└── it-IT/translations.json
-```
-
-```typescript
-const {t} = useTranslation('extMyExtension');
-t('welcome');
-```
-
-## Integration Markers
-
-```typescript
-// Single line
-/** @sfdc-extension-line SFDC_EXT_MY_FEATURE */
-import myFeature from '@extensions/my-feature';
-
-// Block
-{/* @sfdc-extension-block-start SFDC_EXT_MY_FEATURE */}
-<Link to="/my-feature">My Feature</Link>
-{/* @sfdc-extension-block-end SFDC_EXT_MY_FEATURE */}
-```
-
-For full documentation, read: src/extensions/README.md

package/content/sfnext/i18n.md

@@ -1,121 +0,0 @@
-# Internationalization (i18n)
-
-## Overview
-
-- **Server instance**: Has access to all translations for all languages
-- **Client instance**: Dynamically imports translations as JavaScript chunks
-- **Dual API**: `useTranslation()` for components, `getTranslation()` for everything else
-
-## Adding Translations
-
-**In `src/locales/{language}/translations.json`**:
-
-```json
-{
-  "product": {
-    "title": "Product Details",
-    "addToCart": "Add to Cart",
-    "greeting": "Hello, {{name}}!",
-    "itemCount": {
-      "zero": "No items",
-      "one": "{{count}} item",
-      "other": "{{count}} items"
-    }
-  }
-}
-```
-
-## Usage
-
-**2. Use in React components:**
-
-```typescript
-import { useTranslation } from 'react-i18next';
-
-export function ProductCard() {
-    const { t } = useTranslation('product');
-
-    return (
-        <div>
-            <h1>{t('title')}</h1>
-            <button>{t('addToCart')}</button>
-            <p>{t('greeting', { name: 'John' })}</p>
-            <p>{t('itemCount', { count: 5 })}</p>
-        </div>
-    );
-}
-```
-
-**3. Use in non-component code:**
-
-```typescript
-import { getTranslation } from '@/lib/i18next';
-
-// Client-side or utilities
-const { t } = getTranslation();
-const message = t('product:addToCart');
-
-// Server-side (loaders/actions)
-export function loader(args: LoaderFunctionArgs) {
-    const { t } = getTranslation(args.context);
-    return { title: t('product:title') };
-}
-```
-
-## Validation Schemas with Translations
-
-**CRITICAL**: Use factory pattern for Zod schemas to avoid race conditions:
-
-```typescript
-// ❌ WRONG - Module-level schema (race condition)
-export const schema = z.object({
-    email: z.string().email(t('validation:emailInvalid'))
-});
-
-// ✅ CORRECT - Factory function
-import type { TFunction } from 'i18next';
-
-export const createSchema = (t: TFunction) => {
-    return z.object({
-        email: z.string().email(t('validation:emailInvalid'))
-    });
-};
-
-// Usage in component
-import { useMemo } from 'react';
-import { useTranslation } from 'react-i18next';
-
-function MyForm() {
-    const { t } = useTranslation();
-    const schema = useMemo(() => createSchema(t), [t]);
-
-    const form = useForm({ resolver: zodResolver(schema) });
-}
-```
-
-## Language Switching
-
-```typescript
-import LocaleSwitcher from '@/components/locale-switcher';
-
-export function Footer() {
-    return <footer><LocaleSwitcher /></footer>;
-}
-```
-
-## Extension Translations
-
-Extensions use `extPascalCase` namespace:
-
-```
-src/extensions/my-extension/locales/
-├── en-US/translations.json
-└── it-IT/translations.json
-```
-
-```typescript
-const {t} = useTranslation('extMyExtension');
-t('welcome');
-```
-
-**Reference:** See README-I18N.md for complete internationalization documentation.

package/content/sfnext/page-designer.md

@@ -1,78 +0,0 @@
-# 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 `sfnext_add_page_designer_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. `sfnext_add_page_designer_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. `cartridge_deploy` (CARTRIDGES toolset)
-
-Packages the cartridge, uploads it to Commerce Cloud via WebDAV, and unpacks it on the server. **Run `pnpm generate:cartridge` or `pnpm build` before `cartridge_deploy`.** 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. **`sfnext_add_page_designer_decorator`** — Add decorators to the component (use autoMode for a quick first pass).
-2. **Rebuild** — The static registry is auto-generated at build time by the staticRegistry Vite plugin.
-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 `sfnext_add_page_designer_decorator` for faster development
-
-**Reference:** See README.md for complete Page Designer documentation and MCP tool setup.

package/content/sfnext/performance.md

@@ -1,80 +0,0 @@
-# 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/sfnext/pitfalls.md

@@ -1,141 +0,0 @@
-# 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
-```