---
title: "Upgrade JSS 21.7 Next.js apps to version 21.10"
slug: "upgrade-jss-21-7-next-js-apps-to-version-21-10"
abstract: "How to upgrade your JSS 21.7 Next.js apps to version 21.10 to take advantage of React 19, Next.js 15, and Cloud SDK 0.5.1."
---
# Upgrade JSS 21.7 Next.js apps to version 21.10

This guide covers most of the changes you must make to your existing Next.js JSS 21.7 applications to take advantage of the improvements in version 21.10. However, because this process also involves [updating React to version 19](https://react.dev/blog/2024/04/25/react-19-upgrade-guide) and [Next.js to version 15](https://nextjs.org/docs/app/guides/upgrading/version-15), you'll need to refer to the relevant guides for each framework to complete the upgrade process for your apps.

> [!important]
> This version of JSS introduces Cloud SDK 0.5.1. Due to fundamental changes introduced in this version, you will need to make substantial changes to your JSS app, as described in this upgrade guide.
>
> If you haven't previously upgraded your 21.x app's version of Cloud SDK to 0.4.0, you'll also need to refer to the [0.4.0 upgrade guide](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/upgrade-from-cloud-sdk-version-0-3-to-0-4.html) and make any relevant changes mentioned there.

Because of the nature of JavaScript and Next.js application development, this guide doesn't account for all the customization you might have in your existing application.

While upgrading, 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 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.7](https://doc.sitecore.com/sai/en/developers/jss/217/jss-sai/upgrade-jss-21-6-4-next-js-apps-to-version-21-7.html "Upgrade JSS 21.6.4 Next.js apps to version 21.7").
>
> -   We recommend you read the official release notes for [React 19](https://react.dev/blog/2024/12/05/react-19) and [Next.js 15](https://nextjs.org/blog/next-15) to understand what has changed in these new versions.
>
> -   Familiarize yourself with the [changelog](https://github.com/Sitecore/jss/releases/tag/v21.10.0). If your application is heavily customized, the changelog can provide guidance on what additional changes you need that are not covered in this topic.

This topic describes how to:

:::walkthrough
1. [Update application dependencies in your existing app](https://doc.sitecore.com/sai/en/developers/jss/217/jss-sai/upgrade-jss-21-7-next-js-apps-to-version-21-10.html#update-application-dependencies-in-your-existing-app)
2. [Create a JSS 21.10 Next.js application](https://doc.sitecore.com/sai/en/developers/jss/217/jss-sai/upgrade-jss-21-7-next-js-apps-to-version-21-10.html#create-a-jss-2110-nextjs-application)
3. [Update the Next.js template files in your existing app](https://doc.sitecore.com/sai/en/developers/jss/217/jss-sai/upgrade-jss-21-7-next-js-apps-to-version-21-10.html#update-the-nextjs-template-files-in-your-existing-app)
4. [Update the SXA add-on](https://doc.sitecore.com/sai/en/developers/jss/217/jss-sai/upgrade-jss-21-7-next-js-apps-to-version-21-10.html#update-the-sxa-add-on)
:::

## Update application dependencies in your existing app

For your upgraded application to work correctly, you will need to update dependencies.

To update your dependencies:

1. In your existing application's `package.json` file:
    - Update every `@sitecore-jss` package to version `~21.10.0`.
    - Update the `@sitecore-cloudsdk/events` package to version `^0.5.1`.
    - Add the `@sitecore-cloudsdk/core` package at version `^0.5.1`.
    - Update the `@sitecore/components` package to version `~2.0.0`.
    - Update the following dependencies to the specified versions:

        ```json
        "graphql": "~15.10.1",
        "next": "^15.3.1",
        "react": "^19.1.0",
        "react-dom": "^19.1.0",
        "@types/react": "^19.1.2",
        "@types/react-dom": "^19.1.3",
        "eslint-plugin-react": "^7.37.5",
        ```

2. Install the dependencies with the following command:

    ```shell
    npm install
    ```

## Create a JSS 21.10 Next.js application

To simplify the upgrade process as much as possible, create a JSS 21.10 Next.js application with the XM Cloud add-on. You can then copy some files from this app into your existing app.

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

1. In a console, run the following command:

    ```shell
    npx create-sitecore-jss@21.10 nextjs
    ```

2. If prompted to install the `create-sitecore-jss@21.10` package, answer *y*.
3. Enter the folder path for the JSS 21.10 Next.js app. For example, enter `*./jss2110*`, 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

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

To update the Next.js template files:

1. Remove the `src/lib/context` folder.
2. If you have not customized the `src/Bootstrap.tsx` file, replace it with the version in your template app. Otherwise, make the following changes:
    - Add the following imports required for Cloud SDK 0.5.1:

        ```typescript
        import { CloudSDK } from '@sitecore-cloudsdk/core/browser';
        import '@sitecore-cloudsdk/events/browser';
        import { LayoutServicePageState } from '@sitecore-jss/sitecore-jss-nextjs';
        ```

    - Delete the `context` import:

        ```typescript
        import { context } from 'src/lib/context';
        ```

    - Locate the associated `init` method call:

        ```typescript
        context.init({
          siteName: props.site?.name || config.sitecoreSiteName,
          pageState: props.layoutData?.sitecore?.context?.pageState,
        });
        ```

    - Delete that call, replacing it with the following to initialize Cloud SDK. Make sure this new call is made with `useEffect()` in normal, non-development mode:

        ```typescript
        useEffect(() => {
          const pageState = props.layoutData?.sitecore?.context.pageState;
          if (process.env.NODE_ENV === 'development')
            console.debug('Browser Events SDK is not initialized in development environment');
          else if (pageState !== LayoutServicePageState.Normal)
            console.debug('Browser Events SDK is not initialized in edit and preview modes');
          else {
            CloudSDK({
              sitecoreEdgeUrl: config.sitecoreEdgeUrl,
              sitecoreEdgeContextId: config.sitecoreEdgeContextId,
              siteName: props.site?.name || config.sitecoreSiteName,
              enableBrowserCookie: true,
              // Replace with the top level cookie domain of the website that is being integrated e.g ".example.com" and not "www.example.com"
              cookieDomain: window.location.hostname.replace(/^www\./, ''),
            })
              .addEvents()
              .initialize();
          }
        }, [props.site?.name]);
        ```

3. If you have not customized the `src/components/CDPPageView.tsx` file, replace it with the version in your template app. Otherwise, make the following changes:
    - Add the following imports required for Cloud SDK 0.5.1:

        ```typescript
        import { pageView } from '@sitecore-cloudsdk/events/browser';
        ```

    - Delete the `context` import:

        ```typescript
        import { context } from 'lib/context';
        ```

    - Locate the associated promise:

        ```typescript
        context
          .getSDK('Events')
          .then((Events) =>
            Events.pageView({
              channel: 'WEB',
              currency: 'USD',
              page: route.name,
              pageVariantId,
              language,
            })
          )
            .catch((e) => console.debug(e));
        ```

    - Replace it with the following direct call to `pageView`:

        ```typescript
        pageView({
          channel: 'WEB',
          currency: 'USD',
          page: route.name,
          pageVariantId,
          language,
        }).catch((e) => console.debug(e));
        ```

4. If you have not customized the `src/byoc/index.ts` file, replace it with the version in your template app. Otherwise, make the following changes:
    - Change the file extension to `.tsx`.
    - Add the following imports required for Cloud SDK 0.5.1:

        ```typescript
        import React from 'react';
        import * as Events from '@sitecore-cloudsdk/events/browser';
        import config from 'temp/config';
        import {
          LayoutServicePageState,
          SitecoreContextReactContext,
        } from '@sitecore-jss/sitecore-jss-nextjs';
        ```

    - Delete the `context` import:

        ```typescript
        import { context } from 'lib/context';
        ```

    - Delete the following call:

        ```typescript
        FEAAS.setContextProperties(context);
        ```

    - Add the following component definition:

        ```typescript
        const BYOCInit = (): JSX.Element | null => {
          const sitecoreContext = React.useContext(SitecoreContextReactContext).context;
          // Set context properties to be available within BYOC components
          FEAAS.setContextProperties({
            sitecoreEdgeUrl: config.sitecoreEdgeUrl,
            sitecoreEdgeContextId: config.sitecoreEdgeContextId,
            pageState: sitecoreContext?.pageState || LayoutServicePageState.Normal,
            siteName: sitecoreContext?.site?.name || config.sitecoreSiteName,
            eventsSDK: Events,
          });
          return <FEAAS.ExternalComponentBundle />;
        };
        ```

    - Replace the `default` export statement with the following:

        ```typescript
        export default BYOCInit;
        ```

5. Unless you previously upgraded your JSS 21.x app's Cloud SDK version to 0.4.0, you'll need to make additional changes as described in the [0.4.0 upgrade guide](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/upgrade-from-cloud-sdk-version-0-3-to-0-4.html).
6. Remove all other `lib/context` imports throughout your app. Instead of `context.getSDK()`, you can now call Cloud SDK methods directly. If you're using context to retrieve other values, we recommend using `temp/config` instead.
7. Because Next.js 15 [removes the `geo` and `ip` properties from `NextRequest`](https://nextjs.org/docs/app/guides/upgrading/version-15#nextrequest-geolocation), if your solution is hosted by Vercel you need to update your `src/lib/middleware/plugins/personalize.ts` plugin to explicitly provide geo data to the `PersonalizeMiddleware`, via the `PersonalizeOptions` parameter of the personalize middleware handler.

    If you have not customized the `src/lib/middleware/plugins/personalize.ts` file, replace it with the version in your template app. Otherwise, modify it as shown in the following example:

    ```typescript
    import { NextRequest, NextResponse } from 'next/server';
    import { geolocation } from '@vercel/functions'
    import { PersonalizeMiddleware } from '@sitecore-jss/sitecore-jss-nextjs/middleware';
    import { MiddlewarePlugin } from '..';
    ...

    class PersonalizePlugin implements MiddlewarePlugin {
      private personalizeMiddleware: PersonalizeMiddleware;

      ...

      async exec(req: NextRequest, res?: NextResponse): Promise<NextResponse> {
        const { city, country, region } = geolocation(req)

        return this.personalizeMiddleware.getHandler()(req, res, {
          geo: { city, country, region },
        });
      }
    }

    export const personalizePlugin = new PersonalizePlugin();
    ```

8. For every component that uses the `JSX` namespace (for example, if a `JSX.Element` type is present), add a `JSX` import from `react`.
    - In the `src/Bootstrap.tsx` file, the existing `react` import might look like this:

        ```typescript
        import { useEffect } from 'react';
        ```

    - In which case, add `JSX` to create the following:

        ```typescript
        import { useEffect, JSX } from 'react';
        ```

    > [!tip]
    > If you haven't previously customized these files, you can replace them with the versions from your template app.

## Update the SXA add-on

To update the SXA add-on:

1. If you have not customized the `src/assets/sass/components/_component-column-splitter.scss` file, replace it with the version in your template app. Otherwise, do the following:
    - Locate the following padding rules:

        ```scss
        padding-left: $default-padding / 2;
        padding-right: $default-padding / 2;
        ```

    - Replace those rules with the following:

        ```scss
        padding-left: $default-padding * 0.5;
        padding-right: $default-padding * 0.5;
        ```

2. If you have not customized the `/src/assets/sass/components/promo/_promo-shadow.scss` file, replace it with the version in your template app. Otherwise, reposition the CSS statements above the `@include respond-to(all-mobile)` block, as shown in the following example:
    - CSS statements (`padding`, `margin`) previously:

        ```scss
        ...
          >.component-content {
            @include respond-to(all-mobile) {
              margin: 0 10px 30px 10px;
            }
            padding: 15px;
            margin: 0 0 30px 0;
            &:before, &:after {
              ...
        ```

    - CSS statements after moving them both:

        ```scss
        ...
          >.component-content {
            padding: 15px;
            margin: 0 0 30px 0;
            @include respond-to(all-mobile) {
              margin: 0 10px 30px 10px;
            }
            &:before, &:after {
              ...
        ```

3. If you have not customized the `src/lib/next-config/plugins/sass.js` file, replace it with the version in your template app. Otherwise, add the following extra properties to your `sassOptions` configuration:

    ```javascript
    sassOptions: {
      ...
      quietDeps: true,
      silenceDeprecations: ["import", "legacy-js-api"],
    },
    ```

    > [!note]
    > This change is a temporary fix to suppress `sass` deprecation warnings from Bootstrap. When new versions of `bootstrap` and `font-awesome` are released and the warnings stop, these two properties can be removed.

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