CLI commands and configuration

The sitecore-tools project build CLI command prepares app-specific build artifacts, such as those required for the app to connect to SitecoreAI. It does this by sequentially executing the functions listed in the build: section of your CLI config file.

sitecore-tools project build

Your app's package.json file includes a build script that calls this CLI command, so it runs every time your app is built.

By default, the CLI will try to use a file named sitecore.cli.config.ts in the folder where you run the command. If that file does not exist the CLI will try to use sitecore.cli.config.js instead.

If you're running the command in a folder that doesn't contain either of these files, you need to specify the name and (relative) location of the file by using the --config argument, as shown in the following example where a custom file is used in the current folder:

sitecore-tools project build --config=custom.sitecore.cli.config.ts

Within the config file's build.commands: section, you can add custom functionality as shown with myBuildCommand() in the following example:

import { defineCliConfig } from '@sitecore-content-sdk/nextjs/config-cli';
import { SitecoreConfig } from '@sitecore-content-sdk/nextjs/config';
import { generateSites, generateMetadata } from '@sitecore-content-sdk/nextjs/tools';
import config from './sitecore.config';

const myBuildCommand = (
  param: string
): (({ scConfig }: { scConfig: SitecoreConfig }) => Promise<void>) => {
  return async ({ scConfig }) => {
    console.log(param, scConfig.defaultSite);
    return Promise.resolve();
  };
};

export default defineCliConfig({
  config,
  build: {
    commands: [generateMetadata(), generateSites(), myBuildCommand('this is my build command!')],
  },
});

You can configure the default generateMetadata method using a GenerateMetadataConfig object. It accepts two optional parameters:

For additional examples of customization, look at the implementations of generateMetadata and generateSites in the core package.

The sitecore-tools project component scaffold command generates a new named component in the src/components/ folder of your app, based on the default template for the framework.

For example, the following command would create a new file named MyComponent.tsx.

sitecore-tools project component scaffold MyComponent

When using this command, in addition to the new component's name you can also include a path. This path is relative to where you run the command, so running the following example in src/components/ will create YourComponent.tsx in src/components/marketing/.

sitecore-tools project component scaffold marketing/YourComponent

There are two default templates available by default:

To scaffold a BYOC component, add the --byoc flag to your command, as shown in the following example:

sitecore-tools project component scaffold MyBYOCComponent --byoc

If you want to use a custom template file to scaffold your component, specify its name (and optionally its path) with the --templateName argument, as shown in the following example:

sitecore-tools project component scaffold MyCustomComponent --templateName=myTemplate

When using this command, you can include the --config argument to specify the path of a custom CLI configuration file if needed, as shown in the following example:

sitecore-tools project component scaffold MyComponent --config=custom.sitecore.cli.config.ts

Within the config file, a scaffold: section can be added if you want to define additional templates.

In the following example, a scaffold: section has been added to the default CLI config file, including a templates: section that provides a list defining custom component templates of type ScaffoldTemplate. Any of these custom templates can then be used instead of the default ones by including the templateName argument in your scaffold command.

import { defineCliConfig } from '@sitecore-content-sdk/nextjs/config-cli';
import { generateSites, generateMetadata } from '@sitecore-content-sdk/nextjs/tools';
import config from './sitecore.config';

export default defineCliConfig({
  config,
  build: {
    commands: [
      generateMetadata(),
      generateSites(),
    ],
  },
  scaffold: {
    templates: [
      {
        name: 'myTemplate',
        generateTemplate: (componentName: string) => {
          return `this is my new ${componentName}`;
        },
        getNextSteps: (componentOutputPath: string) => {
          return ['this is the next step', `component path is here: ${componentOutputPath}`];
        },
        fileExtension: 'tsx',
      },
    ],
  },
});

The sitecore-tools project add command generates and adds a new component from the Design studio to your application. It simplifies component generation and ensures consistent component mappings throughout your project.

You invoke the command with a component identifier, and an authentication token as shown:

sitecore-tools project component add <component-id> --token <auth-token> [options]

You can optionally direct output to a specific path, skip map generation, or allow overwriting.