Deploy Astro to XM Cloud

Sitecore XM Cloud comes with a built-in rendering host. It is a Node.js server that allows you to run any JavaScript framework. You can run Angular with Node.js proxy, Vue with Node.js proxy, React with Node.js proxy, and Next.js. But also you can run any other framework. Today, I will show you how to run it on the Astro JSS web framework.

The shortest way will take you only a few minutes. If you run Astro on The XM Cloud for the first time, I do recommend the shortest way. Please, scroll to the Sitecore XM Cloud section.

But I will describe a more detailed way. It will give you a better understanding of how XM Cloud works. If you want to make sure that your code is based on the latest changes in both Sitecore Astro JSS and XM Cloud templates, please follow all steps.

Repository Creation

We will use the official Sitecore xmcloud-foundation-head repository as the template for our project. We need to go to GitHub and create a new repository that is based on this template.

Create a new Astro project

This repository template contains head applications for Next.js and Angular. We need to add one more for Astro. You need to pull the repository locally to be able to add your code changes. Head applications are located in the headapps folder. We will place our Astro project in the same location. We need to run npx @astro-sitecore-jss/create-astro-sitecore-jss@latest command to create a new head application.

If you want to read in detail about Astro project creation, please refer to this our article.

The one additional step is to make sure that we don’t commit scjssconfig.json. First of all, we don’t want to save our configuration and secrets in Git. Second, we don’t want these settings to overwrite XM Cloud environment variables.

Code Changes

XM Cloud has specific requirements for your head application. And we need to make sure that our head application follows them.

1. We need to use 3000 port. Astro uses the 4321 port by default. Probably, Sitecore will add the ability to use different port in the future. But, for now, we need to switch to 3000.
2. Egg and chicken problem. XM Cloud build head application before deploying Sitecore. Astro uses SSG by default and requires data from Sitecore. We need to make Astro “egg” for this case and switch to SSR. (BTW, this issue is only for the first build. Once we have Sitecore up and running on XM Cloud, we can switch back to SSG)
3. XM Cloud template doesn’t contain any sample content. In order to see Astro in action, we need to add Sitecore items serialization: tenant, site, pages, templates, renderings, etc.
4. Add our Astro head application to xmcloud.build.json

"astrojsstarter": {
  "path": "./headapps/astro-starter",
  "nodeVersion": "22.11.0",
  "jssDeploymentSecret": "110F1C44A496B45478640DD36F80C18C9",
  "enabled": true,
  "type": "sxa",
  "buildCommand": "build",
  "runCommand": "preview"
},

Sitecore XM Cloud

Repository

You can use your own repository with all the latest changes described above. But the simpler option is to use our template. You need to create your GitHub repository either from this template or fork it if you plan to contribute to this template.

XM Cloud portal project

Now, you can proceed with XM Cloud Project creation once you have the repository.

Choose source control

You need to connect your Github account with access to the previous repository you created.

Set up repository

The next step is to select “Use your own code” and choose Github account, repository, and branch.

Configure authoring environment

You can use any name for the environment that you want.

Review and deploy

The last step will be reviewing your settings. If you are happy with them, click “Start deployment”.

Deployment

You will have a new Sitecore instance with configured Astro rendering host in less than 10 minutes.

Pages

You should not notice any difference with Next.js. Everything in Sitecore XM Cloud should work and feel the same, including all editing features inside the Pages interface.

Try it!

It became very easy to try Astro together with XM Cloud. It takes less than 10 minutes to deploy the Sitecore XM Cloud project on Astro. And you get the Sitecore repository, where you can play with Astro, see code in action, and experiment with features you are interested in. So, what are you waiting for? Give Astro a try and start building blazing-fast websites on Sitecore together with Astro JSS!