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.

Prerequisites

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

Considerations

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.

Architecture Overview

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

Understanding Page Designer Components

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

Pages

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:

1{
2  "name": "Home Page",
3  "description": "Main landing page with hero carousel and featured products",
4  "arch_type": "headless",
5  "route": "/",
6  "region_definitions": [
7    {
8      "id": "headerbanner",
9      "name": "Header Banner Region",
10      "max_components": 3
11    },
12    {
13      "id": "main",
14      "name": "Main Content Region",
15      "max_components": 5
16    }
17  ]
18}

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:

Reads the route field from the page metadata.
Loads your PWA Kit storefront URL (configured as the connected MRT environment in Business Manager).
Goes to the route (for example, /, /product/123, /category/mens).
Renders your React page in an iframe for live editing.
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:

Page Type	Route Example	Description
Homepage	`"/"`	Static route for the main landing page
Content Page	`"/about"`, `"/contact"`	Static routes for informational pages
Product Detail Page (PDP)	`"/product/:productId"`	Dynamic route where `:productId` matches the attribute ID in the PDP aspect type
Category/Product Listing Page (PLP)	`"/category/:categoryId"`	Dynamic route where `:categoryId` matches the attribute ID in the PLP aspect type
Search Results Page	`"/search"`	Static route for search results

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:

1{
2  "name": "Product Detail Page",
3  "arch_type": "headless",
4  "route": "/product/:productId",
5  "attribute_definitions": [
6    {
7      "id": "productId",
8      "name": "Product ID",
9      "type": "product",
10      "required": true
11    }
12  ]
13}

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.

Regions

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

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):

1{
2  "name": "Content Card",
3  "description": "Flexible card component with optional image, title, description, and CTA",
4  "group": "odyssey_base",
5  "arch_type": "headless",
6  "region_definitions": [],
7  "attribute_definition_groups": [
8    {
9      "id": "contentCard",
10      "name": "Content Card",
11      "attribute_definitions": [
12        {
13          "id": "title",
14          "name": "Title",
15          "type": "string",
16          "required": false
17        },
18        {
19          "id": "imageUrl",
20          "name": "Image URL",
21          "type": "image",
22          "required": false
23        },
24        {
25          "id": "buttonText",
26          "name": "Button Text",
27          "type": "string",
28          "required": false
29        }
30      ]
31    }
32  ]
33}

Component Metadata Example (Layout Component):

1{
2  "name": "Grid",
3  "description": "A flexible grid layout component for organizing content in columns",
4  "group": "odyssey_base",
5  "arch_type": "headless",
6  "region_definitions": [
7    {
8      "id": "main",
9      "name": "Main"
10    }
11  ],
12  "attribute_definition_groups": [
13    {
14      "id": "grid",
15      "name": "Grid",
16      "attribute_definitions": [
17        {
18          "id": "columns",
19          "name": "Columns",
20          "type": "enum",
21          "required": false,
22          "values": ["1", "2", "3", "4", "5", "6"],
23          "default_value": "1"
24        }
25      ]
26    }
27  ]
28}

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.

Component Lifecycle and Data Flow

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

Page Load: The <Page> component receives page data from the Shopper Experience API via usePage() hook.
Region Rendering: The <Page> component maps over its regions and renders each using the <Region> component.
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.
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)

Component Registry

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:

1import {registry} from '@salesforce/commerce-sdk-react'
2
3export function initializeRegistry() {
4  // Register components with lazy imports
5  registry.registerImporter('pwa.contentCard', () => import('./components/content-card'))
6
7  registry.registerImporter('pwa.grid', () => import('./components/grid'))
8
9  // Register component with data loader and fallback
10  registry.registerImporter('pwa.productCarousel', () => import('./components/product-carousel'), {
11    loader: 'loader',
12    fallback: 'fallback'
13  })
14}

How It Works:

Call initializeRegistry() once during app startup.
When a page renders, the registry checks if the component is loaded.
If not loaded, it calls the importer function (triggers React Suspense).
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.

Building Layout Components

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

React Component Structure

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

