Upgrade JSS apps to JSS 22.0.0

Version: 22.x

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:

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

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

    RequestResponse
    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();

  3. Modify the /src/app/lib/layout-service-factory.ts file as follows:

    • Add the following import statement:

      RequestResponse
      import { clientFactory } from './client-factory';

    • Locate the following GraphQLLayoutService constructor options, if present:

      RequestResponse
      endpoint: config.graphQLEndpoint,
apiKey: config.sitecoreApiKey,

    • Replace those options with the following:

      RequestResponse
      clientFactory,

  4. Modify the /src/app/lib/dictionary-service-factory.ts file as follows:

    • Add the following import statement:

      RequestResponse
      import { clientFactory } from './client-factory';

    • Locate the following GraphQLDictionaryService constructor options, if present:

      RequestResponse
      endpoint: config.graphQLEndpoint,
apiKey: config.sitecoreApiKey,

    • Replace those options with the following:

      RequestResponse
      clientFactory,

  5. 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:

  1. If the REACT_APP_JSS_APP_NAME environment variable is present, rename it REACT_APP_SITECORE_SITE_NAME.

  2. In all components that use the Image type imported from the sitecore-jss/sitecore-jss-react module, rename the media prop to field.

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

    RequestResponse
    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();

  4. Modify the /src/lib/layout-service-factory.js file as follows:

    • Add the following import statement:

      RequestResponse
      import { clientFactory } from './client-factory';

    • Locate the following GraphQLLayoutService constructor options, if present:

      RequestResponse
      endpoint: config.graphQLEndpoint,
apiKey: config.sitecoreApiKey,

    • Replace those options with the following:

      RequestResponse
      clientFactory,

  5. Modify the /src/lib/dictionary-service-factory.js file as follows:

    • Add the following import statement:

      RequestResponse
      import { clientFactory } from './client-factory';

    • Locate the following GraphQLDictionaryService constructor options, if present:

      RequestResponse
      endpoint: config.graphQLEndpoint,
apiKey: config.sitecoreApiKey,

    • Replace those options with the following:

      RequestResponse
      clientFactory,

Update Vue.js apps

To update your Vue.js applications:

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

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

    RequestResponse
    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();

  3. Modify the /src/lib/layout-service-factory.js file as follows:

    • Add the following import statement:

      RequestResponse
      import { clientFactory } from './client-factory';

    • Locate the following GraphQLLayoutService constructor options, if present:

      RequestResponse
      endpoint: config.graphQLEndpoint,
apiKey: config.sitecoreApiKey,

    • Replace those options with the following:

      RequestResponse
      clientFactory,

  4. Modify the /src/lib/dictionary-service-factory.js file as follows:

    • Add the following import statement:

      RequestResponse
      import { clientFactory } from './client-factory';

    • Locate the following GraphQLDictionaryService constructor options, if present:

      RequestResponse
      endpoint: config.graphQLEndpoint,
apiKey: config.sitecoreApiKey,

    • Replace those options with the following:

      RequestResponse
      clientFactory,

Update the Node headless SSR Experience Edge app

To update your Node headless SSR Experience Edge app:

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

    RequestResponse
    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();

  2. Modify the /src/index.ts file as follows:

    • Add the following import statement:

      RequestResponse
      import { clientFactory } from './client-factory';

    • Locate the following GraphQLLayoutService constructor options, if present:

      RequestResponse
      endpoint: config.endpoint,
apiKey: config.apiKey,

    • Replace those options with the following:

      RequestResponse
      clientFactory,

    • Locate the following GraphQLDictionaryService constructor options, if present:

      RequestResponse
      endpoint: config.endpoint,
apiKey: config.apiKey,

    • Replace those options with the following:

      RequestResponse
      clientFactory,

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.0.0.

  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,