--- title: "The SitecoreAI build configuration" slug: "the-sitecoreai-build-configuration" abstract: "Reference for the SitecoreAI build configuration file" --- # The SitecoreAI build configuration The [SitecoreAI](https://doc.sitecore.com/sai/en/users/sitecoreai/sitecoreai.html) build configuration for an environment is defined in the `xmcloud.build.json` file. The file contains configurations for editing hosts, build targets, serialization modules to deploy to the XM instance for that environment, and more. > [!tip] > You can consult the [PLAY! Summit project repository](https://github.com/Sitecore/Sitecore.Demo.XmCloud.PlaySummit) for a working example of the [`xmcloud.build.json` file](https://github.com/Sitecore/Sitecore.Demo.XmCloud.PlaySummit/blob/main/xmcloud.build.json). > [!note] > **XM Cloud is now SitecoreAI** > Some code examples, images, and UI labels may still use XM Cloud while engineering assets are being updated. The build configuration object has the following structure: ```json { "deployItems": { "modules": [] }, "buildTargets": [], "renderingHosts": { "": }, "transforms": [], "postActions": { "actions": { "": } }, "authoringPath": } ``` The following table shows the properties of the build configuration object: | Name | Description | | --- | --- | | `deployItems` | Allows you to define which serialization item modules to deploy. During the deployment build, `.yml` files that belong to the selected serialization modules are processed to generate `.dat` resource files. These files are deployed to the SitecoreAI CM instance as *Items as Resources* (IAR) files. The conversion from `.yml` to `.dat` occurs during the environment deployment; not when running `dotnet sitecore ser push`. This configuration is similar to the serialization configuration in the `sitecore.json` file and is useful for limiting what you deploy during local development. You do not need direct access to manually manage the generated `.dat` files.

