Create a new component in a JSS Next.js app using the code-first development workflow

Current version: 19.x

Creating new components is one of the most common tasks performed while developing JSS applications. To facilitate the creation of new components, JSS Next.js applications provide a scaffolding script, defined in the file scripts/scaffold-component.ts.

This procedure demonstrates how to use the scaffolding script to create a new component in your JSS Next.js app using the code-first development workflow.

Note

This procedure assumes you have set up your project using the jss create CLI command.

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

  1. In a terminal, in the root directory of your Next.js project, start the application by running the script:

    RequestResponse
    jss start
    Tip

    In your browser, go to http://localhost:3000/  to see your code changes in real-time.

  2. Open a new terminal tab/window. In your application's root directory, run:

    RequestResponse
    jss scaffold MyComponent
    Tip

    The scaffolding system emits a simple working component. You can modify the scaffolding conventions in src/scripts/scaffold-component.js.

  3. In the application's root directory, in the file sitecore/definitions/components/MyComponent.sitecore.ts containing the Manifest definition for the new component, define the data fields for the component. For example:

    RequestResponse
    // eslint-disable-next-line no-unused-vars
    import { CommonFieldTypes, SitecoreIcon, Manifest } from '@sitecore-jss/sitecore-jss-manifest';
    
    /**
     * Adds the MyComponent component to the disconnected manifest.
     * This function is invoked by convention (*.sitecore.ts) when 'jss manifest' is run.
     * @param {Manifest} manifest Manifest instance to add components to
     */
    export default function MyComponent(manifest: Manifest): void {
      manifest.addComponent({
        name: 'MyComponent',
        icon: SitecoreIcon.DocumentTag,
        fields: [{ name: 'heading', type: CommonFieldTypes.SingleLineText }],
        /*
        If the component implementation uses <Placeholder> or withPlaceholder to expose a placeholder,
        register it here, or components added to that placeholder will not be returned by Sitecore:
        placeholders: ['exposed-placeholder-name']
        */
      });
    }
    
  4. In the filesrc/components/MyComponent.tsx, implement the React component. For example:

    RequestResponse
    import { Text, Field, withDatasourceCheck } from '@sitecore-jss/sitecore-jss-nextjs';
    import { StyleguideComponentProps } from 'lib/component-props';
    
    type MyComponentProps = StyleguideComponentProps & {
      fields: {
        heading: Field<string>;
      };
    };
    
    const MyComponent = (props: MyComponentProps): JSX.Element => (
      <div>
        <p>MyComponent Component</p>
        <Text field={props.fields.heading} />
      </div>
    );
    
  5. The newly created component is inactive until added to a layout on a route. Add the component to a route layout. In this example, we add the component to the root route to the default placeholder jss-main. In the file /data/routes/en.yml, add your component to the array of components under the jss-main placeholder:

    RequestResponse
    placeholders:
      jss-main:
      - componentName: MyComponent
        fields:
          heading: Hello, Next.js!
      - componentName: ContentBlock
        fields:
          heading: Welcome to Sitecore JSS
  6. Check your browser. The new component displays at the top of the page.

Do you have some feedback for us?

If you have suggestions for improving this article,