Page Designer Integration with Storefront Next

Page Designer is a visual, drag-and-drop content management tool for B2C Commerce that business users use to create, schedule, and publish personalized storefront pages without extensive developer intervention. It provides a low-code environment where merchants can build engaging consumer experiences, such as homepages, campaign landing pages, and product highlights, by using a library of reusable functional components. Developers build the reusable components that merchants use.

In Storefront Next, developers build Page Designer components as React components instead of ISML templates. ISML pages and templates aren’t used in Storefront Next.

Developers build the underlying building blocks that business users later manipulate. To learn more about how to build reusable pages and components in Page Designer, see Page Designer Readme in GitHub.

The Page Designer system is built on these fundamental concepts that define how content is structured and rendered.

• Pages: Top-level containers fetched via the ShopperExperience API that serve as the foundation for the storefront experience.
• Regions: Named areas within a page or component that act as placeholders where components can be nested.
• Components: Reusable UI elements, such as heroes, carousels, and grids, that contain specific functional logic and styling.
• Component Data: Asynchronous data retrieved by component-specific loaders to populate the UI elements.

Page Designer components are React components that you can decorate with metadata. You can configure the metadata in Business Manager.

Every Page Designer component follows this structure.

1src/components/my-component/
2├── index.tsx          # Main component with decorators

Components use three decorators to define their metadata.

This code example defines a Hero Banner Page Designer component. @Component registers the banner, and @AttributeDefinition on HeroMetadata declares optional configurable fields, such as Title, Image, and CTA link, a call-to-action link. A fallback export renders a loading skeleton. The default export is the main Hero that shows the image, title, and optional CTA. You can configure the Hero Banner in Page Designer.

1// src/components/hero/index.tsx
2import { Component } from "@/lib/decorators/component";
3import { AttributeDefinition } from "@/lib/decorators/attribute-definition";
4
5@Component("hero", {
6  name: "Hero Banner",
7  group: "odyssey_base",
8  description: "Prominent banner section with title, image, and CTA",
9})
10export class HeroMetadata {
11  @AttributeDefinition({
12    name: "Title",
13    type: "string",
14    required: false,
15  })
16  title?: string;
17
18  @AttributeDefinition({
19    name: "Image",
20    type: "image",
21    required: false,
22  })
23  imageUrl?: string;
24
25  @AttributeDefinition({
26    name: "CTA Link",
27    type: "url",
28    required: false,
29  })
30  ctaLink?: string;
31}
32
33// Fallback component (shown while loading)
34export function fallback({ title }: Partial<HeroProps>) {
35  return (
36    <div className="h-64 bg-gray-200 animate-pulse">
37      {title && <span className="sr-only">{title}</span>}
38    </div>
39  );
40}
41
42// Main component (default export required)
43export default function Hero({ title, imageUrl, ctaLink, ctaText }: HeroProps) {
44  return (
45    <section className="hero">
46      <img src={imageUrl} alt={title} />
47      <h1>{title}</h1>
48      {ctaLink && <a href={ctaLink}>{ctaText}</a>}
49    </section>
50  );
51}

These attribute types are available for @AttributeDefinition.

We recommend that every Page Designer component exports a fallback function. The fallback skeleton is shown while the component loads.

1// Lightweight skeleton - no heavy logic
2export function fallback({ title }: Partial<MyComponentProps>) {
3  return (
4    <div className="h-48 bg-gray-200 animate-pulse rounded">
5      {title && <span className="sr-only">Loading {title}</span>}
6    </div>
7  );
8}

Best Practices:

• Keep fallbacks lightweight (no state, effects, or data fetching).
• Match the approximate dimensions of the real component.
• Use CSS animations for loading indication.

Export a loader object for components that need dynamic data.

This code example defines a ProductCarousel that gets its list from a dual loader. A server loader calls fetchProducts using component.data?.categoryId and returns products. The component loads data on the server only, therefore the client loader returns null. The component receives already-resolved data and title as props—no Promise handling in the component. It renders the title and a list of products as ProductCards.

1// Server-side data loading
2export const loader = {
3  server: async ({ component, request, context }) => {
4    // Fetch data on the server
5    const products = await fetchProducts(component.data?.categoryId);
6    return { products };
7  },
8  client: async ({ component, request }) => {
9    // Optional: Client-side data loading
10    return null;
11  },
12};
13
14export default function ProductCarousel({ data, title }: ProductCarouselProps) {
15  // `data` is already resolved - not a Promise!
16  return (
17    <div>
18      <h2>{title}</h2>
19      {data?.products.map((product) => (
20        <ProductCard key={product.id} product={product} />
21      ))}
22    </div>
23  );
24}

