Page Designer Skill Skill

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

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

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

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

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 for all decorator options.

Components with Server Data

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

// 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 for registry details.

Design Mode

Detect when running inside Page Designer:

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:

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

Typical Workflow

Add decorators to component (use storefront_next_page_designer_decorator with autoMode)
Generate metadata JSON (storefront_next_generate_page_designer_metadata)
Deploy cartridge (cartridge_deploy)

Best Practices

Keep loaders synchronous — Return promises for streaming
Use registry — Register components with proper typeId
Handle design mode — Adapt UI when pageDesignerMode is 'EDIT' or 'PREVIEW'
Rebuild after changes — Static registry regenerates at build time
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 - All decorator types and options
Component Registry Reference - Registry setup and component loaders

Agent Skills: Page Designer Skill

Install this agent skill to your local

Skill Files