Create a SitecoreAI project with your own code

Help us improve this documentation

The framework-agnostic documentation is under development. If you have suggestions for improving the content, let us know by sharing your Feedback at the bottom of this page.

To begin Sitecore development, you need a SitecoreAI project, which is a logical group of environments. Each environment holds a set of configurations, code, and implementations, including a content management (CM) instance where content authors create and publish pages. Before your front-end app can retrieve and render SitecoreAI content, you need a project connected to source control, a deployed environment, and at least one site.

This walkthrough explains how to set up such a project using your own code. By the end, you will have an empty SitecoreAI project and environment, ready for you to begin developing against.

This walkthrough describes how to:

Create a SitecoreAI project with your own code

Before you begin

To create a project in SitecoreAI Deploy, you must have an Organization Admin or Organization Owner role in your Sitecore Cloud Portal organization.
Connect SitecoreAI Deploy to your source control provider, such as GitHub or AzureDevOps.
Have an empty repository ready, or be prepared to create one. The repository will hold both your front-end application code and the SitecoreAI build configuration. SitecoreAI Deploy will read your repository.
Either clone your empty remote repository locally, or run git init in a new folder and add the remote with git remote add origin <URL>.

Set up your repository

SitecoreAI Deploy reads various files at the root of your repository to find and build your front-end code. Before you create a project in SitecoreAI Deploy, you need the correct folder structure and files in place.

To set up your repository:

Create the following structure in your repository. You'll add contents to these folders and files in later steps:

text

my-project/
├── .config/
│   └── dotnet-tools.json       ← Sitecore CLI version manifest
├── authoring/                  ← .NET solution for the authoring environment build
├── headapps/                   ← your Astro, Go, or other framework code goes here, one subfolder per app.
│   └── your-head-application/
├── .gitignore
├── nuget.config
├── sitecore.json
└── xmcloud.build.json

Copy the code from xmcloud-starter-js/.config/dotnet-tools.json into your .config/dotnet-tools.json file.

SitecoreAI Deploy runs dotnet tool restore to install the Sitecore Command Line Interface (CLI) before running any build steps. dotnet-tools.json is the .NET tools manifest that tells SitecoreAI Deploy which version of the CLI to install.
Copy the following files verbatim from the xmcloud-starter-js repository into the authoring folder. These files are boilerplate and contain a Visual Studio .NET solution. They do not need to be modified for your project:
Create an empty authoring/items folder, and add a .gitkeep file so Git tracks it. You'll add Sitecore Content Serialization (SCS) items to this folder later, when developing your solution.
In the headapps folder, initialize a project for your front-end application, such as headapps/astro-app or headapps/go-app. The headapps folder groups all front-end apps in one place, one subfolder per app.
Create a .gitignore file at the repository root to prevent build artifacts from being committed to source control, depending on your framework:
- For Astro projects:
  text
  # Node node_modules/ dist/ .astro/ # .NET bin/ obj/ # Environment files .env .env.local
  If your head app framework has its own recommended .gitignore entries such as the file generated by npm create astro, merge those in, as well.
- For Go projects:
  text
  # Go binaries headapps/go-app/go-app headapps/go-app/*.exe # Environment files headapps/go-app/.env headapps/go-app/.env.local # Editor directories .vscode/ .idea/ *.swp *.swo # OS .DS_Store Thumbs.db
Copy the code from xmcloud-starter-js/nuget.config into your nuget.config file.

The Sitecore CLI restores its plugins as NuGet packages during the build. Without this file, the build server has no Sitecore NuGet feed to restore from, and the build fails.
Copy the code from xmcloud-starter-js/sitecore.json into your sitecore.json file.

sitecore.json is the Sitecore Content Serialization configuration file. The SitecoreAI Deploy build server looks for this file to understand the authoring environment build. Without it, the build fails.

