Real-Time Upgrade: JSS 22.6 → 22.10 & Next.js 14 → 15 (Sitecore XP 10.4)

Recently, I upgraded a production-based headless solution running on Sitecore XP from:

• JSS 22.6 → 22.10

• Next.Js 14 → 15

Instead of blindly upgrading packages, I followed a structured, comparison-based approach.

This blog documents the exact real-time steps, commands, issues, and validation checks.

Environment Details

• Backend: Sitecore XP 10.4

• Frontend SDK: Sitecore JSS

• Rendering Host: Next.js

• Serialization: Sitecore CLI

• Mode: Headless

Upgrading a Sitecore JavaScript Services SDK application can sound simple — bump versions and install — but in real apps there are a few key steps to get it right. Here’s a real-time upgrade walkthrough based on the official documentation for JSS Upgrade sitecore offical

Why Upgrade?

With JSS 22.10, Sitecore improved compatibility, stability, and updated dependencies — including Next.js. These updates help keep your project secure and aligned with modern frameworks.

Step 0 — Before You Begin

Pre-checks

Confirm your app jss version
Backup your code or use a feature branch
Review the JSS 22.10 changelog to catch anything custom you may need to address 

My current JSS SDK version is jss 22.6 as we can see in the below screen shot:

 Step 1 — Update Package Dependencies

Open package.json

Find all packages beginning with @sitecore-jss and update them to:

"@sitecore-jss/*": "~22.10.0"

Also update these peer dependencies to the versions required:

"next": "^15.5.10",
"sharp": "0.34.3",
"chokidar": "~4.0.3",
"cross-env": "~10.0.0",
"@types/react": "^19.1.7",
"@types/react-dom": "^19.1.7",
...
Updating JSS and core dependencies in package.json

Step 2 — Reinstall Dependencies

Once the versions are updated run : npm install  

This fetches the new packages and installs everything cleanly 

Step 3 - Create a JSS 22.10 Next.js application

In a console, run the following command:
  npx create-sitecore-jss@22.10 nextjs  

Step 4 - Compare Clean Codebases Against Existing Solution to Identify OOTB Changes

After creating a fresh Sitecore JSS 22.10 Next.js application, I did not immediately start migrating components.

Instead, I followed a critical step:

Compare the clean 22.10 codebase with the existing 22.6 solution to identify changes in Out-of-the-Box (OOTB) files.

This step ensured I didn’t miss structural, configuration, or dependency changes introduced in newer versions.To compare both projects efficiently, I used WinMerge (you can use any diff tool like Beyond Compare, VS Code Compare, etc.).

 Step 5- Moving Custom Components and Updating JSX in the New Project

After stabilizing the fresh Sitecore JSS 22.10 application and aligning the base template structure, the next step was clear:

Migrate custom components and 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';   

Final Upgrade Pattern That Worked

My proven sequence:

1. Create fresh 22.10 app

2. Build and run the freash app

3. Compare OOTB template with old project

4. Merge structural updates

5. Stabilizing the fresh

6. Move custom components

7. Update typings and JSX import

Upgrading from Sitecore JSS 22.6 to 22.10 was not just about updating dependencies — it was about respecting structural changes, stabilizing the new template, and carefully migrating custom components.

 If you are planning a similar migration, focus on structure before functionality

Happy Sitecore 🙌