The XM Cloud build configuration

Abstract

Reference for the XM Cloud build configuration file

The XM Cloud 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 for a working example of the xmcloud.build.json file.

The XM Cloud build configuration object has the following structure:

{
  "deployItems": {
    "modules": []
  },
  "buildTargets": [],
  "renderingHosts": {
    "<key>": <value>
  },
  "transforms": [],
  "postActions": {
    "actions": {
      "<key>": <value>
    }
  }
}

The following table shows the properties of the XM Cloud build configuration object:

Name	Description
`deployItems`	Allows you to define what serialization item modules you want to deploy. It is similar to the serialization configuration defined in the `sitecore.json` file. Useful to limit what you deploy when working locally. For example: "deployItems": { "modules": [ "Foundation.", "Feature.", "Project.*" ] }
`buildTargets`	Allows you to define which projects and solutions to build. For 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.
`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 to perform following the deployment stage of an XM Cloud deployment process.

Configuration options for rendering hosts

You can define rendering hosts in the XM Cloud build configuration file. Each definition maps a unique site name to information about the site.

For example:

  "renderingHosts": {
    "xmcloudpreview": {
      "path": "./src/rendering",
      "nodeVersion": "16.3.19",
      "jssDeploymentSecret": "super-secret-value",
      "enabled": true,
      "type": "sxa"
    }
  }

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.
`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"`.
`lintCommand`	`string`	Linting command from the `package json` file to run. If it is null or it does not exist, it will not run linting. Default: `lint`
`startCommand`	`string`	Start command from the `package.json` file to run. Default: `start:production`.

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:

  "transforms": [
    {
      "xdtPath": "/xdts/<some-transforms>/",
      "targetPath": "/<somewhere>/"
    },
    {
      "xdtPath": "/xdts/<trasforms-at-the-root>/",
      "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 starter kit 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.

Post-deployment actions

You can configure various operations, called post actions, that run after the deployment stage of an XM Cloud deployment process.

The XM Cloud 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.
Schema population.
Reindexing.
Publishing.

The Post Actions configuration has the following structure:

"postActions": {
  "actions":{
    "warmUpCm": {
      "urls": []
    },
    "populateSchema": {
      "indexNames": []
    },
    "reindex": {
      "indexNames": []
    },
    "publish": {
      "path": "",
      "languages": [],
      "itemIds": [],
      "targets": [],
      "republish": true
    }
  }
}

The CM warm-up action

You can warm up various Sitecore XM Cloud pages by defining an array of relative URLs in the urls property of the warmUpCm action.

For example:

"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 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.

For example:

"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.

For example:

"reindex": {
  "indexNames": []
}

The publishing action

You can configure publishing operations using the publish action.

The structure of the publish action is:

"publish": {
  "path": "",
  "languages": [],
  "itemIds": [],
  "targets": "",
  "republish": true
}