In the file, modules points at the authoring/items subfolder, which can be empty. The plugins list tells the Sitecore CLI which NuGet packages to restore during the build.
Paste the following code into xmcloud.build.json. The contents depend on whether your app is Node-based (such as Astro or Next.js) or non-Node (such as Go).
- For Node-based projects:
  json
  { "renderingHosts": { "<YOUR_HEAD_APP>": { "path": "./headapps/<APP_FOLDER>", "nodeVersion": "22", "jssDeploymentSecret": "<RANDOM-32-CHARACTER-LONG-STRING>", "enabled": true, "type": "sxa", "buildCommand": "build", "runCommand": "start" } }, "postActions": { "actions": { "warmUpCm": { "urls": [ "/sitecore/shell", "/sitecore/shell/Applications/Content%20Editor.aspx?sc_bw=1", "/sitecore/client/Applications/Launchpad" ] }, "populateSchema": { "indexNames": [] }, "reindex": { "indexNames": [] } } }, "authoringPath": "./authoring" }
  SitecoreAI Deploy can natively build and host Node-based apps. Each entry in renderingHosts tells SitecoreAI Deploy where your app code lives and how to build and run it. SitecoreAI uses the hosted instance as an editing host for visual editing in the Page builder. jssDeploymentSecret is a shared secret that authorizes the app to deploy items to the Sitecore instance.
  
  The postActions block runs after the main build completes. It warms up the content management instance by requesting key Sitecore shell URLs, and triggers schema population and search index rebuilds.
  
  Replace the following in the script:
  - Replace <YOUR_HEAD_APP> with a short, descriptive name for your editing host, such as astro-head.
  - Replace <APP_FOLDER> so the value matches your subfolder name, such as astro-app.
  - Replace <RANDOM_32_CHARACTER_LONG_STRING> with a random alphanumeric string of at least 32 characters.
- For non-Node projects:
  json
  { "renderingHosts": {}, "postActions": { "actions": { "warmUpCm": { "urls": [ "/sitecore/shell", "/sitecore/shell/Applications/Content%20Editor.aspx?sc_bw=1", "/sitecore/client/Applications/Launchpad" ] }, "populateSchema": { "indexNames": [] }, "reindex": { "indexNames": [] } } }, "authoringPath": "./authoring" }
  SitecoreAI Deploy can only natively build and host Node-based applications. For non-Node apps, you deploy the app yourself to your own hosting provider and then configure it in Sitecore as an external editing host. The renderingHosts object is left empty because there is no editing host for SitecoreAI Deploy to build and manage.
  
  The postActions block runs after the main build completes. It warms up the content management instance by requesting key Sitecore shell URLs, and triggers schema population and search index rebuilds.
Commit all files and push them to your remote repository before creating the project in SitecoreAI Deploy.

Create a project in SitecoreAI Deploy

After preparing your repository, you can create a SitecoreAI Deploy project, connect it to your repository, and provision an authoring environment.

In SitecoreAI Deploy, click Projects > Create project.
In the Set up project window, enter a descriptive name for your project.
In the Source code set up section, click Use your own code, and then click Continue.
In the Set up authoring environment window, enter a descriptive name for your environment, such as staging, dev, or prod.
In the Repository section, choose the source control account you connected SitecoreAI Deploy to, and choose the repository you created in the previous procedure, and then click Continue.
In the Set up editing host (optional) window, do one of the following, depending on your framework:
- For Node-based projects - enter the editing host name. This must be the key name from renderingHosts in xmcloud.build.json, such as astro-head.
- For non-Node projects - skip this step. Non-Node apps are configured as external editing hosts after deployment, once the app is running on your own infrastructure.
Click Continue, and then click Start deployment.

Provisioning the authoring environment takes several minutes. You are redirected to the Deployments page, where you can follow progress. If the deployment fails, the log shows which step encountered an error.

Create a site in SitecoreAI Deploy

After the project is deployed, you create a site in your environment, which is required before starting to render content in your front-end app.

To create a site in your environment:

In SitecoreAI Deploy, click Projects > the project you created in the previous procedure.
On the Authoring environments tab, click the environment you created in the previous procedure.
On the Sites tab, click Create your first site. The Channels page opens.
On the Channels page, in the Get started section, select the Basic template.
In the Create site window, enter a site name, a site collection name, and then click Create. SitecoreAI starts creating a site, which can take several minutes.

After the site is created, its pages and content items are configured in Sitecore. You will enable your front-end app to retrieve and render them in the following steps.

Next steps

You now have a SitecoreAI project connected to source control and deployed with an environment and a site. Next, follow the content rendering documentation, including the Render SitecoreAI content in your app walkthrough.

If you have suggestions for improving this article, let us know!