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

Abstract

Leverage component scaffolding functionality to quickly define new components

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:

    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:

    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:

    // 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:

    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:

    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.