1import React from 'react'
2import PropTypes from 'prop-types'
3import {SimpleGrid} from '@salesforce/retail-react-app/app/components/shared/ui'
4import {Region, regionPropType} from '@salesforce/commerce-sdk-react/components'
5
6/**
7 * This layout component displays its children in a 2 row x 1 column grid on mobile
8 * and a 1 row x 2 column grid on desktop.
9 */
10export const MobileGrid2r1c = ({regions, component}) => {
11  return (
12    <SimpleGrid columns={{base: 1, sm: 2}} gridGap={4}>
13      {regions.map((region) => (
14        <Region key={region.id} regionId={region.id} component={component} />
15      ))}
16    </SimpleGrid>
17  )
18}
19
20MobileGrid2r1c.propTypes = {
21  regions: PropTypes.arrayOf(regionPropType).isRequired,
22  component: PropTypes.object.isRequired
23}
24
25export default MobileGrid2r1c

Component Metadata

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

1{
2  "name": "Mobile Grid 2x1",
3  "description": "2 row x 1 column grid on mobile, 1 row x 2 column on desktop",
4  "group": "odyssey_base",
5  "arch_type": "headless",
6  "region_definitions": [
7    {
8      "id": "region1",
9      "name": "First Region"
10    },
11    {
12      "id": "region2",
13      "name": "Second Region"
14    }
15  ],
16  "attribute_definition_groups": []
17}

Key Points for Layout Components

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.

Building Leaf Components

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

React Component Structure

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

1import React from 'react'
2import PropTypes from 'prop-types'
3import {Box, Image} from '@salesforce/retail-react-app/app/components/shared/ui'
4
5/**
6 * Simple ImageTile component that displays a responsive image.
7 * This component can be placed inside any Layout component.
8 */
9export const ImageTile = ({image}) => {
10  return (
11    <Box className="image-tile">
12      <figure>
13        <picture>
14          <source srcSet={image?.src?.tablet} media="(min-width: 48em)" />
15          <source srcSet={image?.src?.desktop} media="(min-width: 64em)" />
16          <Image src={image?.src?.mobile || image?.url} alt={image?.alt} title={image?.alt} />
17        </picture>
18      </figure>
19    </Box>
20  )
21}
22
23ImageTile.propTypes = {
24  image: PropTypes.shape({
25    url: PropTypes.string,
26    alt: PropTypes.string,
27    src: PropTypes.shape({
28      mobile: PropTypes.string,
29      tablet: PropTypes.string,
30      desktop: PropTypes.string
31    })
32  })
33}
34
35export default ImageTile

Component Metadata

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

1{
2  "name": "Image Tile",
3  "description": "Simple image display component with responsive sources",
4  "group": "odyssey_base",
5  "arch_type": "headless",
6  "region_definitions": [],
7  "attribute_definition_groups": [
8    {
9      "id": "imageTile",
10      "name": "Image Tile",
11      "attribute_definitions": [
12        {
13          "id": "image",
14          "name": "Image",
15          "type": "image",
16          "required": true,
17          "description": "The image to display"
18        }
19      ]
20    }
21  ]
22}

Key Points for Leaf Components

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

Migrating from PWA Kit with ISML to Headless

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.

Understanding the Transformation

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

Aspect	Old PWA Kit Approach (with ISML)	New Approach
Component Definition	ISML + React components required	React components only
Metadata	Component metadata in JSON	Component metadata in JSON with `arch_type: "headless"`
Maintenance	Two implementations (ISML + React)	Single React implementation
Component Registry and Bundle Impact	Uses a mapping object that you configure manually to register components. All components loaded. No lazy loading.	Uses a dynamic registry to lazy load components. Only the used components are loaded (code splitting). Loading of non-critical components or resources is deferred until they’re needed.
Dependencies	`@salesforce/commerce-sdk-react`	Requires `@salesforce/storefront-next-runtime` in PWA Kit v3.17 or later, in addition to `@salesforce/commerce-sdk-react`.
Region or Component	Basic components	Enhanced `Region` and `Component` with design mode
Page Routing	Manual route setup	Automatic via `route` field in metadata
Server-Side Custom JavaScript	Executed at run time	No server-side JavaScript code. All functionality is implemented in React code.
Preview	Preview in Page Designer shows only ISML pages. Storefront Preview needed for PWA live preview.	Page Designer can preview PWA Kit storefront.

Migration Steps

Step 1: Install Required Dependency

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

1npm install @salesforce/storefront-next-runtime

Update your package.json:

1{
2  "dependencies": {
3    "@salesforce/storefront-next-runtime": "^VERSION",
4    "@salesforce/commerce-sdk-react": "^VERSION"
5  }
6}

