Mono-repo or multi-repo? XM Cloud microservices management

Two common approaches are: 

• Using a mono-repo, where all microservices reside in a single repository

• Using a multi-repo, opting for individual repositories for each microservice  

Each approach has its advantages and challenges, which will be covered in this article.

What is a mono-repo? 

A mono-repo is a single repository that contains the source code for multiple microservices. 

This approach offers several benefits, which include simplified dependency management, centralised documentation, and easier code sharing. 

With a mono-repo, developers have a holistic view of the entire system and can make changes that span multiple microservices in a single commit. But this might not be ideal in all scenarios, which can include, but aren't limited to: 

• The amount of microservices added

• The growing size of the repository

• The tooling used for build and deployments

• Bad practices leading to having a distributed monolith instead of true microservices 

• Clear physical separation of dependencies 

Working with Sitecore XM Cloud 

When you start working for the first time with Sitecore XM Cloud, you'll go through the Create an XM Cloud project from a starter template in the XM Cloud Deploy app documentation and create your repository based on GitHub - sitecorelabs/xmcloud-foundation-head.  

As you'll most likely have a docker compose environment to work locally with both the Sitecore instance and the Next.js app, this repository will propose a mono-repo approach to start with. This is because you'll be using a headless approach, the Sitecore CLI and an example of a Visual Studio solution that gets deployed to XM Cloud. 

As a developer, you might be wondering the following: 

• Can I separate my Next.js app to its own repository? 

• What if I want to directly run the Next.js app without using containers? 

• What if I don’t need a Sitecore instance locally to develop? 

• Can’t I just connect directly to XM Cloud?  

These are all valid questions. Especially if you're unfamiliar with Sitecore, you haven’t worked with containers before, and/or you need to get up to speed and deliver features.  The good news is that you absolutely can do all the above! But there are a few things to consider when adopting a multi-repo approach. 

Going multi-repo. What are the considerations? 

• Sitecore XM Cloud - Editing Hosts 

• Git submodules - A solution to add development flexibility 

Sitecore XM Cloud - Editing Hosts 

When you look at the Sitecore XM Cloud architecture, you'll realise that to support Pages and the Experience Editor, you'll need to have an “editing host”. This is an instance of the Next.js app that Sitecore can connect with to render the page and enable editing features. 

During the deployment of XM Cloud, an instance of the Next.js app will be provisioned. This will reside next to your XM Cloud environment.  

A rendering host is created under /sitecore/system/Settings/Services/Rendering Hosts. You can check, for example, /sitecore/system/Settings/Services/Rendering Hosts/Default. You'll notice the field for the Server-side rendering engine application URL is a hostname hosted under sitecorecloud.io 

This process is coupling your Next.js app to be part of your Sitecore repository to support this. But you can choose not to use the instance created by XM Cloud by using an external editing host. 

Git submodules - A solution to add development flexibility 

At Codehouse, when working on XM Cloud projects, we configure it to empower developers to use the approach they prefer. They can work independently on a separate Next.js repository, or from the Sitecore repository by using git submodules. 

When implementing git submodules, you can bring another repo to a directory within the “super” repository, which in this case is the Sitecore repo. 

Developers that want to use Docker and integrate multiple heads (Next.js apps) can use this method. But they'll need to understand the rules in using git submodules and learn most of the commands of git submodule [command]. 

One fundamental approach for all developers is that the git submodules referenced in the Sitecore repo aren't part of deployment to the environments, meaning they're not deployed to XM Cloud and are only for ease of development. 

Sitecore XM Cloud Deploy doesn't support git submodules with their GitOps feature to build and deploy the repository. 

If you want to implement git submodules or a bespoke checkout of your source code, you'll have to use your preferred CI/CD tool such as Azure DevOps. Codehouse has implemented this by using the Sitecore CLI plugin Sitecore.DevEx.Extensibility.XMCloud to deploy to Sitecore XM Cloud deploy. 

You can find more documentation here https://doc.sitecore.com/xmc/en/developers/xm-cloud/the-cli-cloud-command.html 

You can then call a command like: dotnet sitecore cloud deployment create --environment-id $SitecoreXmCloudEnvironmentId --upload --working-dir $WorkingDirectory 

What didn’t work? 

One approach we implemented (but abandoned) was to link deployment pipelines of the Next.js app and Sitecore. We did this by doing a custom checkout of the Sitecore repository having the latest changes on the Next.js app to support the embedded editing host.  

The reason was to prevent the application restart of the XM Cloud environment for updating the editing host on Sitecore. Currently, Sitecore XM Cloud Deploy doesn't distinguish changes happening to a specific part of the code. This means the Sitecore solution files or the Next.js application only update that part of the environment.

It's a known occurrence with Sitecore XP that when the application is updated there's a brief outage on restart as the new changes take effect. This is no different in Sitecore XM Cloud. By removing this deployment dependency, we're instead making use of the external editing host. This is to simplify the interdependencies between Sitecore and the heads (Next.js applications). 

Conclusion

There's no right or wrong approach in using mono-repo or multi-repo. Each has pros and cons.

For instance, a multi-repo will give a granular access control to the repository in terms of security when integrating with other systems. Additionally, there's a clear separation of responsibilities within the overall architecture, your deployment pipelines and processes within your team and project. 

Working with Codehouse 

We’re one of the most experienced Sitecore solution partners in the world and have been building Sitecore websites for over 15 years. 

If you have Sitecore or are considering it as your next digital experience platform, we want to hear from you. Get in touch when you're ready to discuss your project. 

• Read about Object Manipulation in JavaScript

• Read about Next.js in Sitecore JSS