Build your first component

Timing 20 minutes

This is part four of the getting started walkthrough series. Before you can complete the steps here, make sure you have created a project and environment, created a site and page, and set up your local development environment.

In this example, you'll be creating a React Next.JS component in XM Cloud. You'll be creating a component that includes a title and text. To create the component, you will clone one of the existing components that are included out of the box in XM Cloud. Cloning an existing component saves development time by creating the boilerplate items and configurations that your component requires, and makes sure that the required base templates are configured to support the content authoring features in Pages.

This walkthrough describes how to:

Create and deploy the new component to XM Cloud

In the first step, you create the component structure in your local Next.JS project. To do this:

Ensure you still have the cloned repository open in your code editor.
In the /headapps/nextjs-starter/src/components folder create a new file and name it TitleAndText.tsx.

Paste the following code into the new file:

RequestResponse

import React from 'react';
import { Field, Text } from '@sitecore-jss/sitecore-jss-nextjs';

interface Fields {
  Title: Field<string>;
  Text: Field<string>;
}

export type TitleAndTextProps = {
  params: { [key: string]: string };
  fields: Fields;
};

export const Default = (props: TitleAndTextProps): JSX.Element => {
  return (
    <div className="container-default">
      <h1 className="component title row">
        <Text field={props.fields.Title} />
      </h1>
      <div className="component text row">
        <Text field={props.fields.Text} />
      </div>
    </div>
  );
};

Save the file.
Add the change to a commit and push the change to your repo. This will automatically kick off a deployment to XM Cloud. You can follow its progress in the Deploy app. Proceed to the next step after the deployment is complete.

Create the rendering definition

Now, you proceed to create the rendering definition for the component. Rendering definitions are used to tell XM Cloud where in the project the component's .tsx file is, and what data it needs to render correctly. You'll do this by cloning an existing rendering rendering, thereby automatically generating all the required items, instead of having to do it manually. Then, you'll add the rendering to the headless module that was created when you created the site collection. You can find the module in /sitecore/system/Settings/Project.

To clone the component:

In the Cloud Portal, click the tile for the environment you created earlier - XMC Getting Started.
In the pane on the right, click Open app.
On the top menu bar, click Content, then click Content Editor.
In the Content Editor, navigate to /sitecore/layout/Renderings/Feature/Headless Experience Accelerator/Page Content. Right-click the rendering named Rich Text and click Scripts > Clone Rendering.
In the Create derivative rendering window, specify the following:
- On the General tab, enter the name TitleAndText.
- On the General tab, in the Add to module field, select Renderings/Project/XMC Getting Started/XMC Getting Started.
- On the Parameters tab, select Make a copy of original rendering parameters. This decouples the rendering from the original component and reduced dependencies.
- On the Datasource tab, in the Datasource field, select Make a copy of original datasource.
Click Proceed, and close the window when the process is finished.
Navigate to /sitecore/templates/Project/XMC Getting Started/Getting Started Content/Text, and ensure the Builder tab is selected.
Change the values for the fields you created:
- Title - select Single-Line Text.
- Text - select Multi-Line Text.
Make sure the Source column is empty for both fields.
In the top-left corner, click Save.
Navigate to /sitecore/content/XMC Getting Started/XMC Getting Started/Presentation/Available Renderings.
Right-click the Available Renderings item and click Insert > Available Renderings.
Name the new item Getting Started Content and click OK. The new item opens automatically.
In the Renderings field, click Edit.
In the tree on the left, locate and select the rendering item you created previously at /Layout/Renderings/Project/XMC Getting Started/Getting Started Content/TitleAndText. Click the arrow to move it to the list on the right, then click OK.
In the top-left corner, click Save.
Navigate back to the main XM Cloud dashboard by clicking the 9-square icon in the top left.

Add the component to your site page

At this stage, you've completed the required configuration for the new component and it's available to use on your site. In this step, you can return to Pages and add the component to the page you created earlier, after which you'll be able to see it on your local development instance.

On the main XM Cloud Sites dashboard, click the tile of the new site to open Pages, or, in a new browser tab, open https://pages.sitecorecloud.io/.
On the Components tab, in the Getting Started Content section, you can now see the Title and Text component. Drag it onto one of the plus icons on the page. You should now see the component rendered on the page, with a No text in field indicator for the title and text fields.
Type in some text to the title and text fields.
In the previous walkthrough, you connected your application to the local host. Check if it's still running, and if it isn't, in the terminal window, run npm run start:connected.
In your browser, navigate to http://localhost:3000/ to see the new component rendered with the text you entered.

You've completed the walkthrough series! You can now continue to create new components, test your changes locally, and push to your source control provider - this kicks off a deployment in XM Cloud and makes new components available in Pages.

Do you have some feedback for us?

If you have suggestions for improving this article,