Set up leprechaun code generation with Sitecore XM Cloud Starterkit

Hi Sitecorians,

It has been amazing learning year so far and with the change in technology and shift of the focus on frontend frameworks and composable products, it has been market demand to keep learning and exploring new things.

Reasons behind this blog

Today's topic is something that was in my draft from April-May, and I always thought that there is already a good documentation out there for Leprechaun and a blog post is not needed, Until I realized that there was so many of us facing same kind of issues and same kind of problems and spending same amount of time, That is where I thought, if I could write something which can reduce that repetitive troubleshooting time, That would really help the community.

1)  In a project environment, if we get into some configuration issues, we resolve them, we make sure we are not blocked and continue, but if you think same issue, same step and same scenario will come to other people, so if we can draft it online, it will help other people

2) I was aware about point-1 but I always thought with standard leprechaun documentation, everyone will be able to get it working and hence I never drafted my learnings and issues which I run into and steps I performed to resolve them until when lot of people were asking the same question on the floor, in different team who are configuring leprechaun, or over the slack channel, and that is where I strongly thought to draft those steps and learnings and put it online for people to refer to reduce the troubleshooting time,

3) I already drafted common troubleshooting that one will need if you are working with Sitecore XM Cloud starterkit XM Cloud - SXASTARTER Kit Setting up Leprechaun Exited with Code 1 Error (daivagnananavati.blogspot.com)  around in May, But I still did not considered steps required to configure leprechaun before troubleshooting it and I always still thought, People will be able to configure it and did not find a value to write them down.

4) But I was wrong, because only troubleshooting steps are not connecting the dots, I was still replying to same questions which I was getting from the community and from team members around, that means there was still a need of step-by-step guide of configuring leprechaun, and that is where I thought, it is definitely worth putting the steps and guide in place to save many hours of work people are doing in same repetitive manner and getting stuck in same questions.

And that is the inspiration behind this blog. and I also did a webinar on it to show what is the step-by-step guide to configure leprechaun for code generation. (Video is attached at the end of this blog)

What is Leprechaun & Why we should use it? 

I believe there is a strong awareness about it from the community and the GITHUB link of Leprechaun.CLI from Ben Lipson is just great to get started and understand things around it, so I will not focus on that but will jump directly to minimum steps involved to start generating code from it.

Steps

Step -1:  Install Leprechaun

Very first step is open windows PowerShell and go to your root directory where you have .config folder (or where your dotnet manifest file), If you are using XM Cloud starter kit, you will already have .config directory in your root project, so go to the directory inside which you have .config directory and fire below command. 

    dotnet tool install --no-cache Leprechaun.Cli

After executing this command, you will see success message that it was installed successfully, like below.                 

Once, it is installed go into .config directory and open dotnet-tools.json file and verify that the file is updated with leprechaun tool entry, that means your step-1 is finished properly.

NOTE: If you see a success message like above image but still do not see the entry in dotnet-tools.json file, Make sure to correct your path, it could be you might have installed it globally and .config was created elsewhere in which you fired the command, if you have correct path, The entry will made to this file.

Step-2: Download Leprechaun.config file & CodeGen files & modify it.

Download the file from here, you will need to modify it to suite your need and your structure, I have created a sample file which you can download from my GIST here, which has all modifications which are required.

Note - Best practice is to put the leprechaun.config file on the same level as your working directory or where your Sitecore.json file and .config folder is residing, but you are not limited to it, you can put it anywhere, but in that case, you will need to make sure all path inside that file is reflecting it too.

Because the paths in leprechaun.config are always relative to $(configDirectory) (configDirectory is the full path to the directory containing the root leprechaun config file being used)

Let's discuss the modifications you will need to do.

1) Once you download the file, first thing you will need to check is the import attribute on 

     <configurations import="**\*.module.json">

This path will differ depending on where your Leprechaun.config is and where is your module.json file, the import path will vary depending on that.

In my example I am using default start kit structure, so my module files are directly under src folder.

If this path is not configured right, you will end up with one of the Issue No. 4 of Step-4 below (end of this blog I have drafted some frequent issues that might come due to misconfigurations)

2) Second thing is giving the name to the configuration tag like below 

 <configuration name="LeprechaunDemo.Base" abstract="true">

Above name attribute should exactly match with @extends attribute of leprechaun configuration instruction in your module.json file, I have drafted further details of it in Step-3 below.

If you have misconfigured this, you will end getting Issue No.-2 (Point-2 from below list of issues I have given at bottom of the blog)

3) Update the scripts and output file attributes, scripts attribute means which code generation file you want leprechaun to use, you have to specify that path, and output means where you want leprechaun to output the generated file

I am using the type of script code generator created by David Ly for which PR is already out against Lerepchaun, but you can use other types available there as well.

Here is how my configuration node look like, and I will also show you the file structure so you can relate with the paths.

<configuration name="LeprechaunDemo.Base" abstract="true">

    <codeGenerator scripts="$(configDirectory)/CodeGen/JssTypeScript.csx"

                  outputFile="$(configDirectory)\src\sxastarter\.GeneratedTypeScriptModel\$(layer).$(module).model.ts" />

</configuration>

