JSS to Content SDK — Part 1: Upgrading Sitecore JSS from 22.4 to 22.10

Part 1 of a series on migrating from Sitecore JSS to the Sitecore Content SDK. We start here — getting your JSS project to 22.10 — because it’s the right foundation before the bigger move ahead.

Why Upgrade to JSS 22.10?

Before jumping into steps, it’s worth understanding what’s pushing this upgrade.

Sitecore is actively moving its Next.js story from the classic JSS SDK (@sitecore-jss/*) toward the new Sitecore Content SDK (@sitecore-content-sdk/*). The Content SDK targets React 19 and Next.js 15+ from the ground up — which means JSS 22.10 is increasingly the last meaningful stop before the full migration.

Staying on an older JSS version means:

• No clear upgrade path to React 19 or Next.js 15+
• Growing drift from Sitecore’s published reference architecture
• More upgrade debt piling up with every version you skip
• Missing stability, security, and compatibility improvements in each minor release

The good news? Getting to 22.10 is mostly painless — except for one phase.

The Big Picture: 5 Phases, One That Matters

The upgrade from 22.4 to 22.10 breaks down into five sequential phases:

PhaseVersion RangeWhat ChangesCode Changes?

1 ) 22.4 → 22.6Dependency bump❌ No

2 ) 22.6 → 22.7React 19 + Next.js 15⚠️ Yes

3)22.7 → 22.8Dependency bump❌ No

4)22.8 → 22.9Dependency bump❌ No

5)22.9 → 22.10Dependency bump❌ No

Important: Always complete each phase in order. Do not skip phases — intermediate versions may introduce transitive dependency requirements.

Four out of five phases are dependency-only bumps. Phase 2 is where React 19 and Next.js 15 land, and they bring breaking changes that require actual code edits. The rest of this post focuses there.

Phase 1 — JSS 22.4 → 22.6

Straightforward. Update your @sitecore-jss/* packages to ~22.6.0 in package.json, reinstall, and verify the build passes.

bash

npm install
npm run build

No code changes required.

Phase 2 — JSS 22.6 → 22.7 (The One That Requires Work)

This is the phase that actually requires attention. React 19 and Next.js 15 enforce stricter JSX and TypeScript patterns, and three specific code changes are needed before you run npm install.

Before You Touch package.json

A real-world tip worth emphasizing: do not just bump the versions and install. Instead:

1. Create a fresh JSS 22.7 (or 22.10) app using npx create-sitecore-jss@22.10 nextjs
2. Build and run it to confirm it works
3. Use a diff tool (WinMerge, VS Code Compare, Beyond Compare) to compare the clean scaffold against your existing project
4. Identify OOTB structural and configuration changes before you migrate anything custom

This step-first approach prevents you from missing structural changes that aren't obvious from package versions alone.

Code Change 1 — Explicit JSX Import

React 19 removes the global JSX transform. Any file that uses JSX.Element as a return type annotation now needs an explicit import.

Before:

tsx

import React from 'react';

After:

tsx

import { JSX } from 'react';

Note: If the file also uses hooks or other React APIs, keep both:

tsx

import React, { JSX } from 'react';

Search your codebase for JSX.Element and update every affected file.

Code Change 2 — Stricter useRef Initialisation

React 19 enforces that refs must explicitly include null in their type and be initialised with null. Untyped or uninitialised refs will throw TypeScript errors.

Before:

tsx

const scrollElementRef = useRef<HTMLDivElement>();

After:

tsx

const scrollElementRef = useRef<HTMLDivElement | null>(null);

Audit every useRef() call in your component files. This is the most common source of build failures after Phase 2.

Code Change 3 — Ref Type Assertion

In many components, React 19's stricter TypeScript typing causes a mismatch when passing refs to components that expect React.RefObject<T>. A type assertion resolves this.

Before:

tsx

<ScrollToFirstError
  errors={errors}
  submitCount={submitCount}
  formRef={formRef}
/>

After:

tsx

<ScrollToFirstError
  errors={errors}
  submitCount={submitCount}
  formRef={formRef as React.RefObject<HTMLFormElement>}
/>

Search your codebase for any prop typed as React.RefObject<T> and apply the assertion where needed.

Now Install and Verify

Once all three code changes are in place:

bash

npm install
npm run build

Phases 3, 4, and 5 — Smooth Sailing

Each of these is a dependency-only update. The process is the same for all three:

1. Update all @sitecore-jss/* versions to the target minor in package.json
2. Run npm install
3. Confirm the build passes with npm run build

No code changes required for any of these phases.

Other React 19 Changes Worth Knowing

In our project, the three changes above were the only ones that required attention. That said, React 19 does introduce other breaking changes — things like forwardRef being deprecated, ReactDOM.render being removed, defaultProps on function components being dropped, and the older Context.Consumer pattern being deprecated.

Whether these affect you depends entirely on your codebase. If your project uses any of these patterns, you’ll want to address them too. The official React 19 upgrade guide is the best reference for a full list.

Troubleshooting

**npm install fails**

Clear node_modules and package-lock.json, then reinstall. Check that all @sitecore-jss/* packages are on the same minor version — mixing versions is the most common cause of peer dependency conflicts. If conflicts persist, investigate each one properly rather than working around them — unresolved peer dependency issues tend to surface as harder-to-debug runtime problems later.

Build fails after Phase 2

Run these targeted searches:

• Search for useRef() — confirm every instance has | null and is initialised with null
• Search for JSX.Element return type annotations — confirm { JSX } is imported from 'react'
• Search for any prop typed as React.RefObject<T> — confirm the type assertion is applied

Rolling back

To roll back a phase, revert package.json to the previous version range and run npm install. The code changes from Phase 2 are forward-compatible — they don't need to be reverted for phases 3–5.

Migration Checklist

• Phase 1: Updated @sitecore-jss/* to ~22.6.0 and run npm install
• Phase 2: Updated @sitecore-jss/* to ~22.7.0
• Phase 2: Replaced React default import with { JSX } where required
• Phase 2: Updated all useRef() to include | null and null initialiser
• Phase 2: Added type assertions for props typed as React.RefObject<T>
• Phase 2: Run npm install and confirmed build passes
• Phase 3: Updated @sitecore-jss/* to ~22.8.0 and run npm install
• Phase 4: Updated @sitecore-jss/* to ~22.9.0 and run npm install
• Phase 5: Updated @sitecore-jss/* to ~22.10.0 and run npm install
• Final: npm run build passes with no errors on 22.10

What's Next — The Content SDK Migration Series

Getting to JSS 22.10 is a solid milestone — but it's also the starting point for something bigger. This post is Part 1 of a series walking through the full journey from Sitecore JSS to the Sitecore Content SDK.

Here's where we're headed:

• Part 1 (this post): Upgrading JSS from 22.4 to 22.10
• Part 2: Migrating from @sitecore-jss/* to @sitecore-content-sdk/*
• Part 3 and beyond: App Router adoption, React 19 baseline, XM Cloud architecture, and more

The Content SDK migration is a bigger lift — new package structure, new rendering patterns, new configuration approach. But 22.10 is exactly the right foundation to start from, and we'll cover every step in detail.

Stay tuned for Part 2.