With the introduction of SXA 9.3 we are introducing the SXA CLI. The CLI (Command Line Interface) is a command line tool that allows you to setup a theme locally and register it with SXA.
Before we start installing the CLI locally you need to make sure you have NodeJS installed on your local machine. We are using NPM (Node Package Manager) to install the CLI and all its dependencies.
The other dependency is that you have Creative Exchange Live (CEL) enabled on your site. You can do so by going to the folder “Website\App_Config\Include\z.Feature.Overrides”. There you will find a file called “z.SPE.Sync.Enabler.Gulp.config.disabled”. Remove the .disabled from the filename and you have CEL enabled.
Remove .disabled to enable Creative Exchange Live
Personally I always use the admin user with CEL but for security reason you might want to use another user.
You just need to make sure that you have sufficient permissions. You should either have the sitecore\PowerShell Extensions Remoting role assigned to the user or add the user to the “/configuration/sitecore/powershell/services/restfulv2/authorization” config node:
<configuration> <sitecore> <powershell> <services> <restfulv2> <authorization> <add Permission="Allow" IdentityType="User" Identity="sitecore\\username" /> </authorization> </restfulv2> </powershell> </sitecore> </configuration>
Install the SXA CLI
Now back to installing the CLI. First thing we want to do it to install the CLI using NPM. To do so we need to add a registry to NPM. You can do so by running this command in the Windows command prompt (or the new Windows Terminal):
npm config set @sxa:registry https://sitecore.myget.org/F/sc-npm-packages/npm/
Note: If you use the PowerShell console to register the NPM registry you will need to escape the @ character.
The correct command would be:
npm config set \`@sxa:registry https://sitecore.myget.org/F/sc-npm-packages/npm
This makes sure that NPM can find the registry where all packages labeled with @SXA are hosted.
Now it is time to install the CLI. Run the command “npm i -g @sxa/CLI” or “npm install --global @sxa/CLI” and NPM will install the CLI.
npm i -g @sxa/CLI
Now all sorts of magic start. NPM installing the CLI module and all of its dependencies. You will get some warning about outdated packages but that’s nothing to worry about at this point.
Installing the SXA CLI using NPM
Now that the CLI is installed, let’s start using it. Run “sxa register” followed by the url you want it to connect with. In my case “sxa register https://sxa93.dev.local”. This will make sure the CLI will use this url to connect with in a later stage.
sxa register https://sxa93.dev.local
Register the url and start creating a new theme
To create the theme you run “sxa new themename”. First it will ask you to confirm the the url we just registered. After that some basic information like username and password. This will be the user that CEL uses to connect with Sitecore. In my examples I will be using the sitecore\admin user.
sxa new ExampleTheme
Then the CLI will ask for the theme path. This path is relative to the standard themes path (/sitecore/media library/Themes). For this blogpost I will use “Sitecore/Example”. Typically this will be “Tenant Name/Site Name”.
Once this required information is provided the CLI ask whether you want to setup a theme config file.
At this point we are going to start configuring our theme. It will ask what the active modules are for our site.
You can choose between SearchSiteSetup, MapsSiteSetup, ThemingSiteSetup. Based on your choices the CLI will download the base themes which are required for those modules. Once the theme files are downloaded the CLI will setup the theme file and folder structure. When this is all setup you could change the url to which the theme needs to be published.
This is also the point at which the CLI has created the folder structure within Sitecore. As you can see it has not sychronized anything since we haven't made any changes. It simply created the bare folder structure
- [JS] Do you require ES6+ support(babel used)
- [JS] Do you want to compile minified file(pre-optimized-min.js)
- [JS] Do you want to upload js source files
- [CSS] Do you want to compile minified file(pre-optimized-min.css)
- [CSS] Do you want to upload css source files
You can keep all the css files on your local disk and simply use the bundled version, or upload all the CSS files to the media library.
- [SASS] Do you want to upload sass source files
The same question as earlier but now focused towards the sass files.
Now we have completed all the steps to create a new theme. But we are not ready to use it (yet). The CLI made sure all the required files are on your local disk. As part of those files there is also a package.json which lists all the required NPM modules to run the theme and Creative Exchange Live.
To install those modules we first need to go into the theme folder. Once we are there, we can simply run npm install and NPM will install all the required modules.
C:\\Projects\\SXA\\cd ExampleTheme C:\\Projects\\SXA\\ExampleTheme\\npm install
After all of this is completed. You can run “gulp” in the theme folder and start making your edits. Your theme will then compile locally and upload the compiled assets to Sitecore.
Running gulp to synchronize our theme with Sitecore
So now, with the gulp task running, whenever I make a change in my source files. For example a sass file, it will first compile that into CSS and bundle that into a pre-optimized-min.js file. That minified file will then be uploaded to Sitecore.
The results in the gulp output
And as you can see it indeed upload my changes in a minified file to my newly created theme
Voila, we have now installed the CLI, created a new theme locally and configured Creative Exchange Live to synchronize our changes (using compiled assets) into Sitecore.