Upgrade JSS 22.2 Next.js apps to version 22.3

Version:

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

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

XM Cloud is now SitecoreAI

Some code examples, images, and UI labels may still use XM Cloud while engineering assets are being updated.

nextjs
nextjs-xmcloud
nextjs-sxa
nextjs-multisite

Before you begin

If you haven't already done so, upgrade your app to JSS 22.2.
Upgrade Node to version 22 or later.
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 covered in this topic.

This topic describes how to:

Update application dependencies in your existing app

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

To update your dependencies:

In your existing application's package.json file, update the following packages to the stated versions:

Update every @sitecore-jss package to version ~22.3.0.

Update the following packages to the stated versions:

Package	New version
`@types/node`	`^22.9.0`
`@typescript-eslint/eslint-plugin`	`^8.14.0`
`@typescript-eslint/parser`	`^8.14.0`
`eslint`	`^8.56.0`
`typescript`	`~5.4.0`

Install the dependencies with the following command:
npm install

In .eslintrc, add the following rule or modify your existing rule to match:

"@typescript-eslint/no-unused-vars": [
  "error",
  {
    "caughtErrorsIgnorePattern": "."
  }
],

In tsconfig.json, directly above the "lib" entry, add the following:
... "types": ["node"], ...

Create a JSS 22.3 Next.js application

To simplify the upgrade process as much as possible, create a JSS 22.3 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 22.3 Next.js application with the XM Cloud add-on included:

In a console, run the following command:
npx [email protected] nextjs
If prompted to install the [email protected] package, answer y.
Enter the folder path for the JSS 22.3 Next.js app. For example, enter ./jss223, 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 y to install the XM Cloud add-on.
Select other add-ons used by your existing application and press Enter.

The script then installs the application dependencies.

XM Cloud is now SitecoreAI

Some code examples, images, and UI labels may still use XM Cloud while engineering assets are being updated.

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 22.3 app.

To update the Next.js template files:

If you have not customized the scripts/config/plugins/scjssconfig.ts file, replace it with the 22.3 version. Otherwise, modify your file as follows:

Locate the following code:

try {
  scJssConfig = require('scjssconfig.json');
} catch (e) {
...

Modify it by adding an ESLint rule override as follows:

try {
  // eslint-disable-next-line @typescript-eslint/no-require-imports
  scJssConfig = require('scjssconfig.json');
} catch (e) {
...

If you have not customized the scripts/generate-component-builder/index.ts file, replace it with the 22.3 version. Otherwise, modify your file as follows:
- Locate the following rule:
  // eslint-disable-next-line @typescript-eslint/no-var-requires
- Replace it with the following:
  // eslint-disable-next-line @typescript-eslint/no-require-imports
If you have not customized the scripts/scaffold-component/index.ts file, replace it with the 22.3 version. Otherwise, modify your file as follows:
- Locate the following rule:
  // eslint-disable-next-line @typescript-eslint/no-var-requires
- Replace it with the following:
  // eslint-disable-next-line @typescript-eslint/no-require-imports
If you have not customized the scripts/config/index.ts file, replace it with the 22.3 version. Otherwise, modify your file as follows:
- Locate the following rule:
  // eslint-disable-next-line @typescript-eslint/no-var-requires
- Replace it with the following:
  // eslint-disable-next-line @typescript-eslint/no-require-imports
If you have not customized the scripts/utils.ts file, replace it with the 22.3 version. Otherwise, modify your file as follows:
- Locate the following:
  cb && cb(name);
- Replace it with the following:
  if (cb) cb(name);

Update the nextjs-xmcloud add-on

To update the nextjs-xmcloud add-on:

If you have not customized the src/lib/page-props-factory/plugins/content-styles.ts file, replace it with the 22.3 version. Otherwise, modify it as follows:
- Locate the following:
  contentStyles && props.headLinks.push(contentStyles);
- Replace it with the following:
  if (contentStyles) props.headLinks.push(contentStyles);

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!