Sitecore JavaScript Services SDK (JSS)

Upgrade JSS apps to JSS 22.0.0

Version:

Sitecore JavaScript Rendering SDK version 22.0.0 requires you to make minor modifications to your apps.

Before you begin

If you haven't already done so, upgrade your app JSS 21.7.
If you've already upgraded to 21.8 for Angular 17 support, be aware that you need to upgrade to 22.1 immediately after completing the steps in this guide in order to retain Angular 17 compatibility.
Familiarize yourself with the JSS 22.0.0 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 21.7 to 22.0.0 for JSS Next.js apps instead of this topic.

Update Angular apps

Important

If your app currently uses JSS 21.8 with Angular 17, after upgrading to JSS 22.0 you will need to immediately update it to 22.1. Angular 17 updates have been backported to 21.8 from version 22.1, but are not present in version 22.0.

To update your AngularJS applications:

If the JSS_APP_NAME environment variable is present, rename it to SITECORE_SITE_NAME.

Create a /src/app/lib/client-factory.ts file consisting of the following:

import {
  GraphQLRequestClientFactoryConfig,
  GraphQLRequestClient,
} from '@sitecore-jss/sitecore-jss-angular';
import { environment as env } from '../../environments/environment';

// The GraphQLRequestClientFactory serves as the central hub for executing GraphQL requests within the application

/**
 * Creates a new GraphQLRequestClientFactory instance
 * @returns GraphQLRequestClientFactory instance
 */
export const createGraphQLClientFactory = () => {
  let clientConfig: GraphQLRequestClientFactoryConfig;

  if (env.graphQLEndpoint && env.sitecoreApiKey) {
    clientConfig = {
      endpoint: env.graphQLEndpoint,
      apiKey: env.sitecoreApiKey,
    };
  } else {
    throw new Error('Please configure your graphQLEndpoint and sitecoreApiKey.');
  }

  return GraphQLRequestClient.createClientFactory(clientConfig);
};

export const clientFactory = createGraphQLClientFactory();

Modify the /src/app/lib/layout-service-factory.ts file as follows:
- Add the following import statement:
  import { clientFactory } from './client-factory';
- Locate the following GraphQLLayoutService constructor options, if present:
  endpoint: config.graphQLEndpoint, apiKey: config.sitecoreApiKey,
- Replace those options with the following:
  clientFactory,
Modify the /src/app/lib/dictionary-service-factory.ts file as follows:
- Add the following import statement:
  import { clientFactory } from './client-factory';
- Locate the following GraphQLDictionaryService constructor options, if present:
  endpoint: config.graphQLEndpoint, apiKey: config.sitecoreApiKey,
- Replace those options with the following:
  clientFactory,
If you've previously upgraded this app to JSS 21.8 for Angular 17 support, you must now upgrade it to JSS 22.1.

Update React apps

To update your React applications:

If the REACT_APP_JSS_APP_NAME environment variable is present, rename it REACT_APP_SITECORE_SITE_NAME.
In all components that use the Image type imported from the sitecore-jss/sitecore-jss-react module, rename the media prop to field.

Create a /src/lib/client-factory.js file consisting of the following:

import { GraphQLRequestClient } from '@sitecore-jss/sitecore-jss-react';
import config from '../temp/config';

// The GraphQLRequestClientFactory serves as the central hub for executing GraphQL requests within the application

/**
 * Creates a new GraphQLRequestClientFactory instance
 * @returns GraphQLRequestClientFactory instance
 */
export const createGraphQLClientFactory = () => {
  let clientConfig;

  if (config.graphQLEndpoint && config.sitecoreApiKey) {
    clientConfig = {
      endpoint: config.graphQLEndpoint,
      apiKey: config.sitecoreApiKey,
    };
  } else {
    throw new Error('Please configure your graphQLEndpoint and sitecoreApiKey.');
  }

  return GraphQLRequestClient.createClientFactory(clientConfig);
};

export const clientFactory = createGraphQLClientFactory();