Make sure again you enter correct path, else you might get file not found exceptions, but in above "CodeGen" is a folder in which my JssTypeScript.csx file is residing. 

Below is the file system structure look like.

Now it is time to update module.json file so that our configurations which we did can start reading them.

Step-3: Update module.json file with leprechaun node

Because leprechaun does not need live Sitecore connection to generate your model, and it only needs persisted  *.yml files, Let's put instructions in the module.json file of your choice for which you want to generate the code, it can be your typescript model, it can be model for your templates to be used in custom resolvers, choice is yours.

So, here I am interested in generating typescript model and hence I am giving configuration of leprechaun in my DataSource template module which I already have, here is a my datasource.feature.module.json look like

In above configuration, there are two major instruction that you should configure very carefully and understand.

1) @extends - This is the name attribute of the <configuration tag of leprechaun.config (will show it in a while), That means the name attribute inside <configuration tag of leprechaun.config and @extends value should match exactly for leprechaun to work, See below image

2) @name - This should match with your {Layer}/{Module} path, Meaning, in Sitecore if you have different layers like Feature / Foundation / Project and inside that you have a module, and in which all templates are residing 

So, when you run serialization, it will create those physical yml files using those paths, This Name configuration is responsible to match that, whatever the name you give, it should be valid "path" yml for serialization.

For instance, in above example in @name, if I give anything other than Feature.LeprechaunDemo, it will not work and give me error because it will not be able to find any items on that path because it only and only needs Feature.LeprechaunDemo as a name because that is where my items are in Sitecore and all yaml files which got serialized have those paths in it.

Step-4: Run Leprechaun command.

Leprechaun command can be run in two ways.

1) Running it from the command prompt.

Go to the directory where you have configured leprechaun (your $configDirectory) and fire below command.

dotnet leprechaun /c "<<Path where your leprechaun config is>>\Leprechaun.config"

If everything configured fine you will see a success message that model was generated successfully like below 

2) Include it as a part of the build process, so at the time of build it will run leprechaun.

You can create .wpp file in your project if you would like to run and generate these models as a part of the build process, it runs the same above command, configuration you will be putting is like below.

<Target Name="Leprechaun">  
   <Exec Command="dotnet leprechaun /c <<Path where your leprechaun config is>>\Leprechaun.config"/>  
</Target>  

Step-5: Troubleshoot: You will come across common issues before you get it working.

I have drafted some common issues, that you might be running into when working.

With Sitecore XM Cloud Starter kit, there are below two issues which might come.

1) One of it is "Leprechaun runs fine but it does not generate any model files",

2) If you run from the build process, you might also get "Exited with Code 1" error

Solution for both above is drafted here XM Cloud - SXASTARTER Kit Setting up Leprechaun Exited with Code 1 Error (daivagnananavati.blogspot.com)  , This is because somehow in user.json file, All environments are not updated with "authority" attribute and it's endpoint, to resolve this refer above link, it has everything you need to know.

Other Common Issues Might You Run Into

1)  Missing expected 'path' attribute on 'include' node while processing: <include name="Templates" />

This is because if you have downloaded the leprechaun.config file from the GITHUB link, On the line no. 102 it is missing "Path" attribute, Giving a proper path like below. 

<include name="Templates" path="/sitecore/templates/$(layer)/$(module)" />

NOTE: You can use my GIST here directly if you want to use that file and change it, feel free to use that, it has all the modifications.

2) There is an extend inheritance loop, or a container extending a nonexitstant container name.

This is again a mismatch in the extends property in module.json and the name of the <Configuration node, make sure leprechaun.config file configuration name and @extend is matching and other string values are just fine.

3) Item data was null for the provided treenode.

This signifies that serialized data on the disk and your module.json configuration are not matching, or either it is out of data, basically that means either something was renamed in Sitecore and synced for which the leprechaun configuration in module.json file was not updated, Double check that and see those things match.

Example can be, you renamed your module name like from demo to demo1, so on physical disk when you serialize things. It will now use demo1 in the path, so leprechaun.config should also change to reflect that name instead of demo. 

4) Loaded metadata with 0 configuration (0 total templates), No modules are being found by configurations.

This is because in your leprechaun.config file the import attribute is having a wrong path and hence leprechaun is not able to find any module.json on that path, Plese check and correct the path in following node. 

<configurations import="**\*.module.json"> of leprechaun.config , this path depends on your repo structure 

Conclusion & Some Take Aways.

1) Leprechaun does not need connection with Sitecore.

2) Leprechaun.config files(s) is always relative to $(configDirectory) (configDirectory is the full path to the directory containing the root leprechaun config file being used)

3) No need to check in the generated model files, if you have set up leprechaun to run it with build, it will help you to avoid those merge conflicts in auto generated files.

4) You can have multiple leprechaun config if you would want to have a separate model generated and different code generation to be used, Example can be for my DataSource template I want to generate type script model and for my page templates i might want to generate C# models.

I did conduct a training session on these configurations, you can refer to below webinar too for further learning and understandings.

With this blog, I hope to save some troubleshooting and configuration time you might run into.

Feel free to buzz me or comment or find me on social media and buzz or connect for any kind of conversations.

Special thanks to David Ly for creating this type script code gen file and Ben Lipson for leprechaun tool.