Upgrade JSS apps to JSS 22.1

Version: 22.x

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:

      RequestResponse
      "@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:

      RequestResponse
      "@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:

      RequestResponse
      "@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:

      RequestResponse
      "@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:

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

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

      RequestResponse
      // Before
}",\n`;

// After
}";\n`;

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

    RequestResponse
    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:

    RequestResponse
    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:

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

    • Replace that statement with the following:

      RequestResponse
      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:

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

    • Add a new import statement as follows:

      RequestResponse
      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:

      RequestResponse
      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:

      RequestResponse
      config[prop]?.trim()

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

      RequestResponse
      // Before
}",\n`;

// After
}";\n`;

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

    RequestResponse
    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:

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

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

      RequestResponse
      // Before
}",\n`;

// After
}";\n`;

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

    RequestResponse
    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:

    RequestResponse
    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:

    RequestResponse
    npm install

Do you have some feedback for us?

If you have suggestions for improving this article,