Step 2: Update Component Metadata to Headless

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):

1{
2    "name": "Photo Tile",
3    "description": "Image display component",
4    "group": "commerce_assets",
5    "attribute_definition_groups": [...]
6}

After:

1{
2    "name": "Photo Tile",
3    "description": "Image display component",
4    "group": "commerce_assets",
5    "arch_type": "headless",
6    "region_definitions": [],
7    "attribute_definition_groups": [...]
8}

Required changes for each component:

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

Step 3: Update Page Metadata with Routes

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

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

1{
2    "name": "Home Page",
3    "description": "Main landing page",
4    "region_definitions": [...]
5}

After:

1{
2    "name": "Home Page",
3    "description": "Main landing page",
4    "arch_type": "headless",
5    "route": "/",
6    "region_definitions": [...]
7}

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)

Step 4: Update Aspect Type Metadata

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

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

1{
2    "name": "Product detail page",
3    "description": "A product detail page",
4    "attribute_definitions": [...],
5    "supported_object_types": ["product"]
6}

After:

1{
2    "name": "Product detail page",
3    "description": "A product detail page",
4    "arch_type": "headless",
5    "attribute_definitions": [...],
6    "supported_object_types": ["product"]
7}

Step 5: Migrate from Manual Mapping to Registry

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

Remove the old mapping pattern from your page-viewer:

1// OLD - Remove this
2const PAGEDESIGNER_TO_COMPONENT = {
3    'commerce_assets.photoTile': ImageTile,
4    'commerce_layouts.carousel': Carousel,
5    // ...
6}
7
8<Page page={page} components={PAGEDESIGNER_TO_COMPONENT} />

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

1import {registry} from '@salesforce/commerce-sdk-react'
2
3export function initializeRegistry() {
4  // Commerce Assets
5  registry.registerImporter('commerce_assets.imageTile', () => import('./assets/image-tile'))
6  registry.registerImporter('commerce_assets.imageAndText', () =>
7    import('./assets/image-with-text')
8  )
9  registry.registerImporter('commerce_assets.productTile', () => import('./assets/product-tile'))
10
11  // Commerce Layouts
12  registry.registerImporter('commerce_layouts.carousel', () => import('./layouts/carousel'))
13  registry.registerImporter('commerce_layouts.mobileGrid1r1c', () =>
14    import('./layouts/mobileGrid1r1c')
15  )
16  registry.registerImporter('commerce_layouts.mobileGrid2r1c', () =>
17    import('./layouts/mobileGrid2r1c')
18  )
19  registry.registerImporter('commerce_layouts.mobileGrid2r2c', () =>
20    import('./layouts/mobileGrid2r2c')
21  )
22  registry.registerImporter('commerce_layouts.mobileGrid2r3c', () =>
23    import('./layouts/mobileGrid2r3c')
24  )
25  registry.registerImporter('commerce_layouts.mobileGrid3r1c', () =>
26    import('./layouts/mobileGrid3r1c')
27  )
28  registry.registerImporter('commerce_layouts.mobileGrid3r2c', () =>
29    import('./layouts/mobileGrid3r2c')
30  )
31}

Update your page-viewer to use the registry:

1// app/pages/page-viewer/index.jsx
2import React from 'react'
3import {useParams} from 'react-router-dom'
4import {Box} from '@salesforce/retail-react-app/app/components/shared/ui'
5import {usePage} from '@salesforce/commerce-sdk-react'
6import {Page} from '@salesforce/commerce-sdk-react/components'
7import {HTTPError, HTTPNotFound} from '@salesforce/pwa-kit-react-sdk/ssr/universal/errors'
8
9const PageViewer = () => {
10  const {pageId} = useParams()
11  const {data: page, error} = usePage({parameters: {pageId}})
12
13  if (error) {
14    let ErrorClass = error.response?.status === 404 ? HTTPNotFound : HTTPError
15    throw new ErrorClass(error.response?.statusText)
16  }
17
18  return (
19    <Box layerStyle={'page'}>
20      {/* No components prop needed - registry handles it */}
21      <Page page={page} />
22    </Box>
23  )
24}
25
26export default PageViewer

Step 6: Set Up PageDesignerProvider in App Component

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

