---
title: "Upgrade JSS 21.5 Next.js apps to version 21.6"
slug: "upgrade-jss-21-5-next-js-apps-to-version-21-6"
abstract: "JSS 21.6 consolidates client management for all GraphQL-based services."
---
# Upgrade JSS 21.5 Next.js apps to version 21.6

The JavaScript Rendering SDKs (JSS) 21.6 consolidates client management for all GraphQL-based services and refactors some services and configurations.

This topic covers most of the changes you must make in your existing JSS 21.5 applications to take advantage of the new features.

Due to the nature of JavaScript and Next.js application development, this guide can not account for all the customization you might have in your existing application.

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.5 application might use the following templates and add-ons:

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

> [!note]
> **Before you begin**
> -   Familiarize yourself with the [changelog](https://github.com/Sitecore/jss/releases/tag/v21.6.0). If your application is heavily customized, you might need to refer to it for hints on what additional changes you need, which might not be covered in this topic.

This topic describes how to:

- Update application dependencies in your existing app.
- Update environment variables for your existing app.
- Create a JSS 21.6 Next.js application.
- Update the Next.js template files in your existing app.
- Update SXA add-on files (if present).
- Update the Multisite add-on files.

## Update application dependencies in your existing app

For your existing application to work correctly and use new features, you need to update dependencies.

To update your dependencies:

1. In your existing application's `package.json` file:
    - Update every `@sitecore-jss` package to use version `~21.6.0`.
    - Update `@types/react` to `^18.2.22`.
2. Install the dependencies with the following command:

    ```shell
    npm install
    ```

## Update environment variables for your existing app

The updated configuration scripts need some new environment variables.

To provide the new environment variables to your application, modify your `.env` file as follows:

- Rename the `JSS_APP_NAME` environment variable to `SITECORE_SITE_NAME`. This is optional.

You might need to restart the local application server for the environment variable changes to take effect.

## Create a JSS 21.6 Next.js application

To simplify the upgrade process as much as possible, you must first create a JSS 21.6 Next.js application. You will need to copy some files from the 21.6 app into your existing app.

To create a JSS 21.6 Next.js application:

1. In a console, run the following command:

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

2. If prompted to install the `create-sitecore-jss@21.6.0` package, answer *y*.
3. Enter the folder path for the JSS 21.6 Next.js app. For example, to create the app folder in your current working directory, enter *./jss216*.
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 the add-ons used by your existing application - `nextjs-sxa` and/or `nextjs-multisite` and press Enter.

The script then installs the application dependencies.

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

In this procedure, you will replace files in your existing applications with corresponding files for the JSS 21.6 app, or modify your existing app files using the JSS 21.6 app files as a guide.

Update the Next.js template files as follows:

1. Replace the `/scripts/generate-config.ts` file in your existing application with the 21.6 version.
2. Replace the `/src/lib/next-config/plugins/cors-header.js` file in your existing application with the 21.6 version.
3. Copy the the `/src/lib/graphql-client-factory/` folder from the 21.6 app to your existing app.
4. Copy the `/src/lib/config.ts` file from the 21.6 app to your existing app.
5. If you have not customized the `/src/lib/dictionary-service-factory.ts` file, replace it with the 21.6 version. Otherwise, modify it as follows:
    - Add the following import statement:

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

    - Locate the following `GraphQLDictionaryService` constructor options:

        ```typescript
        {
          endpoint: config.graphQLEndpoint,
          apiKey: config.sitecoreApiKey,
          siteName,
          retries:
            (process.env.GRAPH_QL_SERVICE_RETRIES &&
             parseInt(process.env.GRAPH_QL_SERVICE_RETRIES, 10)) ||
            0,
        }
        ```

    - Replace that code block with the following:

        ```typescript
        {
          clientFactory,
          siteName,
          retries:
            (process.env.GRAPH_QL_SERVICE_RETRIES &&
             parseInt(process.env.GRAPH_QL_SERVICE_RETRIES, 10)) ||
            0,
        }
        ```

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

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

    - Locate the following `GraphQLLayoutService` constructor options:

        ```typescript
        {
          endpoint: config.graphQLEndpoint,
          apiKey: config.sitecoreApiKey,
          siteName,
          retries:
            (process.env.GRAPH_QL_SERVICE_RETRIES &&
             parseInt(process.env.GRAPH_QL_SERVICE_RETRIES, 10)) ||
            0,
        }
        ```

    - Replace that code block with the following:

        ```typescript
        {
          clientFactory,
          siteName,
          retries:
            (process.env.GRAPH_QL_SERVICE_RETRIES &&
             parseInt(process.env.GRAPH_QL_SERVICE_RETRIES, 10)) ||
            0,
        }
        ```

7. In the `/src/pages/_app.tsx` file, do the following:
    - Add the following import statement:

        ```typescript
        import Bootstrap from 'src/Bootstrap';
        ```

    - Add the `Bootstrap` component to the app rendering function. For example:

        ```tsx
        return (
            <>
              <Bootstrap {...pageProps} />
              <I18nProvider lngDict={dictionary} locale={pageProps.locale}>
                <Component {...rest} />
              </I18nProvider>
            </>
          );
        ```

8. In the `/next.config.js` file, replace the remove the import of the `getPublicUrl` function and replace the function's call with `jssConfig.publicUrl`.
9. Replace the rest of the files in the `/scripts/config` folder with the 21.6 versions.
10. In the `/src/Layout.tsx` and the `/src/Navigation.tsx` files do the following:
    - Import the `config` object:

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

    - Instead of using the `getPublicUrl` function to generate the value of the `publicUrl` constant, replace it with the value from the `config` object:

        ```typescript
        const publicUrl = config.publicUrl;
        ```

    - Remove the `import { getPublicUrl } from '@sitecore-jss/sitecore-jss-nextjs/utils';` statement.
11. Remove the `/src/lib/page-props-factory/plugins/content-styles.ts` file if present.

## Update SXA add-on files

To upgrade the SXA add-on (if present):

1. Replace the `/src/assets/sass` folder with the 21.6 version.
2. If you have not customized the `/src/lib/middleware/plugins/redirects.ts` file, replace it with the 21.6 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,
          locales: ['en'],
          excludeRoute: () => false,
          disabled: () => process.env.NODE_ENV === 'development',
          siteResolver,
        }
        ```

        Replace that code block with the following:

        ```typescript
        {
          clientFactory,
          locales: ['en'],
          excludeRoute: () => false,
          disabled: () => process.env.NODE_ENV === 'development',
          siteResolver,siteName,
          retries:
            (process.env.GRAPH_QL_SERVICE_RETRIES &&
             parseInt(process.env.GRAPH_QL_SERVICE_RETRIES, 10)) ||
            0,
        }
        ```

3. If you have not customized the `/src/pages/api/sitemap.ts` route, replace it with the 21.6 version. Otherwise, remove the import statement for the `getPublicUrl` utility function and create two new constants for `reqtHost` and `reqProtocol`. Use them to build the page locator:

    ```typescript
    const reqtHost = req.headers.host;
      const reqProtocol = req.headers['x-forwarded-proto'] || 'https';
      const SitemapLinks = sitemaps
        .map((item) => {
          const parseUrl = item.split('/');
          const lastSegment = parseUrl[parseUrl.length - 1];
          return `<sitemap>
            <loc>${reqProtocol}://${reqtHost}/${lastSegment}</loc>
          </sitemap>`;
        })
        .join('');
    ```

4. If you have not customized the `/src/pages/404.tsx` and `/src/pages/500.tsx` files, replace them with the 21.6 version. Otherwise, in the `getStaticProps` function, import and use the GraphQL request client factory, instead of the `endpoint` and `apiKey` options for the `GraphQLErrorPagesService` instantiation:

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

    export const getStaticProps: GetStaticProps = async (context) => {
      // other code
      const errorPagesService = new GraphQLErrorPagesService({
        clientFactory,
        siteName: site.name,
        language: context.locale || config.defaultLanguage,
        retries:
          (process.env.GRAPH_QL_SERVICE_RETRIES &&
            parseInt(process.env.GRAPH_QL_SERVICE_RETRIES, 10)) ||
          0,
      });
    }
    ```

## Update the Multisite add-on files

To use the new GraphQL request client factory, you need to update the GraphQL Sitemap Service provided by the JSS Next.js Multisite add-on.

To update the Sitemap service:

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

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

    - Replace the `endpoint` and `apiKey` options for the `MultisiteGraphQLSitemapService` instantiation with the client factory:

        ```csharp
        this._graphqlSitemapService = new MultisiteGraphQLSitemapService({
          clientFactory,
          sites: [...new Set(siteResolver.sites.map((site: SiteInfo) => site.name))],
        });
        ```