sfnext-page-designer

What this skill does

# Page Designer Skill

This skill covers Page Designer integration in Storefront Next — building merchant-editable pages with React components, decorators, and the Shopper Experience API.

## Overview

Page Designer is Commerce Cloud's visual editor for merchants. In Storefront Next, page structure (regions, components, attributes) is fetched from the Shopper Experience API and rendered via a component registry and `<Region>` component.

| Concept | Role |
|---------|------|
| **Page** | Fetched in route loaders via `fetchPageFromLoader(args, { pageId })` |
| **Region** | Named area rendered with `<Region page={...} regionId="..." />` |
| **Component** | Content block with a `typeId` and attributes; registered in `@/lib/registry` |
| **Registry** | Static registry auto-generated by Vite plugin — do not edit by hand |

## Which Pages Use Page Designer

| Uses Page Designer | Does Not |
|--------------------|----------|
| Home (`homepage`), Category/PLP, Search, Product/PDP | Cart, Checkout, Account, Auth |

## Route Setup

### In the Loader

```typescript
import { fetchPageFromLoader, collectComponentDataPromises } from '@/lib/page-designer';

export function loader(args: LoaderFunctionArgs) {
    const pagePromise = fetchPageFromLoader(args, { pageId: 'homepage' });
    const componentData = collectComponentDataPromises(args, pagePromise);

    return {
        page: pagePromise,
        componentData,
    };
}
```

### In the Layout

```typescript
import { Region } from '@/components/region';

export default function HomePage({ loaderData: { page, componentData } }) {
    return (
        <div>
            <Region page={page} regionId="hero" componentData={componentData}
                fallbackElement={<HeroSkeleton />}
                errorElement={<RegionError />} />

            <Region page={page} regionId="content" componentData={componentData}
                fallbackElement={<ContentSkeleton />} />
        </div>
    );
}
```

## Component Setup

### Metadata Class with Decorators

```typescript
import { Component, AttributeDefinition, RegionDefinition } from '@salesforce/storefront-next-runtime/design';

@Component('hero-banner', {
    name: 'Hero Banner',
    description: 'Full-width banner with image and CTA'
})
class HeroBannerMeta {
    @AttributeDefinition({ type: 'image' })
    image: string;

    @AttributeDefinition()
    headline: string;

    @AttributeDefinition({ type: 'url' })
    ctaUrl: string;

    @AttributeDefinition()
    ctaText: string;

    @AttributeDefinition({ type: 'boolean' })
    fullWidth: boolean;
}
```

### React Component

```typescript
export default function HeroBanner({ image, headline, ctaUrl, ctaText, fullWidth }) {
    return (
        <div className={cn('relative', fullWidth && 'w-full')}>
            <DynamicImage src={image} alt={headline} />
            <h1>{headline}</h1>
            {ctaUrl && <a href={ctaUrl}>{ctaText}</a>}
        </div>
    );
}
```

See [Decorator Patterns Reference](references/DECORATOR-PATTERNS.md) for all decorator options.

### Components with Server Data

If a component needs server data (e.g., product carousel):

```typescript
// Export a loader for the component
export function loader({ componentData, context }) {
    const clients = createApiClients(context);
    return clients.shopperProducts.getProducts({
        params: { query: { ids: componentData.productIds } }
    }).then(({ data }) => data);
}

// Optional fallback during loading
export function fallback() {
    return <CarouselSkeleton />;
}

// Component receives data as prop
export default function ProductCarousel({ data, ...props }) {
    return <Carousel products={data.products} />;
}
```

See [Component Registry Reference](references/COMPONENT-REGISTRY.md) for registry details.

## Design Mode

Detect when running inside Page Designer:

```typescript
import { isDesignModeActive, isPreviewModeActive } from '@salesforce/storefront-next-runtime/design/mode';

// In loaders
const isDesignMode = isDesignModeActive(request);
const isPreview = isPreviewModeActive(request);

// Root layout exposes pageDesignerMode in loader data
// 'EDIT' | 'PREVIEW' | undefined
```

## MCP Tools

Use the B2C DX MCP server tools for Page Designer development:

1. **`storefront_next_page_designer_decorator`** — Adds decorators to components (auto mode or interactive)
2. **`storefront_next_generate_page_designer_metadata`** — Generates metadata JSON for Business Manager
3. **`cartridge_deploy`** — Deploys cartridge to Commerce Cloud

### Typical Workflow

1. Add decorators to component (use `storefront_next_page_designer_decorator` with autoMode)
2. Generate metadata JSON (`storefront_next_generate_page_designer_metadata`)
3. Deploy cartridge (`cartridge_deploy`)

## Best Practices

1. **Keep loaders synchronous** — Return promises for streaming
2. **Use registry** — Register components with proper `typeId`
3. **Handle design mode** — Adapt UI when `pageDesignerMode` is `'EDIT'` or `'PREVIEW'`
4. **Rebuild after changes** — Static registry regenerates at build time
5. **Use MCP tools** — Faster than hand-writing decorators and metadata

## Related Skills

- `storefront-next:sfnext-data-fetching` - Loader patterns for Page Designer routes
- `storefront-next:sfnext-components` - Component development patterns
- `b2c:b2c-page-designer` - Classic ISML Page Designer (NOT Storefront Next)

## Reference Documentation

- [Decorator Patterns Reference](references/DECORATOR-PATTERNS.md) - All decorator types and options
- [Component Registry Reference](references/COMPONENT-REGISTRY.md) - Registry setup and component loaders