---
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: "Upgrade your JavaScript Rendering SDKs to version 21.6 to support the Edge Context and simplify the integration of your SitecoreAI-connected apps."
---
# Upgrade JSS 21.5 Next.js apps to version 21.6

The JavaScript Rendering SDKs (JSS) 21.6 brings new features and support for the Edge Context and the [XM Cloud add-on](https://doc.sitecore.com/sai/en/developers/jss/216/jss-sai/the-jss-xm-cloud-add-on-for-next-js.html "The JSS XM Cloud add-on for Next.js") for Next.js that simplifies integrating personalization features and other composable services and products. Furthermore, some functionality was consolidated into this new plugin, and we refactored some services and configurations to support the Edge Context and simplify configuration.

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

- `nextjs`
- `nextjs-personalize`
- `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.
>
> -   Read the documentation for the JSS [XM Cloud add-on](https://doc.sitecore.com/sai/en/developers/jss/216/jss-sai/the-jss-xm-cloud-add-on-for-next-js.html "The JSS XM Cloud add-on for Next.js"). It will help you understand the changes you must make when following this topic.

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

This topic describes how to:

- Update environment variables for your existing app.
- Update application dependencies in 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.
- Migrate from the Personalize add-on to the XM Cloud add-on.
- Update the Multisite add-on files.
- Fix BYOC errors after upgrading.

## 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, you must modify your `.env` file as follows:

1. Add the `SITECORE_EDGE_CONTEXT_ID` . The value is [your Context ID](https://doc.sitecore.com/xmc/en/developers/xm-cloud/en/context-id-environment-variables.html). This is required to use the Sitecore Edge Platform.
2. Rename the `JSS_APP_NAME` environment variable to `SITECORE_SITE_NAME`.
3. Remove the following deprecated environment variables:
    - `NEXT_PUBLIC_CDP_TARGET_URL`
    - `NEXT_PUBLIC_CDP_CLIENT_KEY`
    - `NEXT_PUBLIC_CDP_POINTOFSALE`

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. If you don't use the XM Cloud/Personalize add-on, remove the following dependency:

        ```text
        "@sitecore-feaas/clientside": "^0.5.5"
        ```

    2. If you do use the XM Cloud/Personalize add-on, remove the `"@sitecore/engage": "^1.4.1"` dependency and replace it with the following:

        ```

        "@sitecore-cloudsdk/events": "^0.1.3",
        "@sitecore-feaas/clientside": "^0.5.12"
        ```

    3. Update every `@sitecore-jss` package to version `~21.6.0`.
    4. Update the `@sitecore/components` package to version `~1.0.19`. If not present, add it.
    5. Update `@types/react` to `^18.2.22`.
    :::

2. Install the dependencies with the following command:

    ```text
    npm install
    ```

## 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 with the XM Cloud add-on. 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 with the XM Cloud add-on included:

> [!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. 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, *./jss216*, 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.
6. Select the add-ons used by your existing application - `nextjs-sxa` and/or `nextjs-multisite` and press Enter.

    > [!note]
    > The `nextjs-personalize` plugin has been replaced by the XM Cloud add-on (`nextjs-xmcloud`), so you will not see it in the list of add-ons.

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.

To update the Next.js template files:

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:

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

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

    2. Locate the following `GraphQLDictionaryService` constructor options:

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

    3. Replace that code block with the following:

        ```typescript
        {
          clientFactory,
          siteName: config.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:

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

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

    2. Locate the following `GraphQLLayoutService` constructor options:

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

    3. Replace that code block with the following:

        ```typescript
        {
          clientFactory,
          siteName: config.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:

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

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

    2. 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 import of the `getPublicUrl` function and replace the function 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:

    :::lettered
    1. Import the `config` object:

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

    2. Instead of generating it with 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;
        ```

    3. Remove the following statement:

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

    :::

11. Replace any remaining occurrences of the config property `jssAppName` with `sitecoreSiteName`.

## Update SXA add-on files

To upgrade the SXA add-on:

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:

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

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

    2. 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,
        }
        ```

    :::

3. In `/src/pages/api/sitemap.ts`, do the following:

    :::lettered
    1. 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
        // ...other code
          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('');
        // ... other code
        ```

    2. Add the following import statement:

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

    3. Locate the `sitemapXmlService` initialization and replace it with the following:

        ```csharp
        const sitemapXmlService = new GraphQLSitemapXmlService({
          clientFactory,
          siteName: site.name,
        });
        ```

    :::

4. In `/src/pages/api/robots.ts`, do the following:

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

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

    2. Replace that statement with the following:

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

    3. Locate the `robotsService` initialization and replace it with the following:

        ```typescript
        const robotsService = new GraphQLRobotsService({
          clientFactory,
          siteName: site.name,
        });
        ```

    :::

5. 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';
    // ...other code
    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,
      });
      // ... other code
    }
    ```

## Migrate from the Personalize add-on to the XM Cloud add-on

The XM Cloud add-on (`nextjs-xmcloud`) adds support for the unified Context to JSS Next.js apps, enabling simplified configuration.

Furthermore, the XM Cloud add-on replaces the deprecated Personalize add-on (`nextjs-personalize`). This is only relevant in dependencies, as the files added to your application by the old add-on still exist, but they must be updated to use new environment variables and the GraphQL request client factory.

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

To use the new simplified configuration and correctly implement Personalization features, you need to make the following changes:

1. Copy the following from the JSS 21.6 Next.js application into your existing application:
    - The `/scripts/config/plugins/edge-platform.ts` file.
    - The `/src/lib/context` folder.
    - The `/src/byoc` folder.
    - The `/src/Bootstrap.tsx` file.
2. If you have not customized the `/src/lib/middleware/plugins/personalize.ts` file, replace it with the 21.6 version. Otherwise, modify it as follows:

    :::lettered
    1. Import the bootstrapped `config` object and the GraphQL request client factory:

        ```javascript
        import clientFactory from 'lib/graphql-client-factory';
        import config from 'temp/config';
        ```

    2. In the `edgeConfig` object, replace the `endpoint` and `apiKey` properties with the imported `clientFactory`:

        ```csharp
        edgeConfig: {
           clientFactory,
           timeout:
              (process.env.PERSONALIZE_MIDDLEWARE_EDGE_TIMEOUT &&
                 parseInt(process.env.PERSONALIZE_MIDDLEWARE_EDGE_TIMEOUT)) ||
              400,
           scope: process.env.NEXT_PUBLIC_PERSONALIZE_SCOPE,
        },
        ```

    3. In the `cdpConfig` object, replace the `endpoint` and `clientKey` properties with `sitecoreEdgeUrl` and `sitecoreEdgeContextId`:

        ```csharp
        cdpConfig: {
         sitecoreEdgeUrl: config.sitecoreEdgeUrl,
         sitecoreEdgeContextId: config.sitecoreEdgeContextId,
         timeout:
           (process.env.PERSONALIZE_MIDDLEWARE_CDP_TIMEOUT &&
              parseInt(process.env.PERSONALIZE_MIDDLEWARE_CDP_TIMEOUT)) ||
            400,
        }
        ```

    :::

3. If you have not customized the `/src/components/CdpPageView.tsx`, replace it with the 21.6 version. Otherwise, make the following changes:

    :::lettered
    1. Remove the `SiteInfo`, `PosResolver`, `init`, and `siteResolver` imports.
    2. Import the Context instance:

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

    3. Replace the `createPageView` asynchronous function with:

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

    :::

4. In the `/src/Scripts.tsx` file, import and use the BYOC component:

    ```csharp
    import BYOC from 'src/byoc';
    import CdpPageView from 'components/CdpPageView';

    const Scripts = (): JSX.Element => {
      return (
        <>
          <BYOC />
          <CdpPageView />
        </>
      );
    };

    export default Scripts;
    ```

If you are not using the `nextjs-sxa` add-on, copy the following files from the 21.6 application to your existing application:

- `/scripts/scaffold-component/plugins/byoc.ts`
- `/scripts/scaffold-component/plugins/next-steps-byoc.ts`
- `/scripts/templates/byoc-component-src.ts`

These files are already present if you use the `nextjs-sxa` add-on.

## Update the Multisite add-on files

To use the new GraphQL request client factory, you must 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))],
        });
        ```

## Fix BYOC errors after upgrading

After upgrading, you might experience errors or unexpected behaviors. Here are some problems you might encounter and tips for how to solve them.

### External (BYOC) component registration errors

If you’re using External (BYOC) Components in your app, you might encounter `This component was not registered.` errors.

You can get these errors in two situations:

- If your BYOC components are not imported in `/src/byoc/index.client.ts` or `/src/byoc/index.hybrid.ts`.
- If you don't have the `/src/lib/next-config/plugins/feaas.js` plugin in your application. This plugin ensures the FEEAS SDK uses Commonjs on the server, and prevents double registration of BYOC components such as client-side and server-side.

To resolve these errors:

- Ensure that your components are imported in either `/src/byoc/index.client.ts` or `/src/byoc/index.hybrid.ts`, depending on the context where they run.
- Copy the `/src/lib/next-config/plugins/feaas.js` file from the 21.6 application you created at the start of the upgrade work.

### External (BYOC) components do not work

If BYOC components don't work, ensure the `<BYOC/>` component is imported and rendered in either of these files:

- `/src/Scripts.tsx`
- `src/Layout.tsx`