Upgrade JSS apps to JSS 22.3

Version: 22.x

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

Before you begin

If you haven't already done so, upgrade your app to JSS 22.1.
Upgrade Node to version 22 or later.
Familiarize yourself with the JSS 22.3 release notes to ensure you understand the implications of upgrading.

This topic describes how to:

Note

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

Update Angular apps

Upgrading an Angular app to JSS 22.3 requires you to make multiple changes. Steps 1-6 of this process can be summarized as follows:

Updating the JssContextService and all references to it, because some of the sitecore-jss-angular components now rely on the application state.
Updating the initialization of i18n to improve performance while fetching Dictionary Data for SSR.

To update your Angular applications:

In src/app/jss-context.service.ts, do the following:

Locate the following import statement:

RequestResponse

import { LayoutServiceData } from '@sitecore-jss/sitecore-jss-angular';

Replace that statement with the following:

RequestResponse

import { LayoutServiceData, JssStateService } from '@sitecore-jss/sitecore-jss-angular';

Delete the BehaviorSubject import.
Delete the following field:
RequestResponse
```
state: BehaviorSubject<JssState>;
```

Add the following get statements and replace the constructor as shown:

RequestResponse

get state() {
  return this.stateService.state;
}
get stateValue() {
  return this.stateService.getStateValue();
}
constructor(protected transferState: TransferState, protected layoutService: JssLayoutService, protected stateService: JssStateService<JssState>) {
}

Replace all instances of this.state.next with this.stateService.setState.
Replace all instances of this.state.value with this.stateService.getStateValue().

In src/app/jss-context.server-side.service.ts, do the following:

Add the following import statement:

RequestResponse

import { JssStateService } from '@sitecore-jss/sitecore-jss-angular';

Delete the JssDataFetcherService import.

Modify the constructor to pass JssStateService and propagate it to the base class. For example:

RequestResponse

constructor(
  protected transferState: TransferState,
  protected layoutService: JssLayoutService,
  protected stateService: JssStateService<JssState>,
  // this initial state from sitecore is injected by server.bundle for "integrated" mode
  @Inject('JSS_SERVER_LAYOUT_DATA') private serverToSsrState: JssState
) {
  super(transferState, layoutService, stateService);
}

In app.module.ts, remove the HttpClient import statement.

Here's an example of the updated file suitable for JSS 22.3:

RequestResponse

TranslateModule.forRoot({
  loader: {
    provide: TranslateLoader,
    useFactory: (transferState: TransferState) =>
      new JssTranslationClientLoaderService(new JssTranslationLoaderService(), transferState),
    deps: [TransferState],
  },
}),

In app.server.module.ts, import TransferState.

Here's an example of the updated file suitable for JSS 22.3:

RequestResponse

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

TranslateModule.forRoot({
  loader: {
    provide: TranslateLoader,
    useFactory: (
      ssrViewBag: {
        [key: string]: unknown;
        dictionary: { [key: string]: string };
      },
      transferState: TransferState
    ) => new JssTranslationServerLoaderService(ssrViewBag, transferState),
    deps: ['JSS_SERVER_VIEWBAG', TransferState],
  },
}),

In app/i18n/jss-translation-server-loader.service.ts, do the following:

Inject TransferState.
Make sure dictionary data is set in transferState.

Here's an example of the updated file suitable for JSS 22.3:

RequestResponse

import {
  Inject,
  Injectable,
  makeStateKey,
  StateKey,
  TransferState,
} from "@angular/core";    
import { DictionaryPhrases } from "@sitecore-jss/sitecore-jss-angular";
...
    
export const dictionaryStateKey: StateKey<DictionaryPhrases> = makeStateKey<DictionaryPhrases>(
  'dictionary'
);

export class JssTranslationServerLoaderService implements TranslateLoader {
  constructor(
    @Inject('JSS_SERVER_VIEWBAG')
    private serverViewBag: { [key: string]: unknown; dictionary: DictionaryPhrases },
    private transferState: TransferState
  ) {}

