Walkthrough: Registering an external component

XM Cloud includes a powerful component builder interface, which designers can use to resize 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 or web component or an entire React or web 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 interface. After developers complete the registration flow, external 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.

    Note

    External components are previewed in a separate tab of the components builder. In Pages, they are rendered directly in the canvas.

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

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.

Tip

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.

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

This walkthrough describes how to:

  • Add the registerComponent method to your code

  • Import the component

  • Register the rendering host (optional)

Add the registerComponent method to your code

To register your component and specify its properties:

Import components

You must import BYOC components into the app to finish registration and make them available for rendering.

  • To ensure the imported components aren't removed during a tree shake, create an intermediate index component that imports all your registered React or web components and exports a FEAAS.ExternalComponent(props) component, as in this index.tsx example:

    RequestResponsets
    // Component that can be rendered both on the client and server
import './ExampleHybridComponent'

// Required: Exported empty fragment for Next.js to import
export default () => <></>

You can find a complete Next.js example application implementing this method here.

Currently, pure server and client-side components aren't supported in JSS.

Register the rendering host (optional)

When developing locally, or if you use your own editing host, you can register the rendering host within the Component builder:

  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 code and registers it within the Components app.

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

Troubleshooting

When registering an external 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.

A project is a logical grouping of XM Cloud environments. Each project can include several environments, such as a development, testing, and production environment. In XM Cloud, you can create a project using the Deploy app, the CLI, or REST APIs.

When you create a project using the Deploy app, one environment is automatically created, and you can choose whether it’s a production environment (that gets faster support than the non-production environments). The number of projects you can create depends on your subscription.

Do you have some feedback for us?

If you have suggestions for improving this article,