Reading time: 6 min read
Upgrading SitecoreAI from JSS to CDK 2.0
A practical look at what really changes when you move a SitecoreAI project from legacy JSS patterns to the newer CDK 2.0 model.
What really changes when you move a SitecoreAI project from legacy JSS patterns to the newer CDK 2.0 model
Upgrading a SitecoreAI project from JSS to CDK 2.0 is the kind of task that sounds smaller than it really is. On paper, it looks like a framework migration. In practice, it's a shift in how you think about the project structure, developer workflow, and the boundary between Sitecore specific implementation details and the application code sitting around them.
So if you're planning on migrating to CDK 2.0, the first thing you need to understand is this: this is not a change of a couple of packages and hope for the best upgrade.
You can absolutely get through it cleanly, but only if you treat it like a proper migration.
What CDK 2.0 changes
The move from JSS to CDK 2.0 is not just a rename.
It reflects a broader push toward a more modern, cleaner and more opinionated development model for SitecoreAI projects. The goal is better alignment with current framework patterns, better tooling, and a clearer foundation for future development.
The uncomfortable version is that older JSS based solutions carry a lot of historical baggage.
- Custom scaffolding assumptions
- Inconsistent component patterns
- Legacy config habits
- Old rendering conventions
- Dependency drift
- Patchwork local fixes from previous upgrades
Before your upgrade, figure out what kind of project you actually have
This matters more than people think. Not every JSS project is equally hard to migrate.
A fairly clean implementation with modern React or Next.js patterns, good component boundaries, and restrained customization is one thing. A long-lived project with years of upgrades, custom pipelines, edge-case rendering logic, and unclear ownership is something else entirely.
Before touching this upgrade, review the following:
- Current JSS version
- Framework version and runtime requirements
- Custom build or deployment scripts
- Rendering host assumptions
- Sitecore specific integration points
- Environment configuration
- Personalization, editing, and preview dependencies
- Any custom abstractions built on top of JSS
You need to know where the weird parts are, because there will be weird parts.
Start with the official upgrade guidance, but do not stop there
Any migration like this should begin with the official SitecoreAI / CDK upgrade path and release notes.
That gives you the baseline:
- Required package changes
- Breaking changes
- Deprecated APIs
- Runtime updates
- Framework expectations
- New project conventions
But that is only the starting point, official guides tell you what changed. They do not tell you how messy your own project is. That part is still your problem.
A practical upgrade approach
The safest way to move from JSS to CDK 2.0 is to treat it as a staged migration. Not a one-shot leap. You will want to upgrade from each major release to the next. For example, if you are on JSS SDK 22.6.0 you will need to upgrade to 22.7.0 then 22.8.0, then on to CDK 1.0, from there CDK 1.1, then CDK 1.2, then 1.3, then 1.4, then 1.5. From there you can upgrade to CDK 2.0.
- Stabilize the current project first
If the current JSS implementation is already shaky, fix the obvious instability before migrating. That includes things like:
- Flaky builds
- Inconsistent local setup
- Failing tests
- Deprecated framework usage you already know about
- Components that only work because everyone is afraid to touch them
Do not upgrade from chaos, you will just get newer chaos.
- Audit dependencies and runtime associations
CDK 2.0 is likely to come with updated expectations around framework and runtime versions.
Check:
- Node version
- Package manager behaviour
- Framework compatibility
- TypeScript versioning
- Linting and build tooling
- CI/CD agent images
A lot of upgrade pain comes from infrastructure mismatch, not the application code itself.
- Identify the JSS-specific patterns you need to replace
This is where the real work will be done. Find the places where your project is tightly coupled to older JSS conventions, that might include:
- Data-fetching patterns
- Component registration assumptions
- Route and layout handling
- Rendering engine glue code
- Editor or preview integration points
- Custom helper utilities that wrap older APIs
You need to know what is genuinely framework-specific versus what is just normal application logic. That separation makes the migration far easier.
- Migrate the shell before the details
A good rule of thumb here is to get the outer structure working first.
Focus on:
- Project bootstrapping
- App startup
- Route resolution
- Layout rendering
- Editing / preview basics
- Core environment configuration
Once the shell is stable, then move deeper into component-level behaviour and special cases.
If you do this in the opposite order, you end up debugging everything at once. That's miserable.
- Upgrade a representative slice, not every page at once
Pick a realistic path through the application.
For example:
- One route
- A handful of common components
- A layout with real placeholders or content regions
- Editing support
- One or two personalized or data-driven components
This becomes your proof that the migration approach actually works. If that slice is healthy, expand outward. If it isn't, stop and fix the pattern before copying the problem everywhere.
- Be suspicious of anything "temporarily" shimmed
During migrations, teams love compatibility shims. Some are necessary, but too many become permanent.
If you add temporary wrappers, transitional helpers, or compatibility layers, track them aggressively. Otherwise you finish the migration and discover you're still carrying half the old system inside the new one, which defeats the point.
The areas most likely to bite you
These are the places I would expect the most trouble.
Rendering and layout assumptions
Anything tied to route composition, placeholders, layout services, or component data contracts deserves extra attention.
Even small differences in how data is shaped or how rendering flows through the app can create lots of annoying downstream issues.
Editing and preview behaviour
A migration is not successful just because the public site renders.
If authoring, preview, or editing workflows break, your content team will find out fast.
And they will be right to complain.
Test these explicitly:
- Page editing
- Component insertion
- Content refresh behaviour
- Preview rendering
- Error handling in authoring scenarios
Personalization and conditional rendering
If the existing project has personalization logic, pay close attention to how those decisions are applied and how data reaches the components involved.
This is one of those areas where "mostly working" is often not actually working.
Build and deployment pipelines
A migration can look fine locally and still fail in CI or production because of:
- Different node versions
- Missing environment variables
- Changed build commands
- Container image mismatches
- Stricter linting or type checks
Always assume deployment will reveal something your local machine politely ignored.
What a good upgrade looks like
A successful JSS to CDK 2.0 migration should leave you with:
- A cleaner project structure
- Fewer legacy abstractions
- Clearer boundaries between app code and platform integration
- Current runtime support
- Predictable local setup
- Working editing and preview flows
- Simpler future upgrades
That last point really matters. A migration should not get you onto the new stack. It should reduce the amount of future pain.
If the new solution is just as fragile as the old one, something went wrong.
What not to do
A few things are especially good at turning this into a mess.
Don't migrate and redesign everything at the same time
This is a classic mistake. If you change the framework, redesign the component architecture, overhaul the content model, and rewrite the deployment pipeline all at once, you create far too many moving parts.
Pick your battles.
Don't keep every old abstraction out of nostalgia
Some custom wrappers deserve to die.
If a helper only exists to hide an old JSS pattern that CDK 2.0 no longer needs, removing it is a feature, not a loss.
Don't ignore author experience
Developers often judge the migration by whether the app compiles.
Authors judge it by whether they can do their jobs.
The authors are not wrong.
Recommended rollout strategy
Make sure to do this carefully:
- Upgrade in a branch with room for iteration
- Migrate a representative vertical slice first
- Validate editing and preview early
- Compare production behaviour, not just code output
- Run parallel QA for both developer and author workflows
- Cut over only when the new implementation is boringly reliable
Because reliable is what we're looking for.
Final thoughts
Upgrading from SitecoreAI JSS to CDK 2.0 is a lot of work, but worth doing, but only if you approach it like a real migration and not a simple package refresh.
The technical changes matter, but the bigger opportunity is to clean up the years of accidental complexity that older JSS projects tend to accumulate.
If you do it well, CDK 2.0 can give you a more modern foundation, a cleaner development model, and a project that is easier to understand six months later.