1// app/components/_app/index.jsx
2import {PageDesignerProvider} from '@salesforce/commerce-sdk-react/components'
3import {useUsid} from '@salesforce/commerce-sdk-react'
4import {initializeRegistry} from '@salesforce/retail-react-app/app/page-designer/registry'
5
6// Initialize registry synchronously at module load time so components are available during SSR
7initializeRegistry()
8
9const App = (props) => {
10  const {children} = props
11  const {usid} = useUsid()
12
13  // Detect Page Designer mode from URL
14  const pageDesignerMode = useMemo(() => {
15    const queryParams = location?.search || ''
16    if (queryParams.includes('mode=EDIT')) return 'EDIT'
17    if (queryParams.includes('mode=PREVIEW')) return 'PREVIEW'
18    return undefined
19  }, [])
20
21  return (
22    <Box className="sf-app">
23      {/* Other providers... */}
24      <PageDesignerProvider
25        clientId="pwa-kit-client"
26        targetOrigin="*"
27        usid={usid}
28        mode={pageDesignerMode}
29      >
30        {children}
31      </PageDesignerProvider>
32    </Box>
33  )
34}

Key setup points:

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

Step 7: Create PageDesignerInit Component

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

1import React, {useEffect} from 'react'
2import {Prompt} from 'react-router-dom'
3import {usePageDesignerMode} from '@salesforce/commerce-sdk-react/components'
4import {useGlobalAnchorBlock} from '@salesforce/retail-react-app/app/hooks/use-global-anchor-block'
5
6export function PageDesignerInit() {
7  const {isDesignMode} = usePageDesignerMode()
8
9  useGlobalAnchorBlock(isDesignMode)
10
11  useEffect(() => {
12    if (isDesignMode) {
13      void import('@salesforce/storefront-next-runtime/design/styles.css')
14    }
15  }, [isDesignMode])
16
17  return <Prompt when={isDesignMode} message={() => false} />
18}
19
20export default PageDesignerInit

Step 8: Create useGlobalAnchorBlock Hook

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

1import {useEffect} from 'react'
2
3export function useGlobalAnchorBlock(enabled = true) {
4  useEffect(() => {
5    if (typeof window === 'undefined' || !enabled) return
6
7    function preventAnchorClicks(event) {
8      const anchor = event.target.closest('a')
9      // Allow links with data-pd-allow-link attribute
10      if (anchor && !anchor.hasAttribute('data-pd-allow-link')) {
11        event.preventDefault()
12      }
13    }
14
15    document.addEventListener('click', preventAnchorClicks)
16    return () => document.removeEventListener('click', preventAnchorClicks)
17  }, [enabled])
18}

Step 9: Add PageDesignerInit to App

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

1import {PageDesignerInit} from '@salesforce/retail-react-app/app/components/page-designer-init'
2
3// Inside your App component's return:
4;<PageDesignerProvider
5  clientId="pwa-kit-client"
6  targetOrigin="*"
7  usid={usid}
8  mode={pageDesignerMode}
9>
10  <PageDesignerInit />
11  {children}
12</PageDesignerProvider>

Step 10: Deploy and Test

Deploy your updated cartridge with headless metadata to your SFCC instance.
Restart your PWA Kit development server:
1npm start
Verify in Business Manager:
- Go to Merchant Tools > Content > Components.
- Your components appear with no ISML requirement.
Test page rendering:
- Go to your pages (homepage, PDP, PLP).
- Components render using the registry.
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.

Common Migration Challenges

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:

1// OLD - Custom script in Page Designer (no longer executed)
2// This JavaScript will be IGNORED for headless components
3
4// NEW - Implement in your React component
5export const MyComponent = ({title, showDiscount}) => {
6  // All logic in React code
7  const displayPrice = showDiscount ? applyDiscount(price) : price
8  return <div>{displayPrice}</div>
9}

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.

New Features

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

Design Metadata

Components now receive designMetadata with information for visual editing:

1interface ComponentDesignMetadata {
2  id: string // Component instance ID
3  name?: string // Display name
4  isFragment: boolean // Is this a fragment?
5  isVisible: boolean // Is component visible?
6  isLocalized: boolean // Is component localized?
7}

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.

Design Mode Detection

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

