Integrate Page Designer with PWA Kit

With Page Designer, you can create reusable page types and component types for your Progressive Web App (PWA) Kit site. Use the no-code Page Designer visual editor in Business Manager to design, schedule, and publish Page Designer pages for your site. When integrated with a PWA Kit site, Page Designer enables the rendering of dynamic, responsive pages that use React components.

This guide explains how to configure PWA Kit so that your site can show Page Designer pages.

Before running the commands in this topic, replace any placeholders with actual values. Placeholders have this format: $PLACEHOLDER.

To integrate Page Designer with a PWA Kit site:

• Build your site with either of these implementations:

  • Composable Storefront (PWA Kit version 2.7.0 or later) for your whole site with usage of the Retail React app template
  • A phased headless rollout (Storefront Reference Architecture - SFRA and PWA Kit version 2.7.0 or later with usage of the Retail React app template)

• Create or update a SLAS public or private client. Follow the steps in Create a SLAS Client or use the registerClient API endpoint.

  • In the Scopes field, include this scope: sfcc.shopper-experience.

    A SLAS private client offers several advantages over a public client. See Use a SLAS Private Client.

• Get a SLAS admin token.

• MRT Admin Permission: To configure the connected MRT environment in Business Manager and use headless Page Designer features, merchants need the MRT Admin permission in Account Manager.

• Configure your MRT environment URL in Business Manager, in Administration > Sites > Manage Sites > Your Site > MRT Configuration. Page Designer uses this URL to render your PWA Kit storefront for live editing.

• Single MRT Environment: Each Business Manager site can only have one MRT environment configured. Multiple MRT environments pointing to the same Business Manager site (n assignment) isn't supported.

• Create your Page Designer pages in the Page Designer visual editor. See Create a Page Using the Page Designer Visual Editor.

• Required for all metadata types: Add arch_type: "headless" to all Page Designer metadata files—pages, components, and aspect types (PDP, PLP, Search)—for headless rendering to work correctly. Without this field, Business Manager expects ISML components.
• No ISML required: With headless Page Designer (arch_type: "headless"), you only need React components, not ISML templates. This change is a major advantage, simplifying development and freeing you from maintaining parallel ISML and React implementations.
• No custom JavaScript in metadata: Pages and components marked as arch_type: "headless" don't run custom JavaScript. Only the page and component metadata (JSON) is evaluated—custom scripts are ignored. You implement all storefront logic in your PWA Kit React code—an intentional architectural change to separate concerns between the storefront (PWA Kit) and server (B2C Commerce).
• You define your components as pure React components with metadata in JSON format, specifying the architecture type, attributes, and regions.
• For pages, you define metadata including the route path where the page is accessible.
• Make sure that component metadata matches your React component's props structure.

Understanding the Page Designer architecture helps you build better components and integrate them effectively into your PWA Kit site.

Page Designer uses a hierarchical architecture with three main concepts: pages, regions, and components.

A Page is the top-level container representing a complete web page. It contains:

• Page metadata including name, description, and route
• One or more Regions that organize content
• Architecture type set to "headless" for React-only rendering
• A route path that defines where the page is accessible

In PWA Kit, you fetch page data with the usePage() hook from @salesforce/commerce-sdk-react and render it with the <Page> component.

Page Metadata Example:

Key Fields:

• arch_type: "headless" - Enables React-only rendering without ISML (required for headless pages).
  • Set to "headless" for PWA Kit React rendering.
  • Set to "controller" or omit for traditional ISML rendering.
  • Supports hybrid storefronts with both ISML and headless pages, enabling incremental migration.
• route - Critical: URL path where the page is accessible. Page Designer uses this field to render your storefront in edit mode.
  • Static routes: "/" for homepage, "/about" for about page
  • Dynamic routes with parameters: "/product/:productId", "/category/:categoryId"
  • Important: Make sure route parameters (:productId, :categoryId) match the attribute IDs defined in the page's aspect type
  • Page Designer loads your PWA Kit storefront at this route when editing the page.
• region_definitions - Defines the content areas for this page.

How Page Designer Uses Routes:

When you edit a headless page in the Page Designer visual editor, Page Designer:

1. Reads the route field from the page metadata.
2. Loads your PWA Kit storefront URL (configured as the connected MRT environment in Business Manager).
3. Goes to the route (for example, /, /product/123, /category/mens).
4. Renders your React page in an iframe for live editing.
5. Uses arch_type: "headless" to identify which components are headless.

This means:

• No special page-viewer route needed - Pages render at their actual routes.
• Non-breaking change - ISML pages without arch_type: "headless" continue to work.
• Hybrid storefronts supported - Mix ISML and headless pages during migration.
• Accurate preview - See exactly what customers see on your PWA Kit site.

Routes in Page Types:

Different page types require different route configurations:

Dynamic Route Parameters:

For pages with dynamic routes (PDP, PLP), the route parameter name must match the attribute ID defined in the page's aspect type metadata:

