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.

Tip

This section covers how to use the SXA CLI with the default user. If you want to enable a custom user to use the SXA CLI, see Use SXA CLI with a custom user.

To be able to add a theme using SXA CLI:

  • You must have sufficient permissions. You must either have the sitecore\Powershell Extensions Remoting role assigned 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>
  • From a command prompt, install node.js npm config set @sxa:registry=https://sitecore.myget.org/F/sc-npm-packages/npm/.

    Note

    This command only works in a command prompt. Do not use PowerShell. If it does not work via a command prompt, you can manually add the correct values to the .npmrc file.

  • Install Node Package Manager (NPM) globally: Use npm and the install command to install SXA CLI as a global package: npm i -g @sxa/CLI. This uses the newest CLI available.

To add a theme using SXA CLI:

  1. Download the theme boilerplate from the Sitecore myget site.

  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. Add a URL for uploading. You have three options: You can use serverUrlStrategy to dedicate a local or global strategy, or you can specify a URL via a CLI option.

    • ServerUrlStrategy: 'local': Sends files to the path for your Sitecore instance registered under serverOptions.server in the config file for Gulp tasks (ThemeRoot/gulp/config.js).

    • ServerUrlStrategy: 'global': Takes the value registered by the CLI. If SXA cannot find this path, it falls back as if it was set up to local.

    • -u, --url - <Instance URL>: upload files to the instance URL, for example -url https://sxa-instance.test. If you specify a URL this way, the tasks ignore the serverUrlStrategy property and take their value from the CLI option. For more information about CLI options, see The SXA CLI watch, (re)build, and upload tasks.

  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. You must 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. Downloads all assets. 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

Use SXA CLI with a custom user

If you do not want to use the default sitecore\admin user to upload themes through SXA CLI, you can create a separate user for this purpose.

To create a custom user that can use the SXA CLI:

  1. Open the User Editor, and create a new user.

  2. In the User Editor, assign the sitecore\PowerShell Extensions Remoting role to the user.

    Note

    In Azure environments, the sitecore\PowerShell Extensions Remoting role does not exist by default. If the role is missing, you must create it in the Role Manager.

  3. Make sure that the user has the following permissions for /sitecore/media library/Themes: Read, Write, Create, Rename, and Delete.

  4. Make sure that the \App_Config\Include\z.Feature.Overrides\z.SPE.Sync.Enabler.Gulf.config file is enabled.