Modify the /src/lib/layout-service-factory.js file as follows:
- Add the following import statement:
  import { clientFactory } from './client-factory';
- Locate the following GraphQLLayoutService constructor options, if present:
  endpoint: config.graphQLEndpoint, apiKey: config.sitecoreApiKey,
- Replace those options with the following:
  clientFactory,
Modify the /src/lib/dictionary-service-factory.js file as follows:
- Add the following import statement:
  import { clientFactory } from './client-factory';
- Locate the following GraphQLDictionaryService constructor options, if present:
  endpoint: config.graphQLEndpoint, apiKey: config.sitecoreApiKey,
- Replace those options with the following:
  clientFactory,

Update Vue.js apps

To update your Vue.js applications:

If the VUE_APP_JSS_APP_NAME environment variable is present, rename it to VUE_APP_SITECORE_SITE_NAME.

Create a /src/lib/client-factory.js file consisting of the following:

import { GraphQLRequestClient } from '@sitecore-jss/sitecore-jss-vue';
import config from '../temp/config';

// The GraphQLRequestClientFactory serves as the central hub for executing GraphQL requests within the application

/**
 * Creates a new GraphQLRequestClientFactory instance
 * @returns GraphQLRequestClientFactory instance
 */
export const createGraphQLClientFactory = () => {
  let clientConfig;

  if (config.graphQLEndpoint && config.sitecoreApiKey) {
    clientConfig = {
      endpoint: config.graphQLEndpoint,
      apiKey: config.sitecoreApiKey,
    };
  } else {
    throw new Error('Please configure your graphQLEndpoint and sitecoreApiKey.');
  }

  return GraphQLRequestClient.createClientFactory(clientConfig);
};

export const clientFactory = createGraphQLClientFactory();

Modify the /src/lib/layout-service-factory.js file as follows:
- Add the following import statement:
  import { clientFactory } from './client-factory';
- Locate the following GraphQLLayoutService constructor options, if present:
  endpoint: config.graphQLEndpoint, apiKey: config.sitecoreApiKey,
- Replace those options with the following:
  clientFactory,
Modify the /src/lib/dictionary-service-factory.js file as follows:
- Add the following import statement:
  import { clientFactory } from './client-factory';
- Locate the following GraphQLDictionaryService constructor options, if present:
  endpoint: config.graphQLEndpoint, apiKey: config.sitecoreApiKey,
- Replace those options with the following:
  clientFactory,

Update the Node headless SSR Experience Edge app

To update your Node headless SSR Experience Edge app:

Create a /src/client-factory.ts file consisting of the following:

import {
  GraphQLRequestClientFactoryConfig,
  GraphQLRequestClient,
} from '@sitecore-jss/sitecore-jss';
import { config } from './config';

// The GraphQLRequestClientFactory serves as the central hub for executing GraphQL requests within the application

/**
 * Creates a new GraphQLRequestClientFactory instance
 * @returns GraphQLRequestClientFactory instance
 */
export const createGraphQLClientFactory = () => {
  let clientConfig: GraphQLRequestClientFactoryConfig;

  if (config.endpoint && config.apiKey) {
    clientConfig = {
      endpoint: config.endpoint,
      apiKey: config.apiKey,
    };
  } else {
    throw new Error('Please configure your endpoint and apiKey.');
  }

  return GraphQLRequestClient.createClientFactory(clientConfig);
};

export const clientFactory = createGraphQLClientFactory();

Modify the /src/index.ts file as follows:
- Add the following import statement:
  import { clientFactory } from './client-factory';
- Locate the following GraphQLLayoutService constructor options, if present:
  endpoint: config.endpoint, apiKey: config.apiKey,
- Replace those options with the following:
  clientFactory,
- Locate the following GraphQLDictionaryService constructor options, if present:
  endpoint: config.endpoint, apiKey: config.apiKey,
- Replace those options with the following:
  clientFactory,

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.0.0.
Install the dependencies with the following command:
npm install

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