Key Points:

• The data prop is always resolved when your component receives it.
• The internal Component wrapper handles Promise resolution.
• Your fallback is shown while data loads.
• Multiple components load data in parallel.

Container components can define the regions where other components can be placed.

This code example defines a Grid Layout Page Designer component that acts as a container with two regions. @Component registers it and @RegionDefinition declares Main Content with up to 6 components, and Sidebar with up to 3 components. GridMetadata adds an optional Columns attribute. A fallback export renders a simple loading grid. The default Grid component renders a two-column layout and uses the Region component to render the nested content for main and sidebar. That way, you can place other components in each region in Page Designer.

1import { Component } from "@/lib/decorators/component";
2import { RegionDefinition } from "@/lib/decorators/region-definition";
3import { Region } from "@/components/region";
4
5@Component("grid", {
6  name: "Grid Layout",
7  group: "odyssey_base",
8  description: "A flexible grid container for arranging components",
9})
10@RegionDefinition([
11  {
12    id: "main",
13    name: "Main Content",
14    maxComponents: 6,
15  },
16  {
17    id: "sidebar",
18    name: "Sidebar",
19    maxComponents: 3,
20  },
21])
22export class GridMetadata {
23  @AttributeDefinition({
24    name: "Columns",
25    type: "integer",
26    defaultValue: 2,
27  })
28  columns?: number;
29}
30
31export function fallback() {
32  return <div className="grid gap-4 animate-pulse" />;
33}
34
35export default function Grid({ component, columns = 2 }: GridProps) {
36  return (
37    <div className={`grid grid-cols-${columns} gap-4`}>
38      <div className="col-span-1">
39        {/* Nested region - uses component mode */}
40        <Region component={component} regionId="main" />
41      </div>
42      <div className="col-span-1">
43        <Region component={component} regionId="sidebar" />
44      </div>
45    </div>
46  );
47}

These options are available for the region definition metadata.

1@RegionDefinition([
2    {
3        id: 'content',                    // Required: Unique region ID
4        name: 'Content Area',             // Required: Display name in Business Manager
5        maxComponents: 5,                 // Optional: Maximum components allowed
6        minComponents: 1,                 // Optional: Minimum components required
7        componentTypeInclusions: [        // Optional: Only allow these component types
8            'sfnext.hero',
9            'sfnext.productCarousel',
10        ],
11        componentTypeExclusions: [        // Optional: Disallow these component types
12            'sfnext.grid',                // Prevent nested grids
13        ],
14    },
15])

A Page is the route-level definition that defines where Page Designer content can be placed.

This code example defines a Category Page with @PageType and two page regions: banner and promoContent. The route loader loads page and category data via fetchPageWithComponentData. The page component renders, in order: the banner region (with a skeleton fallback), a fixed ProductGrid for the category, and the promoContent region. Banner and promo slots are configurable in Page Designer. The route’s category defines the product grid.

1// src/routes/category.$categoryId.tsx
2import { PageType } from "@/lib/decorators/page-type";
3import { RegionDefinition } from "@/lib/decorators/region-definition";
4import { Region } from "@/components/region";
5
6@PageType({
7  name: "Category Page",
8  description: "Category listing page with product grid",
9  supportedAspectTypes: ["category"],
10})
11@RegionDefinition([
12  {
13    id: "banner",
14    name: "Category Banner",
15    maxComponents: 1,
16  },
17  {
18    id: "promoContent",
19    name: "Promotional Content",
20    maxComponents: 3,
21  },
22])
23export class CategoryPageMetadata {}
24
25export async function loader({ params, context }: LoaderFunctionArgs) {
26  const page = await fetchPageWithComponentData({
27    pageId: "category",
28    categoryId: params.categoryId,
29  });
30
31  return { page };
32}
33
34export default function CategoryPage({ loaderData }: Route.ComponentProps) {
35  return (
36    <div>
37      {/* Page-level region */}
38      <Region page={loaderData.page} regionId="banner" fallbackElement={<BannerSkeleton />} />
39
40      {/* Main category content */}
41      <ProductGrid categoryId={loaderData.categoryId} />
42
43      {/* Additional promotional content */}
44      <Region page={loaderData.page} regionId="promoContent" />
45    </div>
46  );
47}

Use page mode for top-level regions.

