---
title: "Upgrade JSS 21.7 Next.js apps to version 22.0.0"
slug: "upgrade-jss-21-7-next-js-apps-to-version-22-0-0"
abstract: "How to upgrade your JavaScript Rendering SDKs to the new major version 22.0.0."
---
# Upgrade JSS 21.7 Next.js apps to version 22.0.0

This topic covers most of the changes you must make to your existing JSS 21.7 applications to take advantage of the new features in version 22.0.0. However, because of the nature of JavaScript and Next.js application development, this topic doesn't account for all the customization you might have in your existing application.

> [!important]
> Several of the changes listed here repeat what's in the 21.6 and 21.7 upgrade guides. If you haven't already made all of these changes, you must now do so in order to prevent build errors when upgrading to 22.0.0.

When performing the upgrade, consider the JSS templates and add-ons you used when creating your Next.js application. You can find them in your `package.json` file. For example, a JSS 21.7 application might use the following templates and add-ons:

- `nextjs` 
- `nextjs-sxa` 
- `nextjs-multisite` 

> [!note]
> **Before you begin**
> -   If you haven't already done so, [upgrade your app to JSS 21.7](https://doc.sitecore.com/xp/en/developers/hd/21/sitecore-headless-development/en/upgrade-jss-21-6-4-next-js-apps-to-version-21-7.html).
>
> -   Familiarize yourself with the [changelog](https://github.com/Sitecore/jss/releases/tag/v22.0.0). If your application is heavily customized, the changelog can provide guidance on what additional changes you need that are not be covered in this topic.

This topic describes how to:

- [Update environment variables for your existing app](https://doc.sitecore.com/xp/en/developers/hd/22/sitecore-headless-development/upgrade-jss-21-7-next-js-apps-to-version-22-0-0.html#UUID-9fbf5026-41d6-cfb1-a0df-8c0e355b25da_N1713953417332).
- [Update application dependencies in your existing app](https://doc.sitecore.com/xp/en/developers/hd/22/sitecore-headless-development/upgrade-jss-21-7-next-js-apps-to-version-22-0-0.html#UUID-9fbf5026-41d6-cfb1-a0df-8c0e355b25da_N1713953896547).
- [Create a JSS 22.0.0 Next.js application](https://doc.sitecore.com/xp/en/developers/hd/22/sitecore-headless-development/upgrade-jss-21-7-next-js-apps-to-version-22-0-0.html#UUID-9fbf5026-41d6-cfb1-a0df-8c0e355b25da_N1713954028631).
- [Update the Next.js template files in your existing app](https://doc.sitecore.com/xp/en/developers/hd/22/sitecore-headless-development/upgrade-jss-21-7-next-js-apps-to-version-22-0-0.html#UUID-9fbf5026-41d6-cfb1-a0df-8c0e355b25da_section-idm1853427908176528 "Update the Next.js template files in your existing app").
- [Update the SXA add-on](https://doc.sitecore.com/xp/en/developers/hd/22/sitecore-headless-development/upgrade-jss-21-7-next-js-apps-to-version-22-0-0.html#UUID-9fbf5026-41d6-cfb1-a0df-8c0e355b25da_section-idm1853427904969130 "Update the SXA add-on").
- [Update the multisite add-on](https://doc.sitecore.com/xp/en/developers/hd/22/sitecore-headless-development/upgrade-jss-21-7-next-js-apps-to-version-22-0-0.html#UUID-9fbf5026-41d6-cfb1-a0df-8c0e355b25da_section-idm1853427905144930 "Update the Multisite add-on").

## Update environment variables for your existing app

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

## Update application dependencies in your existing app

For your upgraded application to work correctly, you must also 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:

    ```shell
    npm install
    ```

## Create a JSS 22.0.0 Next.js application

To simplify the upgrade process as much as possible, create a JSS 22.0.0 Next.js application. You can then copy some files from this app into your existing app.

To create a JSS 22.0.0 Next.js application:

1. In a console, run the following command:

    ```shell
    npx create-sitecore-jss@^22.0.0 nextjs
    ```

2. If prompted to install the `create-sitecore-jss@22.0.0` package, answer *y*.
3. Enter the folder path for the JSS 22.0.0 Next.js app. For example, enter *`./jss22`*, to create the app folder in your current working directory.
4. Follow the remaining prompts, selecting the same options for data fetching (`GraphQL` or `REST`) and prerendering (`SSG` or `SSR`) as in your existing application.
5. When asked if you are building for Sitecore XM Cloud, answer *n* to skip installing the XM Cloud add-on.
6. Select other add-ons used by your existing application and press Enter.

The script then installs the application dependencies.

## Update the Next.js template files in your existing app

This explains how to synchronize files in your existing application with corresponding files from your new JSS 22.0.0 app.

To update the Next.js template files:

1. If you have not customized the `/src/lib/layout-service-factory.ts` file, replace it with the 22.0.0 version. Otherwise, modify the file as follows:
    - Add the following import statement:

        ```typescript
        import clientFactory from 'lib/graphql-client-factory';
        ```

    - Locate the following `GraphQLLayoutService` constructor options, if present:

        ```typescript
        endpoint: config.graphQLEndpoint,
        apiKey: config.sitecoreApiKey,
        ```

    - Replace those options with the following:

        ```typescript
        clientFactory,
        ```

2. If you have not customized the `/src/lib/dictionary-service-factory.ts` file, replace it with the 22.0.0 version. Otherwise, modify the file as follows:
    - Add the following import statement:

        ```typescript
        import clientFactory from 'lib/graphql-client-factory';
        ```

    - Locate the following `GraphQLDictionaryService` constructor options, if present:

        ```typescript
        endpoint: config.graphQLEndpoint,
        apiKey: config.sitecoreApiKey,
        ```

    - Replace those options with the following:

        ```typescript
        clientFactory,
        ```

3. If you're importing the `isEditorActive`, `resetEditorChormes`, `resolveUrl`, `handleEditorFastRefresh`, or `getPublicUrl` functions in your custom code, ensure they are imported from `sitecore-jss-nextjs/utils` and not `sitecore-jss-nextjs`.

## Update the SXA add-on

To upgrade the SXA add-on:

1. If you have not customized the `/src/lib/middleware/plugins/redirects.ts` file, replace it with the 22.0.0 version. Otherwise, modify it as follows:
    - Add the following import statement:

        ```typescript
        import clientFactory from 'lib/graphql-client-factory';
        ```

    - Locate the following `RedirectsMiddleware` constructor options:

        ```typescript
        endpoint: config.graphQLEndpoint,
        apiKey: config.sitecoreApiKey,
        ```

    - Replace them with the following:

        ```typescript
        clientFactory,
        ```

2. If you have not customized the `/src/pages/404.tsx` and `/src/pages/500.tsx` files, replace them with the 22.0.0 versions. Otherwise, modify them as follows:
    - In the `getStaticProps` function, add the following import statement:

        ```typescript
        import clientFactory from 'lib/graphql-client-factory';
        ```

    - For the `GraphQLErrorPagesService` instantiation, locate the following options:

        ```typescript
        endpoint: config.graphQLEndpoint,
        apiKey: config.sitecoreApiKey,
        ```

    - Replace them with the following:

        ```typescript
        clientFactory,
        ```

3. If you have not customized the `\src\pages\api\sitemap.ts` file, replace it with the 22.0.0 version. Otherwise, modify it as follows:
    - Add the following import statement:

        ```typescript
        import clientFactory from 'lib/graphql-client-factory';
        ```

    - For the `GraphQLSitemapXmlService` instantiation, locate the following options:

        ```typescript
        endpoint: config.graphQLEndpoint,
        apiKey: config.sitecoreApiKey,
        ```

    - Replace them with the following:

        ```typescript
        clientFactory,
        ```

4. If you have not customized the `\src\pages\api\robots.ts` file, replace it with the 22.0.0 version. Otherwise, modify it as follows:
    - Add the following import statement:

        ```typescript
        import clientFactory from 'lib/graphql-client-factory';
        ```

    - Remove the `config` import:

        ```typescript
        import config from 'temp/config';
        ```

    - For the `GraphQLRobotsService` instantiation, locate the following options:

        ```typescript
        endpoint: config.graphQLEndpoint,
        apiKey: config.sitecoreApiKey,
        ```

    - Replace them with the following:

        ```typescript
        clientFactory,
        ```

## Update the Multisite add-on

To update the Multisite add-on:

1. If you have not customized the `/scripts/config/plugins/multisite.ts` file, replace it with the 22.0.0 version. Otherwise, do the following:
    - Add the following import statement:

        ```typescript
        import { createGraphQLClientFactory } from 'lib/graphql-client-factory/create';
        ```

    - For the `GraphQLSiteInfoService` constructor call, locate the following options:

        ```typescript
        endpoint: config.graphQLEndpoint,
        apiKey: config.sitecoreApiKey,
        ```

    - Replace them with the following:

        ```typescript
        clientFactory: createGraphQLClientFactory(config),
        ```

2. If you have not customized the `/src/lib/sitemap-fetcher/plugins/graphql-sitemap-service.ts` file, replace it with the 22.0.0 version. Otherwise, do the following:
    - Add the following import statement:

        ```typescript
        import clientFactory from 'lib/graphql-client-factory';
        ```

    - For the `MultisiteGraphQLSitemapService` instantiation, locate the following options:

        ```typescript
        endpoint: config.graphQLEndpoint,
        apiKey: config.sitecoreApiKey,
        ```

    - Replace them with the following:

        ```typescript
        clientFactory,
        ```

3. Be aware that JSS now uses the `site` query to retrieve site info. If the Multisite addon is installed, the `site` query retrieves both the SXA Headless and the configuration sites. JSS will filter out the term *website*, but any other MVC or non-Next.js sites defined in the configuration will be considered for resolution by the JSS app. If this affects you, and you want to avoid it by only using the headless sites for your setup, you can add a filter in the `\scripts\config\plugins\multisite.ts` file. For example:

    ```typescript
    sites = sites.filter((site) => !['not-headless', 'headful', 'mvc'].includes(site.name));
    ```

## Next steps

To finalize the upgrade process, make sure you resolve any errors and warnings you encounter. [Enable debug logging for JSS specific issues](https://doc.sitecore.com/xp/en/developers/hd/22/sitecore-headless-development/debug-logging-in-jss-apps.html "Debug logging in JSS apps") to assist you if necessary.