1. Sitecore JavaScript Services SDK (JSS)

Upgrade JSS apps to JSS 21.6

Version:

Sitecore JavaScript Rendering SDKs version 21.6 brings changes to JSS packages, other NPM dependencies, and some environment variables.

Before you begin

This topic shows you how to:

  • Upgrade dependencies and environment variables in React and Vue apps.

  • Upgrade JSS Next.js apps to JSS 21.6.

  • Upgrade JSS Angular apps to JSS 21.6 and Angular 16.

Upgrade dependencies and environment variables in React and Vue apps

Upgrading your applications based on JSS templates requires upgrading your dependencies and replacing some environment variable names.

To upgrade your applications:

  1. In your package.json file, update every @sitecore-jss dependency to use the ~21.6.0 version.

  2. Rename your application's JSS_APP_NAME environment variable to SITECORE_SITE_NAME.

  3. If your application is a React or Next.js app, update the @types/react dependency to version ^18.2.22.

  4. In a shell, install/update dependencies in your app by running the following command:

    npm install

Upgrade JSS Next.js apps to JSS 21.6

In JSS 21.6, Sitecore refactored some services and configurations used by Next.js applications.

To upgrade JSS Next.js apps:

Upgrade JSS Angular apps to JSS 21.6 and Angular 16

In JSS 21.6, the Angular template has been updated to use Angular 16.

Before you begin

  1. In the package.json file:

    • Upgrade dependencies and development dependencies to Angular 16.

    • Upgrade the typescript package to version ~4.9.5.

    • To preserve the server artifacts path JSS conventions require, update your build:server and postbuild:server scripts. In the package.json file, update the scripts to:

      “build:server”: “cross-env-shell ng run <your-app-name>:server:production --output-path=$npm_package_config_buildArtifactsPath --output-hashing=none”,
"postbuild:server": "move-cli ./dist/main.js ./dist/server.bundle.js"

    • To replace the deprecated --deploy-url option with --base-href ng build option, update the build:client script to:

      "build:client": "cross-env-shell ng build --base-href $npm_package_config_sitecoreDistPath/browser/ --output-path=$npm_package_config_buildArtifactsPath/browser/",

    • Remove the overrides workaround.

  2. In a shell, install/update dependencies in your app by running the following command:

    npm install

  3. In the angular.json file:

    • Update the allowedCommonJsDependencies configuration.

    • In the server.options configuration, remove the outputPath property and add the outputHashing property with the value  none. The final options needs to contain the following:

        "options": {
    "outputPath": "dist/server",
    "main": "server.bundle.ts",
    "tsConfig": "src/tsconfig.server.json",
    "deleteOutputPath": false,
    "outputHashing": "none"
 }

  4. In the .eslintrc file, replace the deprecated @angular-eslint/ng-cli-compat ESLint rules with @angular-eslint/recommended rules, as shown in this diff , and remove other outdated rules.

  5. In the /src/app/app.module.ts, make the following changes:

    • Remove the BrowserModule and TransferState import from the @angular/platform-browser package and add instead the following import statement:

      import { APP_ID, NgModule, TransferState } from '@angular/core';

    • Remove the NgModule import from the @angular/core package.

    • In the NgModule decorator, in the imports set, remove the BrowserModule.withServerTransition({ appId: 'my-app' }) import.

    • In the NgModule decorator, in the providers set, add the following:

       // The token is needed in cases when multiple applications are bootstrapped on a page
{ provide: APP_ID, useValue: 'my-app' },

  6. Consult the Angular 15 to 16 upgrade guide for your Angular-specific upgrade needs and implement the changes in your application customization.

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