1. Sitecore JavaScript Services SDK (JSS)

Upgrade JSS apps to JSS 22.1

Version:

Sitecore JavaScript Rendering SDK version 22.1 requires you to make some modifications to your apps.

Before you begin

This topic describes how to:

  1. Replace the import path for editing utilities (all frameworks) 

  2. Update Angular apps 

  3. Update React apps 

  4. Update Vue.js apps 

  5. Update application dependencies 

Note

To update your JSS Next.js applications, follow the detailed upgrade guide from JSS 22.0.0 to 22.1 for JSS Next.js apps instead of this topic.

Replace the import path for editing utilities (all frameworks)

We're moving all editing utilities located at @sitecore-jss/sitecore-jss/utils to the more meaningful @sitecore-jss/sitecore-jss/editing. As a result, you will need to replace the path of any import statements in your code that refer to the older location.

This change affects the following utilities:

  • ChromeCommand 

  • DefaultEditFrameButton 

  • DefaultEditFrameButtonIds 

  • DefaultEditFrameButtons 

  • EditButtonTypes 

  • EditFrameDataSource 

  • ExperienceEditor 

  • FieldEditButton 

  • handleEditorAnchors 

  • HorizonEditor 

  • isEditorActive 

  • mapButtonToCommand 

  • Metadata 

  • resetEditorChromes 

  • WebEditButton 

Warning

The older path will only continue to work until the next release of JSS. Therefore, we strongly recommend you make the necessary changes as soon as possible.

Update Angular apps

Note

Some of the steps in this section repeat the upgrade guide for JSS 21.8. Therefore, if you've already applied those changes, you do not need to repeat them here.

To update your Angular applications:

  1. Update TypeScript to ~5.2.2.

  2. Update Angular and all of its core dependencies to version 17, along with any related dependencies. The following list shows the required versions at time of release:

    • Angular main dependencies:

      "@angular/animations": "~17.3.11",
"@angular/common": "~17.3.11",
"@angular/compiler": "~17.3.11",
"@angular/core": "~17.3.11",
"@angular/forms": "~17.3.11",
"@angular/platform-browser": "~17.3.11",
"@angular/platform-browser-dynamic": "~17.3.11",
"@angular/platform-server": "~17.3.11",
"@angular/router": "~17.3.11",

    • Angular dev dependencies:

      "@angular-builders/custom-webpack": "^17.0.2",
"@angular-devkit/build-angular": "^17.3.8",
"@angular-eslint/builder": "^17.5.2",
"@angular-eslint/eslint-plugin": "^17.5.2",
"@angular-eslint/eslint-plugin-template": "^17.5.2",
"@angular-eslint/schematics": "^17.5.2",
"@angular-eslint/template-parser": "^17.5.2",
"@angular/cli": "~17.3.8",
"@angular/compiler-cli": "~17.3.11",
"@angular/language-service": "~17.3.11",

    • Other main dependencies:

      "@ngx-translate/core": "~15.0.0",
"@ngx-translate/http-loader": "~8.0.0",
"apollo-angular": "~6.0.0",
"bootstrap": "^5.3.3",
"core-js": "~3.37.1",
"tslib": "^2.6.3",
"zone.js" "~0.14.7",

    • Other dev dependencies:

      "@types/node": "~20.14.10",
"@typescript-eslint/eslint-plugin": "^7.16.0",
"@typescript-eslint/parser": "^7.16.0",
"body-parser": "~1.20.2",
"eslint": "^8.56.0",
"eslint-plugin-import": "2.29.1",
"eslint-plugin-jsdoc": "48.7.0",

    • All remaining dependencies can be left at their current versions.

  3. If you have not customized the scripts/generate-config.ts file, replace it with the 22.1 version. Otherwise, modify your file as follows:

    • In the configText prop assignment, after config[prop]?, add a toString method call followed by a trim method call, such as:

      config[prop]?.toString().trim()

    • At the end of that assignment, replace the comma before the newline character with a semicolon:

      // Before
}",\n`;

// After
}";\n`;

    Here's an example of the updated assignment suitable for JSS 22.1:

    configText += `config.${prop} = process.env.${constantCase(prop)} || "${config[prop]?.toString().trim()}";\n`;

  4. Also in the scripts/generate-config.js file, repeat step 3 for computedConfig[prop]. Here's an example of the updated assignment suitable for JSS 22.1:

    configText += `config.${prop} = process.env.${constantCase(prop)} || ${
  computedConfig[prop]?.toString().trim()
};\n`;

  5. If you have not customized the /server.bundle.ts file, replace it with the 22.1 version. Otherwise, modify your file as follows:

    • Locate the following import statement:

      import 'zone.js/dist/zone-node';

    • Replace that statement with the following:

      import 'zone.js';

  6. If you have not customized the src/polyfills.ts file, replace it with the 22.1 version. Otherwise, modify your file as follows:

    • Locate and remove the following import statements, if present:

      import 'zone.js/dist/zone-node';
import 'zone.js/dist/zone';

    • Add a new import statement as follows:

      import 'zone.js';

  7. If you have not customized the src/test.ts file, replace it with the 22.1 version. Otherwise, modify your file as follows:

    • Locate and remove any import statements containing zone.js/dist.

    • Add a new import statement as follows:

      import 'zone.js/testing';

  8. If your existing app has other customizations that might be affected by the Angular 17 upgrade, refer to the Angular 17 upgrade guide for guidance on what further changes are required.

  9. Update your application's JSS package, and install dependencies.

Update React apps

The simplification of editing support has introduced a new breaking change to the sitecore-jss-react package that requires you to make some modifications to your apps.

To update your React applications:

  1. Because ComponentConsumerProps has been removed, if you have any import statements that reference it, update them all to use WithSitecoreContextProps instead.

  2. If you have not customized the scripts/generate-config.js file, replace it with the 22.1 version. Otherwise, modify your file as follows:

    • In the configText prop assignment, add a trim method call after config[prop]?, such as:

      config[prop]?.trim()

    • At the end of that assignment, replace the comma before the newline character with a semicolon:

      // Before
}",\n`;

// After
}";\n`;

    Here's an example of the updated assignment suitable for JSS 22.1:

    configText += `config.${prop} = process.env.REACT_APP_${constantCase(prop)} || "${
  config[prop]?.trim()
}";\n`;

  3. Update your application's JSS package, and install dependencies.

Update Vue.js apps

To update your Vue.js applications:

  1. If you have not customized the scripts/generate-config.js file, replace it with the 22.1 version. Otherwise, modify your file as follows:

    • In the configText prop assignment, add a trim method call after config[prop]?, such as:

      config[prop]?.toString().trim()

    • At the end of that assignment, replace the comma before the newline character with a semicolon:

      // Before
}",\n`;

// After
}";\n`;

    Here's an example of the updated assignment suitable for JSS 22.1:

    configText += `config.${prop} = process.env.VUE_APP_${constantCase(prop)} || "${
  config[prop]?.trim()
}";\n`;

  2. Also in the scripts/generate-config.js file, repeat step 1 for computedConfig[prop]. Here's an example of the updated assignment suitable for JSS 22.1:

    configText += `config.${prop} = process.env.VUE_APP_${constantCase(prop)} || ${
  computedConfig[prop]?.trim()
};\n`;

  3. Update your application's JSS package, and install dependencies.

Update application dependencies

For your upgraded applications to work correctly, you must update dependencies.

To update your dependencies:

  1. In your existing application's package.json file, update every @sitecore-jss package to version ~22.1.

  2. Install the dependencies with the following command:

    npm install
If you have suggestions for improving this article, let us know!