In this example, the route parameter :productId matches the attribute definition id: "productId". When a merchant selects a product in Page Designer, the system uses this attribute to construct the correct URL for preview.

A Region is a logical content area within a page or component. Regions:

• Contain an ordered list of components.
• Are nestable within Layout components.
• Are identifiable by unique IDs (for example, 'main', 'header', 'sidebar').
• Can define maximum component limits and restrictions.

The <Region> component from @salesforce/commerce-sdk-react/components handles rendering regions and their child components.

Components are the building blocks of your page content. There are two types:

Leaf Components (Content Components):

• Render actual content (images, text, products, carousels).
• Do NOT contain nested regions.
• Have "region_definitions": [] in their metadata.
• Examples: ContentCard, Hero, ProductCarousel.
• Receive their configuration as props directly from Page Designer.

Layout Components (Container Components):

• Organize other components with visual layouts (grids, columns, tabs).
• Must contain one or more nested Regions to hold child components.
• Have populated "region_definitions" in their metadata.
• Use the <Region> component to render their nested content.
• Examples: Grid, Carousel (when used as a container).

Component Metadata Example (Leaf Component):

Component Metadata Example (Layout Component):

Key Fields:

• arch_type: "headless" - Required for React-only components (no ISML).
• group - Organizes components in Page Designer.
• region_definitions - Empty array for leaf components, populated for layout components.
• attribute_definitions - Props that will be passed to your React component.

Understanding how components are discovered, loaded, and rendered helps you debug issues and optimize performance:

1. Page Load: The <Page> component receives page data from the Shopper Experience API via usePage() hook.
2. Region Rendering: The <Page> component maps over its regions and renders each using the <Region> component.
3. Component Discovery: For each component in a region, the <Component> wrapper:
   • Looks up the React component in the registry using the component's typeId.
   • Lazy-loads the component if needed (triggers React Suspense).
   • Extracts component data from the Page Designer configuration.
4. Component Rendering: The resolved React component receives:
   • Props matching the attribute_definitions from metadata (title, image, etc.)
   • regions: Nested regions (for layout components only)
   • page: Reference to the full page object
   • regionId: ID of the parent region
   • designMetadata: Design mode metadata (for Page Designer editor integration)

The component registry dynamically loads Page Designer components on-demand using lazy imports. Instead of a simple mapping object, it uses a ComponentRegistry class that enables:

• Lazy loading: Components are only loaded when needed, reducing initial bundle size.
• Dynamic imports: Each component is registered with an importer function.
• Fallback support: Optional loading states during component load.
• Data loaders: Optional server/client data fetching functions hoisted to the page.

Registry Initialization Example:

How It Works:

1. Call initializeRegistry() once during app startup.
2. When a page renders, the registry checks if the component is loaded.
3. If not loaded, it calls the importer function (triggers React Suspense).
4. Subsequent uses of the same component are instant.

Key Benefits:

• Only components used on the page are downloaded.
• Initial page load is faster.
• Components are shared across pages (loaded one time and cached).
• Eliminates the manual management of imports in page files.

Layout components organize other components using visual layouts. They render nested regions to hold child components.

Here's an example of a layout component that shows content in a responsive grid:

Store the metadata in your cartridge at: cartridge/experience/components/{group}/{componentId}.json

• arch_type is "headless": This tells Business Manager no ISML component is needed.
• Receive regions and components prop: Layout components get an array of region objects and the parent component object.
• Map over regions: Each nested region is rendered using the <Region> component.
• Pass required props: Each <Region> needs:
  • regionId: The unique identifier for the region
  • component: The parent component object (the Region finds the region data from component.regions)
  • key: React key prop for list rendering
• Metadata region match: Make sure the region_definitions in your metadata match the regions your component expects.

Leaf components render actual content and do NOT contain nested regions. They're the "content" pieces that get placed inside layout components.

Here's an example of a leaf component that displays an image:

Store the metadata in your cartridge at: cartridge/experience/components/{group}/{componentId}.json

• arch_type is "headless": No ISML component needed.
• region_definitions is empty array: Leaf components don't have nested regions.
• Attributes match props: Each attribute_definition becomes a prop passed to your React component.
• Define PropTypes: Always define PropTypes to match your metadata attributes.
• Supported attribute types: string, text, markup, integer, boolean, product, category, file, page, image, url, enum, custom

The older PWA Kit Page Designer implementation required ISML components. This section describes how to migrate to the new headless metadata approach, which uses React components only.

The biggest win: You no longer need ISML components. With arch_type: "headless", you only maintain React components.

Add the @salesforce/storefront-next-runtime package to your project:

Update your package.json:

For each existing component in your cartridge, update the JSON metadata file to include arch_type: "headless":

Before (cartridge/experience/components/commerce_assets/photoTile.json):

After:

Required changes for each component:

