Upgrade JSS 21.6.4 Next.js apps to version 21.7

Version:

The JavaScript Rendering SDKs (JSS) 21.7 uses Next.js 14 and has improved GraphQL retries.

The update contains changes to 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 might use the following templates and add-ons:

nextjs
nextjs-sxa
nextjs-multisite

Before you begin

If you haven't already done so, upgrade your app to JSS 21.6.
Familiarize yourself with the changelog. 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 the Next.js 14 release and keep the Next.js 14 upgrade guide handy. You might need it to finalize the upgrade of your application.

This topic describes how to:

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.

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:

In your existing application's package.json file, do the following:

Update the Next.js version:
"next": "^14.1.0",
Update every @sitecore-jss package to version ~21.7.0.

Update the package versions in devDependencies to the new versions, as follows:

"@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",

Install the dependencies with the following command:
npm install
Perform any Next.js specific upgrades using the Next.js 14 upgrade guide. If necessary, use the provided codemods to complete the Next.js upgrade.

Create a JSS 21.7 Next.js application

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

To create a JSS 21.7 Next.js application:

In a console, run the following command:
npx create-sitecore-jss@^21.7.0 nextjs
If prompted to install the [email protected] package, answer y.
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.
Follow the remaining prompts, selecting the same options for data fetching (GraphQL or REST) and prerendering (SSG or SSR) as in your existing application.
When asked if you are building for Sitecore XM Cloud, answer n to skip installing the XM Cloud add-on.
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:

Copy the src/lib/next-config/plugins/component-props.js file from the 21.7 app to your existing app.

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:

Locate the retries option in the GraphQLDictionaryService constructor options:

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

Replace that code block with the following:

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

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:

Locate the retries option in the GraphQLLayoutService constructor options:

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

Replace that code block with the following:

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

Update the SXA add-on

To upgrade the SXA add-on:

Replace the following files with the 21.7 versions:
- src/assets/basic/_container.scss
- src/assets/sass/_app.scss

Update the /src/components/Image.tsx file as follows:

Import the CSSProperties type from the react package:
import React, { CSSProperties } from 'react';

Update the backgroundStyle constant definition to:

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

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.

We recommend you evaluate your needs in relation to GraphQL retries and use GraphQL request retry strategies as needed to mitigate rate limits in GraphQL endpoints.

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