1import {usePageDesignerMode} from '@salesforce/commerce-sdk-react/components'
2
3function MyComponent() {
4  const {isDesignMode, isPreviewMode} = usePageDesignerMode()
5
6  return (
7    <div>
8      {isDesignMode && <span>Editing mode</span>}
9      {/* ... */}
10    </div>
11  )
12}

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

1import {isDesignModeActive, isPreviewModeActive} from '@salesforce/commerce-sdk-react/components'
2
3if (isDesignModeActive()) {
4  // In design mode
5}

Page Component API

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

Before	After
`<Page page={data} components={map} />`	`<Page page={data} />`
Required `components` prop	Components from registry
Used `PageContext` internally	No context needed

Updated Region API

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

Before	After
`<Region region={regionObj} />`	`<Region component={comp} regionId="main" />`
Received region object directly	Finds region by ID from component
No fallback support	`fallbackElement` and `errorElement` props

New Region Props:

1// For page-level regions
2<Region page={page} regionId="main" fallbackElement={<Loading />} />
3
4// For nested regions in layout components
5<Region component={component} regionId="left" errorElement={<Error />} />

Component Registry API

1import {registry} from '@salesforce/commerce-sdk-react'
2
3// Register with lazy loading
4registry.registerImporter('typeId', () => import('./component'))
5
6// Register with fallback for loading state
7registry.registerImporter(
8  'typeId',
9  () => import('./component'),
10  () => import('./skeleton')
11)
12
13// Get a component
14const Component = registry.getComponent('typeId')
15
16// Preload a component
17await registry.preload('typeId')

Component (Internal)

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

Before	After
Used `usePageContext()` for component map	Uses `registry.getComponent()`
Wrapped in `<div className="component">`	No wrapper div
Synchronous rendering	Suspense-based lazy loading

Complete Migration Example

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

Before (Old API):

1// page-viewer.jsx
2import {Page} from '@salesforce/commerce-sdk-react/components'
3import ImageTile from './components/image-tile'
4import Banner from './components/banner'
5import TwoColumn from './components/two-column'
6
7const components = {
8  'commerce_assets.imageTile': ImageTile,
9  'commerce_assets.banner': Banner,
10  'commerce_layouts.twoColumn': TwoColumn
11}
12
13function PageViewer({pageData}) {
14  return <Page page={pageData} components={components} />
15}
16
17// two-column.jsx
18import {Region} from '@salesforce/commerce-sdk-react/components'
19
20function TwoColumn({regions}) {
21  return (
22    <div>
23      <Region region={regions.left} />
24      <Region region={regions.right} />
25    </div>
26  )
27}

After (New API):

1// registry.js
2import {registry} from '@salesforce/commerce-sdk-react'
3
4export function initializeRegistry() {
5  registry.registerImporter('commerce_assets.imageTile', () => import('./assets/image-tile'))
6  registry.registerImporter('commerce_assets.banner', () => import('./assets/banner'))
7  registry.registerImporter('commerce_layouts.twoColumn', () => import('./layouts/two-column'))
8}
9
10// _app/index.jsx
11import {initializeRegistry} from './page-designer/registry'
12initializeRegistry() // At module level, not in useEffect
13
14// page-viewer.jsx
15import {Page} from '@salesforce/commerce-sdk-react/components'
16
17function PageViewer({pageData}) {
18  return <Page page={pageData} />
19}
20
21// two-column.jsx
22import {Region} from '@salesforce/commerce-sdk-react/components'
23
24function TwoColumn({component}) {
25  return (
26    <div>
27      <Region component={component} regionId="left" />
28      <Region component={component} regionId="right" />
29    </div>
30  )
31}

Configure Page Designer

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

1. Install Dependencies

1npm install @salesforce/storefront-next-runtime

2. Create Component Registry

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

1import {registry} from '@salesforce/commerce-sdk-react'
2
3export function initializeRegistry() {
4  // Register layout components
5  registry.registerImporter('commerce_layouts.carousel', () => import('./layouts/carousel'))
6  registry.registerImporter('commerce_layouts.mobileGrid2r1c', () =>
7    import('./layouts/mobileGrid2r1c')
8  )
9
10  // Register asset components
11  registry.registerImporter('commerce_assets.photoTile', () => import('./assets/image-tile'))
12  registry.registerImporter('commerce_assets.imageAndText', () =>
13    import('./assets/image-with-text')
14  )
15
16  // Add all your Page Designer components here
17}

3. Set Up App Integration

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

