Sitecore Helix Tips and Recommendations

Helix is a series of architectural patterns that Sitecore recommends as best practices for any projects developed in the platform. (You can learn more about the Helix architecture in Sitecore's documentation.) In this blog I will briefly describe the architecture and the tools we've used to develop our projects using the Helix architecture.

Helix is a 3-layered architecture, where dependencies are unidirectional (higher layers depend on lower layers), and each group of components that change together are packaged into individual modules. The 3 layers (from top to bottom) in Helix are Project, Feature, and Foundation. Modules in the lower layers are more stable than the ones in the upper layers, so unstable modules can depend on more stable modules. Except for the Foundation layer, there are no dependencies among modules in the same layer. Most of the work is done on the Feature layer, where all business modules are implemented. Foundation layer contains all the foundation libraries for the project. And finally, the Project layer contains the site definition modules, with assets, page and content type templates that depend on the Feature modules.

The following tips and recommendations are based on real life projects developed by Oshyn using this new architecture.

Consider your Sitecore installation as part of the "environment"

When you install and configure an empty Sitecore instance, it should be a process you do only ONCE. That means that you shouldn't have in your code repository any of the files already included in the default Sitecore installation. Make sure you NEVER copy to your installation the main Web.config file (set the Build Action to "None" in Visual Studio), since the Web.config file included with Sitecore should never be modified at all. You might need to copy the Web.config file under the Views folder, but do it only once, and then set it to Build Action "None" in your module projects. Never perform any direct modifications and/or overwrite the Sitecore.config file. To overwrite, change, delete or add new Sitecore configuration values, use .config patch files. For each module project in your Helix solution, put your .config patch files under App_Config/Include/<Layer Name>, in a folder with a name of the module project (e.g. if your Feature module project is called SomeClient.Feature.Navigation, then create a folder with that same name under App_Config/Include/Feature, and put all the .config files specific for that module there).

Use XML transformations in your deployment process

By default, MSBuild applies XML transformations only to the Web.config file. This is not useful for Sitecore, since the Web.config file shouldn't be modified ever, and the bulk of the configurations reside in the Sitecore.config file and associated .config patch files. If you are doing deployments using MSBuild, Microsoft provides a NuGet package / Visual Studio add-on combination called SlowCheetah. SlowCheetah's Visual Studio add-on allows you to easily create an XML transformation file for ANY .config file in your project. And the NuGet package allows you to apply the configuration transformations in your local computer and also on an external build server. So for certain environments where you need very specific configuration values for a same .config patch file, you can create new Visual Studio configurations, and create transformation files for each configuration for that specific .config patch file. However, newer server deployment solutions such as Octopus Deploy or Microsoft's own Azure DevOps now provide XML transformations for any config file without the need for SlowCheetah and VS configurations. These solutions allow you to configure multiple environment deployments, specific variables, and config transformations for each environment.

Use tools to set up your Helix-based solution

Setting up a Helix solution with its many projects can be a very tedious and error-prone process. Fortunately, there are tools out there to help you out with these tasks. To start, download and install Node.js, so you have access to the npm package manager. Then install the Yeoman scaffolding tool using the following npm command (it will install Yeoman globally, so it can be used on any folder):

npm install -g yo

Next, install the generator-helix tool using the following npm command  (it will also install it globally):

npm install -g generator-helix

Once you have these tools in place, it is very simple to create a new Helix-based solution. Just create the root folder that will contain the solution, change to that folder, and execute the following command:

yo helix

This will show you a series of prompts, and when finished, it will create the Visual Studio solution and general folder structure in the filesystem. To add module projects to the solution, in the same project's root folder execute the following command:

yo helix:add

This will show you a series of prompts (including layer, naming prefix, and need of Unicorn serialization), and when finished, it will create the module Visual Studio project, and add it to the general solution. Be aware that the generated projects will be almost completely blank, only with basic system references. You will still need to manually add the required NuGet packages for Sitecore references, MVC references, and other dependencies required for your module's functionality.

For more information about the generator-helix tool, please refer to Helix Generator.

Use serialization carefully

Tools such as Unicorn or Hedgehog's TDS used for Sitecore item serialization can be very useful for synchronizing Sitecore data among different environments, without the use of packages. These tools serialize items to files, and those files can be checked into a repository (Git or similar), so they can be deployed to any server using a build server or deployment tool.

Infrastructure items, such as Templates, Renderings, Layouts, Placeholder Settings, Workflows and other settings items outside the Content item, should be serialized. This ensures that everything that a module needs will be deployed to all environments. However, be careful with content (anything under the Content item and under the Media Library item), since editors in environments such as QA, Staging and Production will be constantly doing changes that might get overwritten with synchronizations. You might want to synchronize some content in your development environments. However, for other environments, use Sitecore package import and export.