---
title: "Upgrade JSS 21.6.4 Next.js apps to version 21.7"
slug: "upgrade-jss-21-6-4-next-js-apps-to-version-21-7"
abstract: "Upgrade your JavaScript Rendering SDKs to version 21.7 to take advantage of Next.js 14 and improved GraphQL request retries."
---
# Upgrade JSS 21.6.4 Next.js apps to version 21.7

The JavaScript Rendering SDKs (JSS) 21.7 uses Next.js 14, improved GraphQL retries, and the Site GraphQL query for retrieving site information.

The update involves changes to the environment variables, configuration objects, JSS packages, services, and dependencies.

This topic covers most of the changes you must make in your existing JSS 21.6.4 applications to take advantage of the new features. 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.

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.6.4 application included in the XM Cloud starter foundation uses the following templates and add-ons:

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

> [!note]
> **XM Cloud is now SitecoreAI**
> Some code examples, images, and UI labels may still use XM Cloud while engineering assets are being updated.

> [!note]
> **Before you begin**
> -   If you haven't already done so, [upgrade your app to JSS 21.6](https://doc.sitecore.com/sai/en/developers/jss/217/jss-sai/upgrade-jss-21-5-next-js-apps-to-version-21-6.html "Upgrade JSS 21.5 Next.js apps to version 21.6").
>
> -   Familiarize yourself with the [changelog](https://github.com/Sitecore/jss/releases/tag/v21.7.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.
>
> -   Read about [Next.js 14 release](https://nextjs.org/blog/next-14) and keep [the Next.js 14 upgrade guide](https://nextjs.org/docs/app/building-your-application/upgrading/version-14) handy. You might have to use it to finalize the upgrade of your application.

This topic describes how to:

- [Update environment variables for your existing app](https://doc.sitecore.com/sai/en/developers/jss/217/jss-sai/upgrade-jss-21-6-4-next-js-apps-to-version-21-7.html#UUID-64874296-c8ae-4321-b31b-05290fb438e0_section-idm4611658809566434120211252755 "Update environment variables for your existing app").
- [Update application dependencies in your existing app](https://doc.sitecore.com/sai/en/developers/jss/217/jss-sai/upgrade-jss-21-6-4-next-js-apps-to-version-21-7.html#UUID-64874296-c8ae-4321-b31b-05290fb438e0_section-idm4507338688070434120210725859 "Update application dependencies in your existing app").
- [Create a JSS 21.7 Next.js application](https://doc.sitecore.com/sai/en/developers/jss/217/jss-sai/upgrade-jss-21-6-4-next-js-apps-to-version-21-7.html#UUID-64874296-c8ae-4321-b31b-05290fb438e0_section-idm4620167227648034120210091693 "Create a JSS 21.7 Next.js application").
- [Update the Next.js template files in your existing app](https://doc.sitecore.com/sai/en/developers/jss/217/jss-sai/upgrade-jss-21-6-4-next-js-apps-to-version-21-7.html#UUID-64874296-c8ae-4321-b31b-05290fb438e0_section-idm4545590124406434120210480859 "Update the Next.js template files in your existing app").
- [Update the XM Cloud add-on](https://doc.sitecore.com/sai/en/developers/jss/217/jss-sai/upgrade-jss-21-6-4-next-js-apps-to-version-21-7.html#UUID-64874296-c8ae-4321-b31b-05290fb438e0_section-idm4602571608808034229048913731 "Update the XM Cloud add-on").
- [Update SXA add-on](https://doc.sitecore.com/sai/en/developers/jss/217/jss-sai/upgrade-jss-21-6-4-next-js-apps-to-version-21-7.html#UUID-64874296-c8ae-4321-b31b-05290fb438e0_section-idm4545590049686434120429456559 "Update SXA add-on").
- [Update the Multisite add-on](https://doc.sitecore.com/sai/en/developers/jss/217/jss-sai/upgrade-jss-21-6-4-next-js-apps-to-version-21-7.html#UUID-64874296-c8ae-4321-b31b-05290fb438e0_section-idm4620167108465634120432049086 "Update the Multisite add-on").

## Update environment variables for your existing app

The GraphQL retry functionality is now enabled by default with three retries, while still allowing you to [use default or custom retry strategies when fetching data from the Edge GraphQL endpoint](https://doc.sitecore.com/sai/en/developers/jss/217/jss-sai/use-retry-strategies-for-requests-to-experience-edge.html "Use retry strategies for requests to Experience Edge").

To customize the global number of retries:

- In the JSS application's `.env` file, update the value of the `GRAPH_QL_SERVICE_RETRIES` environment variable to the desired number or to 0 to disable retries.

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

## 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, do the following:

    > [!note]
    > **XM Cloud is now SitecoreAI**
    > Some code examples, images, and UI labels may still use XM Cloud while engineering assets are being updated.

    :::lettered
    1. Update the Next.js version:

        ```json
        "next": "^14.1.0",
        ```

    2. Update every `@sitecore-jss` package to version `~21.7.0`.
    3. Update the package versions in `devDependencies` to the new versions, as follows:

        ```json
        "@graphql-codegen/cli": "^5.0.0",
        "@graphql-codegen/import-types-preset": "^3.0.0",
        "@graphql-codegen/plugin-helpers": "^5.0.1",
        "@graphql-codegen/typed-document-node": "^5.0.1",
        "@graphql-codegen/typescript": "^4.0.1",
        "@graphql-codegen/typescript-operations": "^4.0.1",
        "@graphql-codegen/typescript-resolvers": "^4.0.1",
        "@graphql-typed-document-node/core": "^3.2.0",
        ```

    4. If you don't use the XM Cloud add-on, remove the following dependencies:

        ```

        "@sitecore-feaas/clientside": "^0.5.5",
        "@sitecore/components": "~1.0.19",
        ```

    5. If you use the XM Cloud add-on, update these packages to new versions, as follows:

        ```

        "@sitecore/components": "^1.1.10",
        "@sitecore-cloudsdk/events": "^0.2.4",
        "@sitecore-feaas/clientside": "^0.5.17"
        ```

    :::

2. Install the dependencies with the following command:

    ```shell
    npm install
    ```

3. Perform any Next.js specific upgrades using [the Next.js 14 upgrade guide](https://nextjs.org/docs/app/building-your-application/upgrading/version-14). If necessary, use the provided codemods to complete the Next.js upgrade.

    > [!important]
    > You will need to check that version 14 of Next.js has been installed, and adjust your installation if necessary. Version 15 is not compatible with JSS 21.7.

## Create a JSS 21.7 Next.js application

To simplify the upgrade process as much as possible, you must first create a JSS 21.7 Next.js application with the XM Cloud add-on. You will need to copy some files from this app into your existing app.

To create a JSS 21.7 Next.js application with the XM Cloud add-on included:

1. In a console, run the following command:

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

2. If prompted to install the `create-sitecore-jss@21.7.0` package, answer *y*.
3. Enter the folder path for the JSS 21.7 Next.js app. For example, *`./jss217`*, 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 *y* to install the XM Cloud add-on.

    > [!note]
    > **XM Cloud is now SitecoreAI**
    > Some code examples, images, and UI labels may still use XM Cloud while engineering assets are being updated.

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

In this procedure, you will synchronize files in your existing applications with corresponding files for the JSS 21.7 app.

To update the Next.js template files:

1. Copy the the `/scripts/generate-metadata.ts` file from the 21.7 app to your existing app.
2. Copy the `src/lib/next-config/plugins/component-props.js` file from the 21.7 app to your existing app.
3. If you have not customized the `/src/lib/dictionary-service-factory.ts` file, replace it with the 21.7 version. Otherwise, modify the file as follows:

    :::lettered
    1. Locate the `retries` option in the `GraphQLDictionaryService` constructor options:

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

    2. Replace that code block with the following:

        ```typescript
        retries:
            (process.env.GRAPH_QL_SERVICE_RETRIES &&
             parseInt(process.env.GRAPH_QL_SERVICE_RETRIES, 10)) as number,
        ```

    :::

4. If you have not customized the `/src/lib/layout-service-factory.ts` file, replace it with the 21.7 version. Otherwise, modify the file as follows:

    :::lettered
    1. Locate the `retries` option in the `GraphQLLayoutService` constructor options:

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

    2. Replace that code block with the following:

        ```typescript
        retries:
            (process.env.GRAPH_QL_SERVICE_RETRIES &&
             parseInt(process.env.GRAPH_QL_SERVICE_RETRIES, 10)) as number,
        ```

    :::

5. In `/scripts/fetch-graphql-introspection-data.ts`, do the following:

    :::lettered
    1. Locate the following import statement:

        ```typescript
        import { GraphQLRequestClient } from '@sitecore-jss/sitecore-jss-nextjs';
        ```

    2. Replace that statement with the following:

        ```typescript
        import { GraphQLRequestClient } from '@sitecore-jss/sitecore-jss-nextjs/graphql';
        ```

    :::

6. Add the following import statement to `/scripts/bootstrap.ts`:

    ```typescript
    import './generate-metadata';
    ```

## Update the XM Cloud add-on

Updating the XM Cloud add-on requires you update some package dependencies, and replace or update some of the files in your existing application.

To update the XM Cloud add-on:

> [!note]
> **XM Cloud is now SitecoreAI**
> Some code examples, images, and UI labels may still use XM Cloud while engineering assets are being updated.

1. Replace the `/src/lib/page-props-factory/plugins/feaas-themes.ts` file with the `/src/lib/page-props-factory/plugins/component-themes.ts` file from the 21.7 application.
2. Replace the `/src/lib/page-props-factory/plugins/content-styles.ts` file with the 21.7 version.
3. Copy the following files from the 21.7 application into your existing app:
    - `/src/components/FEAASScripts.tsx` 
    - `/src/pages/api/editing/config.ts` 
    - `src/pages/api/editing/feaas/render.ts` 
    - `src/pages/feaas/render.tsx` 
4. In the `/src/middleware.ts` file, update the `matcher` pattern to include `feaas-render`.
5. In the `src/Scripts.tsx` file:

    :::lettered
    1. Import the `FEEASScripts` component:

        ```ts
        import FEAASScripts from 'components/FEAASScripts';
        ```

    2. Add the `FEEASScripts` component after existing components:

        ```ts
        <BYOC />
        <CdpPageView />
        <FEAASScripts />
        ```

    :::

## Update SXA add-on

To upgrade the SXA add-on:

1. Replace the following files with the 21.7 version:
    - `src/assets/basic/_container.scss` 
    - `src/assets/sass/_app.scss` 
2. Update the `/src/components/Image.tsx` as follows:

    :::lettered
    1. Import the `CSSProperties` type from the `react` package:

        ```ts
        import React, { CSSProperties } from 'react';
        ```

    2. Update the `backgroundStyle` constant definition to:

        ```ts
        const backgroundStyle = (props?.fields?.Image?.value?.src && {
          backgroundImage: `url('${props.fields.Image.value.src}')`,
        }) as CSSProperties;
        ```

    :::

## Update the Multisite add-on

SitecoreAI deployments use the GraphQL Site query to fetch site information. This query takes the values valid for the environment when resolving available sites in a multisite environment.

The Multisite add-on has been updated to support the Site query.

To update the Multisite add-on:

- In the `/scripts/config/plugins/multisite.ts`, update the `GraphQLSiteInfoService` constructor call options to include the `useSiteQuery` option with a `true` value:

    ```ts
    const siteInfoService = new GraphQLSiteInfoService({
      clientFactory: createGraphQLClientFactory(config),
      // enable site query for the service. Only works on XMCloud currently
      useSiteQuery: true,
    });
    ```

## 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/sai/en/developers/jss/217/jss-sai/debug-logging-in-jss-apps.html "Debug logging in JSS apps") to assist you if necessary.

We recommend you evaluate your needs in relation to GraphQL retries and [use GraphQL request retry strategies](https://doc.sitecore.com/sai/en/developers/jss/217/jss-sai/use-retry-strategies-for-requests-to-experience-edge.html "Use retry strategies for requests to Experience Edge") as needed to mitigate rate limits in GraphQL endpoints.