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.

• MRT Admin or User Permission: To use headless Page Designer features, merchants need one of the following permissions in Account Manager: Managed Runtime Admin (crm-org-admin), Managed Runtime User (crm-org-user), or Managed Runtime Service Admin (crm-service-admin). If you have one of these permissions and an MRT environment pointing to your B2C Commerce site, no additional manual configuration is needed. Starting with B2C Commerce version 26.6, these permissions will no longer be required.

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.

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.

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.

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.

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.

These options are available for the region definition metadata.

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.

Use page mode for top-level regions.

Use component mode for nested regions inside container components.

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

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

Component metadata (hero.json):

Page metadata (homePage.json):

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

To deploy the cartridge, run this command.

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

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.