Upgrade JSS 22.11 Next.js apps to version 22.12

Upgrading a Sitecore JSS 22.11 Next.js application to version 22.12 might look like a small version change, but in reality, it involves several important updates. Because every project is a bit different—especially in the JavaScript and Next.js world—you may need to make additional adjustments depending on how customized your application is.

Before starting, it’s a good idea to check which templates and add-ons your app is using. You can find these in your package.json. A typical JSS 22.11 setup, especially one based on the XM Cloud starter foundation, might include things like nextjs, nextjs-styleguide, nextjs-sxa, and nextjs-multisite. Also, keep in mind that XM Cloud is now being referred to as SitecoreAI, although you may still see the old name in code or documentation.

The first step is preparation. If your app isn’t already on JSS 22.11, you’ll need to upgrade to that version first. It’s also worth reviewing the changelog, especially if your application includes custom code. The changelog often highlights changes that might not be obvious but could still affect your implementation.

Once you’re ready, start by updating your dependencies. In your package.json, update all @sitecore-jss packages to version ~22.12.0. Along with that, you’ll need to align your environment with newer platform versions. Node.js is now version 24, and Next.js has been upgraded to version 16. This means updating related dependencies like @types/node and next. After making these changes, run npm install to install everything.

During this step, you might run into type-related issues. One common example is errors involving JSX.Element. If that happens, the fix is usually simple—just import the JSX type from React where needed. These kinds of issues are normal when working with newer versions of TypeScript and React.

To make the upgrade process easier, it’s highly recommended to create a fresh JSS 22.12 Next.js application. This gives you a clean reference to compare against your existing project. You can generate one using the create-sitecore-jss command and select the same options your current app uses, such as GraphQL or REST for data fetching, and SSG or SSR for rendering. Make sure to include the XM Cloud (SitecoreAI) add-on and any other add-ons your app depends on. Once created, this new project will help you identify exactly what has changed.