1<Region
2  page={loaderData.page} // Page data from loader
3  regionId="main" // Region ID matching @RegionDefinition
4  fallbackElement={<Skeleton />} // Optional: Loading state
5  errorElement={<ErrorMessage />} // Optional: Error state
6/>

Use component mode for nested regions inside container components.

1<Region
2  component={component} // Component object (synchronous)
3  regionId="content" // Region ID
4/>

The build process automatically generates B2C Commerce cartridge metadata from your decorated components and pages.

1pnpm build

This runs pnpm generate:cartridge as part of the build process and does these steps.

1. Scans src/ for @Component and @PageType decorators.
2. Extracts metadata from decorators.
3. Generates JSON files in cartridges/app_storefrontnext_base/cartridge/experience/.

1pnpm generate:cartridge

1cartridges/app_storefrontnext_base/cartridge/experience/
2├── components/
3│   └── odyssey_base/
4│       ├── hero.json
5│       ├── productCarousel.json
6│       └── grid.json
7├── pages/
8│   ├── homePage.json
9│   ├── productDetailPage.json
10│   └── categoryPage.json
11└── aspects/
12    └── (aspect definitions)

Component metadata (hero.json):

1{
2  "name": "Hero Banner",
3  "description": "Prominent banner section with title, image, and CTA",
4  "group": "odyssey_base",
5  "arch_type": "headless",
6  "region_definitions": [],
7  "attribute_definition_groups": [
8    {
9      "id": "hero",
10      "name": "Hero Banner",
11      "attribute_definitions": [
12        {
13          "id": "title",
14          "name": "Title",
15          "type": "string",
16          "required": false
17        }
18      ]
19    }
20  ]
21}

Page metadata (homePage.json):

1{
2  "name": "Home Page",
3  "description": "Main landing page",
4  "arch_type": "headless",
5  "region_definitions": [
6    {
7      "id": "main",
8      "name": "Main Content Region",
9      "max_components": 5
10    }
11  ],
12  "supported_aspect_types": [],
13  "route": "/"
14}

• arch_type: "headless": All generated metadata includes arch_type: "headless". This flag tells Page Designer that the page or component is rendered by the headless storefront (Storefront Next) rather than by a B2C Commerce controller. When Page Designer opens a page marked as headless, it loads the Managed Runtime (MRT) storefront URL in the editor iframe instead of a classic B2C Commerce controller-based page. This behavior enables Page Designer to render and edit React components directly.
• route: Automatically extracted from your file-based routing structure (for example, src/routes/category.$categoryId.tsx → /category/:categoryId). When Page Designer loads a page, the {page_route} variable in the iframe URL is resolved using the route field from the page type metadata.
• Manual additions: If you must add metadata manually, place JSON files in the cartridges/ directory structure.

Deploy the generated cartridge to your B2C Commerce instance.

Create a dw.json file in the storefront-next-dev package directory.

1{
2  "hostname": "your-instance.demandware.net",
3  "username": "your-username",
4  "password": "your-password",
5  "code-version": "version1"
6}

To deploy the cartridge, run this command.

1pnpm push

The command:

1. Generates cartridge metadata if GENERATE_AND_DEPLOY_CARTRIDGE_ON_MRT_PUSH is enabled.
2. Deploys the cartridge to B2C Commerce via WebDAV.
3. Pushes the storefront bundle to Managed Runtime.

To deploy only the cartridge without pushing to Managed Runtime (MRT), use these commands.

1# Generate metadata
2pnpm generate:cartridge
3
4# Deploy to B2C Commerce
5sfnext deploy-cartridge --project-directory .

1. ZIP Creation: Cartridge directory is zipped.
2. Upload: ZIP uploaded to B2C Commerce via WebDAV.
3. Unzip: Archive extracted on the server.
4. Cleanup: Temporary ZIP file deleted.

1. Cartridge Path: Add app_storefrontnext_base to your site’s cartridge path in Business Manager.

   • Go to Administration > Sites > Manage Sites > [Your Site] > Settings.
   • Add app_storefrontnext_base to the cartridge path.

2. MRT Linking: Make sure that your MRT environment is linked to your B2C Commerce instance. The MRT environment is linked if the storefront was set up in Business Manager, or you can link it in MRT’s Environment Settings page. The MRT storefront URL in Page Designer is automatically configured when exactly one MRT environment is linked to the specific B2C Commerce instance and site ID. No manual URL configuration is required. Page Designer uses this URL to populate the headless_url object, (containing edit_url, preview_url, and info_url) that controls where the editor iframe points.

   If the Page Designer iframe appears blank, verify that your MRT environment is correctly linked to your B2C Commerce instance and site.

