1. Sitecore JavaScript Services SDK (JSS)

Upgrade JSS 21.7 Next.js apps to version 21.10

Version:

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 and Next.js to version 15, you'll need to refer to the relevant guides for each framework to complete the upgrade process for your apps.

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

  • nextjs 

  • nextjs-styleguide OR nextjs-sxa

  • nextjs-multisite 

Before you begin

  • If you haven't already done so, upgrade your app to JSS 21.7.

  • We recommend you read the official release notes for React 19 and Next.js 15 to understand what has changed in these new versions.

  • Familiarize yourself with the changelog. 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:

  1. Update application dependencies in your existing app

  2. Create a JSS 21.10 Next.js application

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

  4. 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 following dependencies to the specified versions:

      "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:

    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. You can then copy some files from this app into your existing app.

To create a JSS 21.10 Next.js application:

  1. In a console, run the following command:

  2. If prompted to install the [email protected] 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 n.

  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:

  • 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:

      import { useEffect } from 'react';

    • In which case, add JSX to create the following:

      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:

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

    • Replace those rules with the following:

      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:

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

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

    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 to assist you if necessary.

If you have suggestions for improving this article, let us know!