• Add "arch_type": "headless".
• Add "region_definitions": [] for leaf components, or populate with regions for layout components.

For each existing page in your cartridge, update the JSON metadata to include arch_type and route:

Before (cartridge/experience/pages/homePage.json):

After:

Route examples:

• Homepage: "route": "/"
• Static pages: "route": "/about", "route": "/contact"
• Product pages: "route": "/product/:productId" (:productId matches the attribute ID in your aspect type)
• Category pages: "route": "/category/:categoryId" (:categoryId matches the attribute ID in your aspect type)

For each aspect type (PDP, PLP, Search), add arch_type:

Before (cartridge/experience/aspects/pdp.json):

After:

Replace the old manual component mapping with the new registry approach.

Remove the old mapping pattern from your page-viewer:

Create a registry file at app/page-designer/registry.js:

Update your page-viewer to use the registry:

Update your main _app/index.jsx to initialize the registry and wrap with PageDesignerProvider:

Key setup points:

1. Initialize registry at module level (outside the component) so components are available during SSR.
2. Pass usid from useUsid() hook to the provider for session tracking.
3. Detect mode from URL - Page Designer passes mode=EDIT or mode=PREVIEW as query parameters.
4. Always wrap with PageDesignerProvider - it handles both design mode and normal rendering.

Create app/components/page-designer-init/index.jsx to handle design mode behaviors:

Create app/hooks/use-global-anchor-block.js to prevent link navigation in design mode:

In app/components/_app/index.jsx, render PageDesignerInit inside the provider:

1. Deploy your updated cartridge with headless metadata to your SFCC instance.
2. Restart your PWA Kit development server:
3. Verify in Business Manager:
   • Go to Merchant Tools > Content > Components.
   • Your components appear with no ISML requirement.
4. Test page rendering:
   • Go to your pages (homepage, PDP, PLP).
   • Components render using the registry.
5. Test in Page Designer:
   • Open the Page Designer visual editor.
   • Edit a page - your PWA Kit site shows in the preview.
   • Drag components - changes show immediately.

Challenge: Custom JavaScript no longer runs Solution: Headless components (arch_type: "headless") do not run custom JavaScript from Page Designer metadata. Migrate all custom logic to your React components. This approach is intentional—it separates storefront logic (PWA Kit React) from content configuration (Business Manager JSON).

Example:

Challenge: Forgetting to set arch_type: "headless" Solution: Always include "arch_type": "headless" in your metadata. Otherwise, Business Manager expects ISML components.

Challenge: Metadata attributes don't match React props Solution: Ensure every attribute_definition id matches a prop name in your React component. Use PropTypes to validate.

Challenge: Component typeId mismatch Solution: The typeId format is {group}.{componentId}. In your registry, use the same format: 'odyssey_base.myComponent': MyComponent

Challenge: Layout component regions not rendering Solution: Ensure that your metadata includes region_definitions and your React component maps over the regions prop with <Region> components.

Challenge: Page route not working Solution: For page metadata, include the route field with the URL path (for example, "route": "/" for homepage).

Challenge: Region not found Solution: Verify regionId matches the region ID in your page data. For nested regions, pass component not page. Use errorElement prop to handle missing regions gracefully.

Challenge: Visual editing not working Solution: Ensure PageDesignerProvider wraps your content. Verify targetOrigin matches your Business Manager URL. Check browser console for postMessage errors.

The updated Page Designer implementation includes several new features for enhanced visual editing support.

Components now receive designMetadata with information for visual editing:

Components also receive additional props:

• component - The full component data object
• regionId - The parent region's ID

You don't need to use these props, but they're available if needed for custom behavior.

Use the usePageDesignerMode hook to conditionally render content based on design mode:

Or use the utility functions for checking outside of React components:

The Page component no longer requires a components prop. Components are now resolved via the registry.

The Region component API has changed to support nested regions in layout components:

New Region Props:

The Component is now internal and uses the registry. You don't interact with it directly.

Here's a consolidated before/after example showing the full transformation:

Before (Old API):

After (New API):

Follow these steps to set up Page Designer in a new PWA Kit project.

Create app/page-designer/registry.js to register your components with lazy loading:

Update app/components/_app/index.jsx to initialize Page Designer:

Create app/components/page-designer-init/index.jsx:

Create app/hooks/use-global-anchor-block.js:

With this setup:

1. Your existing routes work automatically - No special page-viewer route needed
2. Page Designer loads your actual routes - When you edit a page with "route": "/", Page Designer loads your homepage at /
3. Live editing - Changes in Page Designer's visual editor appear instantly in your PWA Kit storefront
4. Hybrid support - Mix headless and ISML pages during migration

Example: If you create a homepage with:

Page Designer:

• Loads your PWA Kit site's homepage (/).
• Renders it in an iframe for editing.
• Applies changes in real-time.

• GitHub: Page Designer Repo for PWA Kit
• Salesforce Help: Page Designer Pages