Skip to main content

Add a theme using SXA CLI

Abstract

Automate theme creation for SXA sites.

SXA CLI is a useful command line tool to automatize tasks for an SXA project. This topic describes how to add a theme using SXA CLI. This can be convenient if you want to have more control over your assets and use a version control system, such as Git.

Before you can add a theme using SXA CLI make sure to install node.js and to install Node Package Manager (NPM) globally:

  1. Open a command prompt terminal and install the registry:

    npm config set @sxa:registry=https://sitecore.myget.org/F/sc-npm-packages/npm/

  2. Use npm and the install command to install SXA CLI as a global package: npm i -g @sxa/CLI.

To add a theme using SXA CLI:

  1. Download the theme boilerplate.

  2. Go to Website\App_Config\Include\z.Feature.Overrides and enable the z.SPE.Sync.Enabler.Gulp.config.disabled file.

  3. Switch to the downloaded theme boilerplate folder.

  4. Run sxa init.

  5. Update the config file for Gulp tasks.

    Go to: ThemeRoot/gulp/config.js and for serverOptions.server enter the path to the Sitecore instance.

  6. If you use Creative Exchange, skip this step.

    Open ThemeRoot/gulp/serverConfig.json and enter:

    • serverOptions.projectPath - the path to the project where the theme is placed.

    • serverOptions.themePath - the path to the basic theme folder from the project root.

  7. Open the Theme root folder with the command line.

  8. Run npm i.

  9. Your new theme is now available. Make sure to assign your new theme to your site:

    Go to Sitecore/Content/<tenant>/<site>/Settings, and in the Site Configuration settings, in the Compatible themes field add your new theme to the Selected field. Now you can select the theme as your site's current theme.

The following table describes the most important commands for using SXA CLI in your theme setup:

Command

Alias

Description

sxa init

sxa i

Downloads all necessary files for compatibility with the Creative Exchange Live Mode. This process downloads the missing files and does not replace existing files.

sxa new <ThemeName> --url <url>

sxa n

Runs the create theme pipeline and stores the theme both locally and in Sitecore. Use this command to create a new theme for your site.

You can add to the instance where the theme should be created. If you want to create the theme in the currently registered Sitecore instance, you don't have to specify the URL.

sxa config

sxa c

Sets up the theme variable by answering a list of questions. Use this command to change the theme setup.

sxa register <url>

sxa reg

Globally registers an instance of Sitecore URL.

sxa get-url

sxa g

Checks the currently registered URL.

sxa build [taskName]

sxa b

Builds the theme assets based on the current theme configuration. For available tasks, go to The SXA watch, build, and upload tasks.

sxa upload [taskName]

sxa u

Uploads the theme assets based on the theme configuration. For available tasks, go to The SXA watch, build, and upload tasks

sxa watch [taskName]

sxa w

Watches theme asset changes and uploads the modified files automatically. For available tasks, go to The SXA watch, build, and upload tasks

Can be configured with sxa config command.

sxa rebuild [taskName]

sxa r

Rebuilds and uploads theme assets. For available tasks, go to

The SXA watch, build, and upload tasks