1. Upgrade Guide for SXA 10.5

Themes

This guide is designed to assist customers who are upgrading their SXA themes from version 10.2 to 10.5. It provides step-by-step instructions and important considerations to ensure a smooth transition to the latest version.

For more information about SXA themes, refer to the the SXA themes.

Backup

Before upgrading, make sure to create a full backup of the theme, which is the sass/ directory and all custom components.

Preparing package.json

It is recommended to use the following `package.json`:

{
    "name": "@sitecore/sxa-theme",
    "version": "10.5.0",
    "description": "SXA Theme",
    "keywords": [
        "SXA",
        "Creative Exchange Live",
        "Sitecore Experience Accelerator",
        "Gulp",
        "Theme"
    ],
    "scripts": {
        "postinstall": "node ./gulp/config.js",
        "gulp": "./node_modules/gulp/bin/gulp.js",
        "doc": "rimraf ./jsdoc/ | jsdoc -c ./node_modules/@sitecore/sxa-celt/jsdoc.json"
    },
    "author": "Sitecore Corporation A/S",
    "homepage": "https://doc.sitecore.com/xp/en/developers/sxa/104/sitecore-experience-accelerator/add-a-theme-using-sxa-cli.html",
    "license": "https://doc.sitecore.net/~/media/C23E989268EC4FA588108F839675A5B6.pdf",
    "main": "index.js",
    "dependencies": {
        "@babel/polyfill": "^7.12.1",
        "axios": "^1.8.1",
        "chalk": "^5.3.0",
        "glob": "^11.0.1",
        "gulp": "^5.0.0",
        "gulp-autoprefixer": "^9.0.0",
        "gulp-babel": "^8.0.0",
        "gulp-cli": "^3.0.0",
        "gulp-concat": "^2.6.1",
        "gulp-eslint": "^6.0.0",
        "gulp-filter": "^9.0.1",
        "gulp-if": "^3.0.0",
        "gulp-prompt": "^1.2.0",
        "gulp-rename": "^2.0.0",
        "gulp-sourcemaps": "^3.0.0",
        "gulp-upload": "^1.0.0",
        "gulp-watch": "^5.0.1",
        "gulp.spritesmith": "^6.13.1",
        "inquirer": "^12.4.2",
        "jsdoc": "^4.0.4",
        "path": "^0.12.7",
        "rimraf": "^6.0.1",
        "rollup-plugin-node-polyfills": "^0.2.1"
    },
    "devDependencies": {
        "@babel/cli": "^7.26.4",
        "@babel/core": "^7.26.9",
        "@babel/plugin-transform-runtime": "^7.26.9",
        "@babel/preset-env": "^7.26.9",
        "@babel/register": "^7.25.9",
        "@sitecore/sxa-celt": "10.5.0",
        "eslint": "^9.21.0",
        "gulp-tap": "^2.0.0"
    },
    "overrides": {
        "form-data": "2.5.6",
        "lodash": "^4.17.21"
    },
    "babel": {
        "presets": [
            "@babel/env"
        ],
        "overrides": [
            {
                "sourceType": "unambiguous"
            }
        ]
    }
}

Steps Before Installation

  1. Back up the existing package.json and theme files.

  2. Update the existing @sitecore/sxa-celt entry in devDependencies to 10.5.0 and the gulp entry in dependencies to ^5.0.0. Preserve other project-specific dependencies, scripts, and configuration.

  3. Run the following command:

    npm install

Existing Sass Compatibility

Updating npm dependencies does not automatically migrate existing Sass sources. Build the theme with the SXA 10.5 tooling, review compilation errors and deprecation warnings, and update custom Sass where required.

After the Upgrade

  1. Run the following command:
npm run gulp -- buildAll
  1. Confirm the command finishes without errors.
  2. Upload the generated assets to the correct Sitecore theme.
  3. Publish the updated theme items to the delivery database.
  4. Open the SXA website and confirm the styles display correctly.
If you have suggestions for improving this article, let us know!