1import {PageDesignerProvider} from '@salesforce/commerce-sdk-react/components'
2import {useUsid} from '@salesforce/commerce-sdk-react'
3import {initializeRegistry} from '@salesforce/retail-react-app/app/page-designer/registry'
4import {PageDesignerInit} from '@salesforce/retail-react-app/app/components/page-designer-init'
5
6// Initialize registry synchronously at module load time so components are available during SSR
7initializeRegistry()
8
9const App = (props) => {
10  const {children} = props
11  const {usid} = useUsid()
12
13  // Detect Page Designer mode from URL
14  const pageDesignerMode = useMemo(() => {
15    const queryParams = location?.search || ''
16    if (queryParams.includes('mode=EDIT')) return 'EDIT'
17    if (queryParams.includes('mode=PREVIEW')) return 'PREVIEW'
18    return undefined
19  }, [])
20
21  return (
22    <Box className="sf-app">
23      <PageDesignerProvider
24        clientId="pwa-kit-client"
25        targetOrigin="*"
26        usid={usid}
27        mode={pageDesignerMode}
28      >
29        <PageDesignerInit />
30        {children}
31      </PageDesignerProvider>
32    </Box>
33  )
34}

4. Create PageDesignerInit Component

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

1import React, {useEffect} from 'react'
2import {Prompt} from 'react-router-dom'
3import {usePageDesignerMode} from '@salesforce/commerce-sdk-react/components'
4import {useGlobalAnchorBlock} from '@salesforce/retail-react-app/app/hooks/use-global-anchor-block'
5
6export function PageDesignerInit() {
7  const {isDesignMode} = usePageDesignerMode()
8
9  // Block anchor navigation when in design mode
10  useGlobalAnchorBlock(isDesignMode)
11
12  // Load Page Designer styles only in design mode
13  useEffect(() => {
14    if (isDesignMode) {
15      void import('@salesforce/storefront-next-runtime/design/styles.css')
16    }
17  }, [isDesignMode])
18
19  // Block React Router navigation in design mode
20  return <Prompt when={isDesignMode} message={() => false} />
21}
22
23export default PageDesignerInit

5. Create useGlobalAnchorBlock Hook

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

1import {useEffect} from 'react'
2
3export function useGlobalAnchorBlock(enabled = true) {
4  useEffect(() => {
5    if (typeof window === 'undefined' || !enabled) return
6
7    function preventAnchorClicks(event) {
8      const anchor = event.target.closest('a')
9      // Allow links with data-pd-allow-link attribute
10      if (anchor && !anchor.hasAttribute('data-pd-allow-link')) {
11        event.preventDefault()
12      }
13    }
14
15    document.addEventListener('click', preventAnchorClicks)
16    return () => document.removeEventListener('click', preventAnchorClicks)
17  }, [enabled])
18}

6. How It Works

With this setup:

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

Example: If you create a homepage with:

1{
2    "name": "Home Page",
3    "arch_type": "headless",
4    "route": "/",
5    "region_definitions": [...]
6}

Page Designer:

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

Integrate Page Designer with PWA Kit

Prerequisites

Considerations

Architecture Overview

Understanding Page Designer Components

Pages

Regions

Components

Component Lifecycle and Data Flow

Component Registry

Building Layout Components

React Component Structure

Component Metadata

Key Points for Layout Components

Building Leaf Components

React Component Structure

Component Metadata

Key Points for Leaf Components

Migrating from PWA Kit with ISML to Headless

Understanding the Transformation

Migration Steps

Step 1: Install Required Dependency

Step 2: Update Component Metadata to Headless

Step 3: Update Page Metadata with Routes

Step 4: Update Aspect Type Metadata

Step 5: Migrate from Manual Mapping to Registry

Step 6: Set Up PageDesignerProvider in App Component

Step 7: Create PageDesignerInit Component

Step 8: Create useGlobalAnchorBlock Hook

Step 9: Add PageDesignerInit to App

Step 10: Deploy and Test

Common Migration Challenges

New Features

Design Metadata

Design Mode Detection

Page Component API

Updated Region API

Component Registry API

Component (Internal)

Complete Migration Example

Configure Page Designer

1. Install Dependencies

2. Create Component Registry

3. Set Up App Integration

4. Create PageDesignerInit Component

5. Create useGlobalAnchorBlock Hook

6. How It Works

See Also