1. Go to Merchant Tools > Content > Page Designer.
2. Create a page or edit an existing one.
3. Select a page type that matches your Storefront Next page types.
4. Add components to regions using the visual editor.
5. Configure component attributes in the properties panel.
6. Publish the page.

You can assign pages to:

• Specific entities - A particular product, category, or content asset
• Default pages - Fallback for all entities of a type

When editing in Page Designer:

1. Business Manager reads the route from page metadata.
2. Loads your storefront in an iframe with the appropriate URL.
3. Shows live preview as you configure components.

For the storefront to load inside the Page Designer iframe, the frame-ancestors Content Security Policy directive must allow both 'self' and your Business Manager hostname (for example, https://your-instance.commercecloud.salesforce.com). The default value of 'self' isn’t sufficient. Extend the directive in config.server.ts. See Security Response Headers.

To preview a page in the context of a specific Customer Group or on a specific date:

1. Enable the feature toggle in Business Manager: Turn on the “Shopper Context” feature toggle in Business Manager.
2. Configure MRT environment variable: Set PUBLIC__app__features__shopperContext__enabled to true in your Managed Runtime environment.

• No live editing without saving: Changes made in the Page Designer properties panel aren’t reflected in the preview iframe in real time. You must save changes to see them in the preview.
• Hybrid storefronts — link builder restriction: In hybrid deployments (SFRA and Storefront Next running together), the Page Designer link builder can only link to pages within the same technology stack. Headless pages can link to other headless pages, and SFRA pages can link to other SFRA pages, but cross-stack linking isn’t supported.

Local development with Page Designer using localhost URLs isn’t supported. To test Page Designer integration, deploy your storefront to an MRT environment.

As a temporary workaround, use a local development cartridge to redirect Page Designer to your local server. Download the cartridge from Local Dev Cartridge (ZIP).

1. Deploy the cartridge to your B2C Commerce instance.
2. Add the cartridge to your Business Manager cartridge path.
3. In Business Manager, go to Administration > SF Next Local Dev.
4. Enter your local development URL (for example, http://localhost:3000).
5. Run the service worker.
6. Click Enable Headless URL Override.

Page Designer contains Storefront Next template pages that merchants can add and customize. Page Designer can connect to the storefront associated with a site. See Page Designer Content Management for Merchants.

If you’re migrating from Salesforce Storefront Reference Architecture (SFRA) to Storefront Next and use content slots, follow this workaround until the planned Embedded Content feature becomes available. See Migrate Content Slots from SFRA to Storefront Next.

j

Announcements

Choose Your B2C Commerce Storefront Type

B2C Commerce

SCAPI

Storefront Next

Get Started

Build and Customize Storefront Next

Agent Skills and the B2C DX MCP Server

Managed Runtime (MRT) Data Store

Customize Your Storefront

Deploy Storefront Next to Managed Runtime (MRT)

Modernized Storefront Experience in Storefront Next

Enhance Shopper Experience with Store Locator and In-Store Pickup

Shopper Agent for Storefront Next

Page Designer Integration with Storefront Next

Page Designer Content Management for Merchants

Manage Content for Site-Wide Regions with Content Blocks (Beta)

Migrate Content Slots from SFRA to Storefront Next

Configure Checkout for Storefront Next

Configure Address Autocomplete for Storefront Next

Configure Salesforce Payments for Storefront Next

Passwordless Login for Storefront Next

Email Verification for Storefront Next

Social Login for Storefront Next

Password Reset for Storefront Next

Limit Access to a Storefront Under Development

Extend Storefront Next with Features

Upgrade Customized Components

Environment Base Paths

Maintain Shopper Sessions Across Subdomains in Storefront Next

Hybrid Storefronts

Login and Registration Support

Login and Registration Support for Hybrid Storefront Next Storefronts

Deploy and Manage Storefront Next on Managed Runtime

Preview, Test, and Debug Storefront Next

Optimize the Performance of Storefront Next

Track Storefront Next Activity with Analytics

Migrate from PWA Kit to Storefront Next

CLI Reference

Composable Storefront

Storefront Reference Architecture (SFRA)

Commerce Apps ISV Developer Guide

B2C Commerce Solutions

B2C Commerce Release Notes

B2C Commerce Reference Information

Ask the Community