Upgrade JSS 22.0 Next.js apps to version 22.1

Version: 22.x

This topic covers most of the changes you must make to your existing JSS 22.0.0 applications to benefit from the latest improvements in version 22.1. 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.0.0 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 22.0.0.

  • 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 22.1 Next.js application.

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

  4. Update the SXA add-on.

  5. Replace the import path for editing utilities.

Update application dependencies in your existing app

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

To update your dependencies:

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

    • Update every @sitecore-jss package to version ~22.1.

    • Update the @types/node package to version ^20.14.2.

  2. Install the dependencies with the following command:

    RequestResponse
    npm install

  3. We highly recommend you install version 0.32.6 of the sharp image processing library using the following command. This is to improve memory usage of the image optimization feature:

    RequestResponse
    npm i [email protected]

Create a JSS 22.1 Next.js application

To simplify the upgrade process as much as possible, create a JSS 22.1 Next.js application. You can then copy some files from this app into your existing app.

To create a JSS 22.1 Next.js application:

  1. In a console, run the following command:

    RequestResponse
    npx [email protected] nextjs

  2. If prompted to install the [email protected] package, answer y.

  3. Enter the folder path for the JSS 22.1 Next.js app. For example, enter ./jss221, 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 to skip installing the XM Cloud add-on.

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

To update the Next.js template files:

  1. If you have not customized the scripts/generate-config.ts file, replace it with the 22.1 version. Otherwise, modify your file as follows:

    • In the configText prop assignment, add a trim method call after config[prop]?, such as:

      RequestResponse
      config[prop]?.trim()

    • At the end of that assignment, replace the comma before the newline character with a semicolon:

      RequestResponse
      // Before
}',\n`;

// After
}';\n`;

    Here's an example of the updated assignment suitable for JSS 22.1:

    RequestResponse
    configText += `config.${prop} = process.env.${constantCase(prop)} || '${config[prop]?.trim()}';\n`;

  2. If you have not customized the the lib/next-config/plugins/cors-header plugin, replace it with the 22.1 version. Otherwise, modify your file as follows:

    • Because cross-origin resource sharing (CORS) is now handled by API handlers or middleware, remove the following CORS header for API endpoints:

      RequestResponse
      {
  source: '/api/:path*',
  headers: [
    {
      key: 'Access-Control-Allow-Origin',
      value: config.sitecoreApiHost.replace(/\/$/, ''),
    },
  ],
},

  3. Because ComponentConsumerProps has been removed, if you have any import statements that reference it, update them all to use WithSitecoreContextProps instead.

  4. Because the resolvePageUrl function now accepts an object, and because serverUrl is now optional, the latter is omitted if the metadata edit mode for Pages is enabled. If you've customized the pages/api/editing/render.ts file and you currently pass the resolvePageUrl function into EditingRenderMiddleware, modify your file as follows:

    • Replace the existing handler initialization with the following:

      RequestResponse
      const handler = new EditingRenderMiddleware({
  resolvePageUrl: ({ serverUrl, itemPath }) => `${serverUrl}${itemPath}`,
}).getHandler();
    Note

    If you haven't customized pages/api/editing/render.ts, you don't need to make any new changes to it for this release.

  5. If your app contains any references to the now-deprecated EditingComponentPlaceholder or the RenderingType enum, such as the following example in [[...path]].tsx, delete them:

    RequestResponse
    import Layout from 'src/Layout';
import { RenderingType, EditingComponentPlaceholder } from '@sitecore-jss/sitecore-jss-nextjs';
...
const isComponentRendering =
  layoutData.sitecore.context.renderingType === RenderingType.Component;
...
{isComponentRendering ? (
  <EditingComponentPlaceholder rendering={layoutData.sitecore.route} />
) : (
  <Layout layoutData={layoutData} headLinks={headLinks} />
)}

Update the SXA add-on

To upgrade the SXA add-on:

  • Replace the following files with the new versions from your 22.1 app:

    • src/components/Image.tsx 

    • src/components/Promo.tsx 

    • src/components/Title.tsx 

    • src/assets/sass/components/title/_component-title.scss 

Replace the import path for editing utilities

We're moving all editing utilities currently located at @sitecore-jss/sitecore-jss/utils, so if you currently refer to this path in any of your import statements you will need to update them to use the new path @sitecore-jss/sitecore-jss/editing instead.

This change affects the following utilities:

  • ChromeCommand 

  • DefaultEditFrameButton 

  • DefaultEditFrameButtonIds 

  • DefaultEditFrameButtons 

  • EditButtonTypes 

  • EditFrameDataSource 

  • ExperienceEditor 

  • FieldEditButton 

  • handleEditorAnchors 

  • HorizonEditor 

  • isEditorActive 

  • mapButtonToCommand 

  • Metadata 

  • resetEditorChromes 

  • WebEditButton 

Warning

The older path will only continue to work until the next release of JSS. Therefore, we strongly recommend you make the necessary changes as soon as possible.

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.

Do you have some feedback for us?

If you have suggestions for improving this article,