  getTranslation(_lang: string) {
    const dictionary = this.serverViewBag.dictionary;

    this.transferState.set(dictionaryStateKey, dictionary);
    ...
  }
}

In app/i18n/jss-translation-client-loader.service.ts, do the following:

Inject TransferState.
Check for dictionary data in transferState and use it if available and provided by the server.

Here's an example of the updated file suitable for JSS 22.3:

RequestResponse

import { dictionaryStateKey } from './jss-translation-server-loader.service';
import { Injectable, TransferState } from '@angular/core';
import { TranslateLoader } from '@ngx-translate/core';
import { DictionaryPhrases } from '@sitecore-jss/sitecore-jss-angular';
import { EMPTY, Observable, of } from 'rxjs';
import { JssTranslationLoaderService } from './jss-translation-loader.service';
import { dictionaryStateKey } from './jss-translation-server-loader.service';

@Injectable()
export class JssTranslationClientLoaderService implements TranslateLoader {
  constructor(
    private fallbackLoader: JssTranslationLoaderService,
    private transferState: TransferState
  ) {}

  getTranslation(lang: string): Observable<DictionaryPhrases> {
    const dictionary = this.transferState.get(dictionaryStateKey, null);
  
    if (dictionary) {
      return of(dictionary);
    }
    ...
  }
}

In the root .gitignore file, add a rule for .angular if you haven't already done so.
Replace the contents of src/environments/.gitignore with the following if you haven't already done so:
RequestResponse
```
*
!.gitignore
```

In package.json, update the following devDependencies:

RequestResponse

"@types/node": "~22.9.0",
"@typescript-eslint/eslint-plugin": "^8.14.0",
"@typescript-eslint/parser": "^8.14.0",
...
"typescript": "~5.4.0",

In src/tsconfig.app.json, remove the following from compilerOptions:
RequestResponse
```
"types": []
```
Repeat step 10 for src/tsconfig.server.json.
In tsconfig.json, add "types": ["node"] above typeRoots, such as:
RequestResponse
```
...
"types": ["node"],
"typeRoots": ["node_modules/@types"],
...
```
If you want to break the config and generate-component-factory into the new plugins architecture, do the following:
- Copy the plugin files from the Angular template to your app's /scripts/config and /scripts/generate-component-factory directories.
- Import ./scripts/config and ./generate-component-factory in the scripts/bootstrap.ts file.
- Copy the scripts/generate-plugins.ts file from the Angular template and import it in the bootstrap.ts file.
Here's an example of the updated bootstrap.ts file suitable for JSS 22.3:
RequestResponse
```
/*
   PLUGINS GENERATION
*/
require("./generate-plugins");

/*
  CONFIG GENERATION
*/
require("./generate-config");

/*
  COMPONENT FACTORY GENERATION
*/
require("./generate-component-factory");
```
Update your application's JSS package, and install dependencies.

Update React apps

To update your React applications:

In .eslintrc, set the ecmaVersion to 13, as shown in the following example:

RequestResponse

"ecmaFeatures": {
  "jsx": true
},
"ecmaVersion": 13,
"babelOptions": {
  "presets": ["@babel/preset-react"]
}

Update Vue.js apps

To update your Vue.js applications:

In package.json, the following dependencies are no longer required and can be removed:
- @vue/server-renderer
- @vue/compiler-sfc

Update the following packages to the stated versions:

Table 2.

Package	New version
`vue`	`^3.5.12`
`@vue/apollo-option`	`^4.0.0`
`@vue/apollo-ssr`	`^4.0.0`

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

Update the Node headless SSR Experience Edge app

To update your Node headless SSR Experience Edge app:

Update the following packages to the stated versions:

Table 3.

Package	New version
`@types/node`	`^22.9.0`
`typescript`	`~5.6.3`

Update the Node headless SSR proxy app

To update your Node headless SSR proxy app:

Update the following packages to the stated versions:

Table 4.

Package	New version
`@types/node`	`^22.9.0`
`typescript`	`~5.6.3`

Update application dependencies

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

To update your dependencies:

In your existing application's package.json file, update every @sitecore-jss package to version ~22.3.
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,