All modules defined in `deployItems` are converted into a IAR files. The IAR creation process is recorded in the Deploy app build logs. Roles are not supported. To deploy roles, use the [SCS module deployment action](https://doc.sitecore.com/sai/en/developers/sitecoreai/deploying-sitecoreai/the-sitecoreai-build-configuration.html#post-deployment-actions).

Example

`"deployItems": {`
  `"modules": [`
     `"Foundation.*",`
     `"Feature.*",`
     `"Project.*"`
     `]`
`}`

Important: If you omit `deployItems` from your build configuration, all members of the `modules` property in your `sitecore.json` file are converted into IAR files.

Note: You cannot delete or modify IAR files directly. To override existing items, deploy the updated items in a subsequent deployment. To remove an item deployed as a resource, remove its serialized `.yml` file and redeploy the environment.
| `buildTargets` | Allows you to define which projects and solutions to build.

Example

`"buildTargets": [`
    `"./src/CM/Platform.csproj",`
   `"./src/CM/Root.sln"`
`],`

This configuration affects how you pass arguments to the `msbuild` command:
`msbuild .\src\platform\Platform.csproj /p:Configuration=$env:BUILD_CONFIGURATION /m /p:DeployOnBuild=true /p:PublishProfile=Local` | `renderingHosts` | Allows you to configure the location for the rendering hosts and the sites they map to. It consists of key-value pairs where the key is a *unique site name*, and the value contains [information about the site](https://doc.sitecore.com/sai/en/developers/sitecoreai/deploying-sitecoreai/the-sitecoreai-build-configuration.html#configuration-options-for-rendering-hosts). | | `transforms` | An array of items mapping an XDT path to a target path.

Allows you to specify fully qualified paths with wildcards to the location where you want to process XDT transforms. | | `postActions` | [Operations](https://doc.sitecore.com/sai/en/developers/sitecoreai/deploying-sitecoreai/the-sitecoreai-build-configuration.html#xdt-transformations) to perform following the deployment stage of a deployment process. | | `authoringPath` | Allows you to specify the relative path of the authoring environment code. This ensures that if your editing host and authoring environment code share the same repository, a change to authoring environment code does not automatically trigger a redeployment of the editing host and vice versa. The default value is `./authoring`.

Note: This property only affects environments created using [the beta feature that lets you deploy your authoring environments and editing hosts separately.](https://developers.sitecore.com/changelog/sitecoreai/03032025/improvements-to-project-creation-and-management%2c-including-separate-repositories-for-each-authoring-environment-and-editing-host)
| ## Configuration options for rendering hosts You can define rendering hosts in the build configuration file. Each definition maps a *unique site name* to information about the site. **Example** ```json "renderingHosts": { "xmcloudpreview": { "path": "./src/rendering", "nodeVersion": "16.3.19", "packageManager": "npm", "jssDeploymentSecret": "super-secret-value", "enabled": true, "type": "sxa", "buildCommand": "build", "runCommand": "next:start" } } ``` > [!note] > The editing host build process and runtime operate in a restricted environment. Any file operations such as read, add, edit, or delete must be performed in the designated working directory. The following table describes the properties you use to configure the site information: | Name | Type | Description | | --- | --- | --- | | `path` | `string` | The relative path from the `xmcloud.build.json` file to the app source code. Usually, it is the relative path from the root folder. | | `nodeVersion` | `string` | Specific Node.js version for rendering host.

The major version of Node.js used by hosts and starters and the one used by Content SDK must match. | | `packageManager` | `string` | Defines the package manager used to build the application.

Possible values: `npm`, `pnpm`. Default value is `npm`.

If property not present, default will be used. | | `jssDeploymentSecret` | `string` | A randomly generated string of 32 or more characters. The deployment secret is a shared secret that authorizes the application to deploy items to the Sitecore instance. It populates the value for `deploySecret` in the `scjssconfig.json` file. | | `enabled` | `boolean` | Enables the site.

Default: `false`. | | `type` | `string` | Type of rendering host.

Allowed values: `"jss"` or `"sxa"`.

Default: `"jss"`

**Note**
An SXA site is created from an [SXA template](https://doc.sitecore.com/sai/en/developers/sitecoreai/content-modeling-and-presentation/sitecoreai-for-developers/content-editor-items/site-collections/create-a-headless-site-collection-and-site.html) and uses item-based configuration. A JSS site is created from a [JSS template](https://doc.sitecore.com/sai/en/developers/jss/22/jss-sai/create-a-jss-app-locally.html) and uses file-based configuration. | | `buildCommand` | `string` | Build command from the `package.json` file to run.

Default: `"build"` | | `runCommand` | `string` | Run command from the `package.json` file to run.

Default: `"next:start"` | > [!important] > `startCommand` has been deprecated and is ignored. Use `buildCommand` and `runCommand` instead. ## Custom editing hosts [Editing hosts](https://doc.sitecore.com/sai/en/developers/sitecoreai/environment-editing-hosts-and-rendering-hosts/the-different-types-of-editing-hosts-in-sitecoreai.html) enable WYSIWYG editing in editors such as the Page builder and Design studio. Custom editing hosts correspond to a `renderingHosts` entry in the `xmcloud.build.json` file. > [!warning] > Do not use the name 'default' when adding a custom editing host. 'Default' is a reserved editing host name and cannot be used for custom editing hosts. Attempting to configure a custom editing host with this name may result in incorrect site resolution or unexpected behaviour. ## XDT transformations To support XDT transforms, you must specify the fully qualified paths to a folder or an XDT source file and configuration destination files. Transformations occur on the fully built solution. The paths must be relative to the web root of the built code. For example, assuming your XDT source files are located in the `src/platform/xdts` folder, you can configure transform paths as follows: ```json "transforms": [ { "xdtPath": "/xdts//", "targetPath": "//" }, { "xdtPath": "/xdts//", "targetPath": "/" }, { "xdtPath": "/xdts/web.config.xdt", "targetPath": "/web.config" } ] ``` > [!note] > The value of the `xdtPath` property for each transform depends on how you organize your project files. In this example, we assume your project is based on a foundation template provided by Sitecore and that your transformations are in the `/src/platform/xdts/` folder. For information on how to define XDT files, consult the documentation for [web.config transformations](https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/iis/transform-webconfig?view=aspnetcore-6.0). ## Post-deployment actions You can configure various operations, called *post actions*, that run *after the deployment stage* of a deployment process. The build configuration includes default actions you can customize to fit your requirements. They are defined using the `actions` property of the `postActions` object and include: - CM warm-up. - Deploying SCS modules. - Schema population. - Reindexing. - Publishing. > [!note] > Post actions run one after the other, in the order which they appear in the configuration file. Therefore, when configuring your post actions, we highly recommend that you do not change the order of the actions. > > The order shown in the following example ensures that if you deploy SCS modules, they will be published. And that the indexes are populated before reindexing. The post actions configuration has the following structure: ```json "postActions": { "actions":{ "warmUpCm": { "urls": [] }, "scsModules": { "modules": [] }, "populateSchema": { "indexNames": [] }, "reindex": { "indexNames": [] }, "publish": { "path": "", "languages": [], "itemIds": [], "targets": [], "republish": true, "publishSubItems": true } } } ``` ### The CM warm-up action You can warm up various [SitecoreAI](https://doc.sitecore.com/sai/en/users/sitecoreai/sitecoreai.html) pages by defining an array of relative URLs in the `urls` property of the `warmUpCm` action. **Example** ```json "warmUpCm": { "urls": [ "/sitecore/shell", "/sitecore/shell/Applications/Content%20Editor.aspx?sc_bw=1", "/sitecore/client/Applications/Launchpad", "/sitecore/client/Applications/ControlPanel.aspx?sc_bw=1" ] } ``` ### The SCS module deployment action > [!note] > For more information about Sitecore Content Serialization, see [Setup Sitecore Content Serialization](https://developers.sitecore.com/learn/accelerate/xm-cloud/pre-development/sprint-zero/setup-content-serialization). You can deploy Sitecore Content Serialization (SCS) modules to the Sitecore instance using the `scsModules` action. The structure of the `scsModules` action is: ```json "scsModules": { "modules": ["Module1","Module2"] } ``` ### The schema population action You can restrict the managed schema population to specific indexes by defining a list of index names in the `indexNames` property of the `populateSchema` action. An empty array results in the population of all available indexes. **Example** ```json "populateSchema": { "indexNames": [] } ``` ### The reindexing action You can restrict reindexing to specific indexes by defining a list of index names in the `indexNames` property of the `reindex` action. An empty array results in the reindexing of all available indexes. **Example** ```json "reindex": { "indexNames": [] } ``` ### The publishing action You can configure publishing operations using the `publish` action. The structure of the `publish` action is: ```json "publish": { "path": "", "languages": [], "itemIds": [], "targets": "", "republish": true, "publishSubItems": true } ``` When using the `publish` action to publish an item, you can control the publishing of its subitems by defining the `publishSubItems` property within the publish action. If this property is not included, subitems will be published by default. Allowed values: - `true` - subitems will be published. - `false` - subitems will not be published. The following example does not publish the subitems of */sitecore/content/Home*: ``` "publish": { "path": "/sitecore/content/Home", "languages": [], "itemIds": [], "targets": [], "republish": true, "publishSubItems": false } ``` ### Change the post action timeout The default timeout for each post action is 30 minutes. In some cases, you might need to override the default timeout, for example if there is a large number of items to reindex. You can change the default timeout by defining the `taskTimeOut` property in the post actions structure. The following example changes the post action timeout to 45 minutes: ```json "postActions": { "actions":{ ... }, "taskTimeOut": "00:45:00" } ```