# 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.