Walkthrough: Registering an external React component

Current version: 22.0

XM Cloud includes a powerful component builder interface, which designers can use to configure, arrange, and style components. Content authors can then add components to site pages using the Pages application. The component builder lets you single-source your site content by building once and reusing while applying consistent themes.

In XM Cloud, there are other options for including code in a component and building components in JSS. This topic describes referencing an external React component or an entire React component library.

Components is a low-code/no-code solution mostly used by content authors and designers to create reusable elements for a website. Developers can bring their own code (BYOC) by referencing an external code base that includes components so that they can be used in the Component builder and Pages interface. After developers complete the registration flow, React components can be added to the builder. As a result:

  • The registered component is part of the components library (scoped to a project) and can be used and reused within XM Cloud Pages.

  • The registered component can be previewed in the Component builder and in Pages.

  • A content author using the component in Pages can enter values for the defined input parameters.

When you use the XM Cloud starter foundation, it comes complete with a JSS app for handling your front end. After creating your React component, you register a BYOC React component in your JSS app.

Before referencing your external components, ensure the code base is hosted on an accessible rendering host URL. You do have the option of working locally and referencing your local rendering host for testing purposes.


To make it easier to follow this topic, in the Components app, on the Settings tab, click Rendering host and copy the commands and code from there.

This walkthrough describes how to:

  • Add the registerComponent method to your code.

  • Import the component.

  • Register the rendering host (optional).

  • Troubleshoot registering an external React component.

Add the registerComponent method to your code

To register your component and specify its properties:

Import the component

You must import BYOC components into the app to finish registration and make them available for rendering. Starting from JSS version 21.6, this is handled automatically by the new starter foundation.

If you're using JSS version 21.5 or earlier, to import a component and ensure it is not removed during tree-shaking, use syntax to import the component for side effects. Place it at the top of Layout.tsx:

import './ExampleHybridComponent

BYOC can be used in non-JSS apps as well. You can find a Next.js example application implementing this method here.

When using JSS, you can also use a predefined structure for importing BYOC components, ensuring that the components are available in the appropriate contexts:

  • For client-only components, add your imports to the src/byoc-imports/index.client.ts file.

  • For hybrid components, add your import statement to the src/byoc-imports/index.hybrid.ts file.

Register the rendering host (optional)

When developing locally or using your own editing host, you can register the rendering host within the Component builder. This will allow you to develop and debug BYOC components without needing to push your app to XM Cloud. This is an optional step.

To register the rendering host:

  1. In Components, on the Settings tab, click Rendering host.

  2. In the Set your rendering host field, enter your publicly accessible URL and click Save. This fetches your React code and registers it within the Components app.

After a short wait, you can see an updated indication of the number of registered components.

Troubleshoot registering an external React component

When registering an external React component, you might get a Could not find registered BYOC component server-side error combined with a client-side (browser) hydration error.

The front-end-as-a-service (FEAAS) SDK supports CommonJS and ES modules, whereas JSS uses CommonJS. This error indicates that your Next.js application lacks the webpack plugin that ensures FEAAS and JSS use the same module formatting system.

To eliminate the error:

  1. Download the plugin file in your application in the src/lib/next-config/plugins folder.

  2. Redeploy your application.

Do you have some feedback for us?

If you have suggestions for improving this article,