Walkthrough: Creating a new component in a JSS Next.js app

Current version: 22.0

Creating new components is one of the most common tasks performed while developing JSS applications.

This walkthrough assumes you have a project called MyProject.

The walkthrough explains how to:

  • Create the JSON rendering in Sitecore.

  • Verify the rendering's JSON output.

  • Verify the rendering's JSON output.

  • Fill out values in the Experience Editor.

Create the JSON rendering in XM Cloud

To create the JSON rendering in XM Cloud:

  1. In the Content Editor, in the /sitecore/templates/Project/myproject folder, create a new template called MyComponent.

  2. In the new template, create a new template section (the name is unimportant) and add the following fields:

    • heading, with the type Single-line Text.

    • body, with the type Rich Text.

  3. Using the Title standard field, provide a descriptive and user-friendly name for the template.

  4. With the Builder tab open, in the Builder Options menu, click Standard Values and in the heading and body fields enter some default values.

  5. In the content tree, in /sitecore/layout/Renderings/Project/myproject, create a JSON rendering called MyComponent, and set values for the following fields:

    • Datasource Location field: enter ./

    • Datasource Template: select sitecore/Templates/Project/myproject/MyComponent.

  6. Add the MyComponent rendering to the Allowed Controls in the /sitecore/layout/Placeholder Settings/Project/myproject/Main placeholder and click Save.

  7. Open /sitecore/content/MyProject/Home in the Experience Editor and add your new rendering, including creating a data source item for it.


    Your rendering host page outputs JSS component is missing React implementation or a similar message because you have not yet mapped a component to this JSON rendering in your rendering host.

  8. Publish all your item changes:

    • In Content Editor, on the Publish ribbon, click the small black arrow next to the Publish icon and click Publish site.

    • In the Publish Site window, to publish your items from the Master database to the Web database, select the Smart publish radio button and click Publish.

Verify the rendering's JSON output

To test the output of your new rendering, try to view to Layout Service JSON output for the site home page.

To view the JSON output:

  1. From the file scjssconfig.json in your Next.js application root, copy the apiKey value.

  2. In a browser, open the URL https://cm.myproject.localhost/sitecore/api/layout/render/jss?item=/&sc_apikey=<YOUR API KEY>&sc_site=<YOUR SITE NAME>&sc_mode=normal.

  3. The output must include your new component.

        "uid": "ba5d4f2d-b6f1-428a-81e8-6b7c25844c08",
        "componentName": "MyComponent",
        "dataSource": "{A2A3F4C0-B13B-4651-B342-320E56FDC43A}",
        "params": {},
        "fields": {
            "heading": {
                "value": "Default"
            "body": {
                "value": "Default"

Create the component in the Next.js app

In the Next.js application, you must create a component matching the rendering you just created in XM Cloud.

To create a component in a JSS Next.js app:

  1. Create the file MyProject\src\my-project\src\components\MyComponent.tsx.

  2. In the newly created file, define a component with the same name as the rendering:

    import { Text, Field, RichText } from '@sitecore-jss/sitecore-jss-nextjs';
    type MyComponentProps = {
      fields: {
        heading: Field<string>,
        body: Field<string>  
    const MyComponent = (props: MyComponentProps): JSX.Element => (
        <Text field={props.fields.heading} />
        <RichText field={props.fields.body} />
    export default MyComponent;

Fill out values in the Experience Editor

You can now fill out the values for the fields of the component.

To fill out values:

  1. In the Experience Editor, open the item /sitecore/content/MyProject/home.

  2. Fill out values for all fields.

  3. Save and publish the item.

  4. Refresh the application in the browser, usually served at http://localhost:3000 to see the changes.

Do you have some feedback for us?

If you have suggestions for improving this article,