With the introduction of Sitecore 10 (XM/XP) in September 2020, Sitecore introduced a new serialization system called Sitecore Content Serialization (SCS). Sitecore’s new SaaS offering Sitecore XM Cloud, which is publicly available since July 2022, also uses this Sitecore Content Serialization (SCS) system. SCS is a system for serializing, sharing, and deploying content items, as well as keeping them in version control. It’s one of the features any developer needs to learn while working on Sitecore XM Cloud implementations.
This blogpost is part of short series on ‘XM Cloud – Sitecore Content Serialization (SCS) Best Practices‘
- XM Cloud – Sitecore Content Serialization (SCS) Best Practices – File System
- XM Cloud – Sitecore Content Serialization (SCS) Best Practices – Include naming
- XM Cloud – Sitecore Content Serialization (SCS) Best Practices – Module Explorer
Having worked with SCS for the last 2 years on multiple Sitecore Headless projects (in which I both used Nextjs/JSS as well as the ASP.NET Core Rendering SDK), I thought that it’s time to share some of ‘MY’ best practices. In today’s blog-post we’re going to look at the filesystem setup, which I think is an important topic to discuss.
To Helix or not to Helix
About 3 months ago, Sitecore came out with an ‘Update on Development Practices for Headless Projects’. In there the following was stated:
It is important to note that while we are not endorsing Helix for headless projects, for traditional implementations based on Sitecore 10 and earlier versions, Helix remains the recommended practice. The Helix guidelines have proven to be a valuable resource for building scalable, maintainable, and modular solutions, and we will continue to support their use in these contexts.
So for Headless projects Sitecore is NOT endorsing it, but for more traditional implementations IT IS the recommended practice. Sitecore therefore also setup some XM Cloud recommened practices. From these recommended practices in my opinion the piece on serialization is missing at the moment. Let’s have another look before I dive in into what this blogpost is finally about.
Sitecore’s XM Cloud uses SXA Headless in order to accelerate website creation and setup on XM Cloud by establishing a structured framework and common patterns for seamless multisite configuration, content sharing, and reusability. SXA however follows the Sitecore Helix principles that contain development process recommendations for building, testing, extending, and maintaining Sitecore implementations. One of the Helix principles is that each module has a separate location in the content tree. I think we can apply this as well on the filesystem for serialization setup, since we’re also maintaining this while developing our own SXA modules for our custom templates, branches, renderings etc… Let’s have a look at what I think a best practice is.
Serialization filessystem setup
When you’re working on a Sitecore XM Cloud project, your repository will inherit from the Sitecore XM Cloud Foundation Head repository. Looking at that /src folder in that repo, we can directly already see a *.module.json configuration, which is a Sitecore Content Serialization (SCS) module configuration file. As you can see there’s the /items folder as well. When your XM Cloud project repo is generated it’s generated from the above mentioned base repo from Sitecore. What I’m missing there is some kind of good structure which I think is what we need. Here we go.
Introduce Helix layers
In your project do the following in your /src/items folder:
- Create a Foundation folder
- Create a Feature Folder
- Create a Project Folder
So now when you’re working on either your Foundational architecure or working on a Feature called BasicContent, you’ll end up with a structure like this:
- \src\items\Feature\BasicContent
Each SCS module.json file should belong and be moved to the specific Feature (or Foundation or Project) it belongs to. Maintain the naming convention of your Module in the *.module.json name. So for the above we’ll end up with:
- \src\items\Feature\BasicContent\BasicContent.module.json
The serialized items for this module will then be serialized into the following folder:
- \src\items\Feature\BasicContent\items
I do know that you’ll end up with twice the name of ‘items’ in your path, but it’s way more structured and your .yml files won’t end up all over the place. In case you might want to change the first ‘items’ for example to ‘serialization’ then you can adjust it yourself. In case you want to have the second ‘items’ adjusted to ‘serialization’, then you have to adjust the following setting in the root’s sitecore.json file:
- “defaultModuleRelativeSerializationPath”: “items” (default in an XM Cloud project)
- “defaultModuleRelativeSerializationPath”: “serialization” (adjusted)
I would NOT advise to do the above! Since probably all XM Cloud projects will use the ‘items’ naming convention. Just wanted to mention that it CAN be done.
Adjust Sitecore.json
The sitecore.json file in the repo’s root directory needs to be adjusted so SCS can scan all the modules on the filesystem. Make the following change to the sitecore.json:
And that’s it for now! In my next blogpost I’ll try to explain the importance of doing proper ‘Include’ naming in your SCS modules and will continue on this ‘XM Cloud – Sitecore Content Serialization (SCS) Best Practices series’. Hope this first one was helpful!
Happy Sitecore-ing!
–Robbert
