Migrating from JSS to Sitecore Content SDK 1.x in SitecoreAI (XM Cloud) – SDK Lifecycle Deep Dive

While working hands-on with the official Sitecore PLAY! Summit demo – one of the most complex, production-grade JSS applications in the ecosystem (50+ components, multisite middleware, OrderCloud, Sitecore Search, Content Hub DAM, Auth0, and more) – I attempted a full migration to Sitecore Content SDK 1.2.1.

The results from the completed phases were impressive: bundles ~45% smaller, dramatically fewer files touched, and far simpler services – even before finishing the component migration. This post is the real-world chronicle of that journey, refined into a repeatable, Next.js-focused guide you can apply today.

Whether you’re preparing for the 2026 JSS sunset or simply want a leaner, SitecoreAI-ready codebase, here’s everything I learned – the wins, the pitfalls, and the exact commands that actually worked.

Why Migrate PLAY! Summit (and Your App) to Content SDK?

Bottom line: Content SDK isn’t “JSS lite” – it’s the version Sitecore built specifically for XM Cloud and SitecoreAI.

My Migration Status (Honest Update – November 22, 2025)

Completed & Working

• Node.js 22 + Next.js 15 + React 19 upgrade
• JSS 22.8 baseline → All JSS packages removed cleanly
• Content SDK 1.2.1 installed without conflicts
• Centralized sitecore.config.ts + sitecore.cli.config.ts
• All services (layout, dictionary, editing) migrated to SitecoreClient
• Solid foundation ready for the rest

Still Pending

• Updating 50+ components (field helpers, context, etc.)
• Complex middleware plugins (multisite, personalization, redirects)
• Third-party integrations (OrderCloud, Search, CDP, Auth0)
• Full regression testing

Verdict: The foundation is already cleaner and faster than the original JSS version – finishing the migration (or starting fresh) is absolutely worth it.

Pre-Migration Checklist

1. Node.js 22+ – Non-negotiable (nvm use 22.17.1)
2. Upgrade to JSS 22.8.0 (required bridge step)
3. Create a Git branch: feature/content-sdk-migration
4. Backup .env and take an XM Cloud environment snapshot

Spin up a reference app:

npx create-content-sdk-app@latest play-summit-reference --template nextjs

Step-by-Step Migration Guide (Next.js – What Actually Worked on PLAY!)

1. Dependency Overhaul

# CRITICAL: Must be on Node.js 22
node --version   # → v22.x.x

# Remove ALL JSS packages in ONE command
npm uninstall @sitecore-jss/sitecore-jss-nextjs \
  @sitecore-jss/sitecore-jss-cli \
  @sitecore-jss/sitecore-jss-dev-tools \
  @sitecore-jss/sitecore-jss-react --legacy-peer-deps

# Install ONLY the Next.js SDK (core is pulled automatically)
npm install @sitecore-content-sdk/nextjs@latest --legacy-peer-deps

Golden Rule: Never install both @sitecore/content-sdk and @sitecore-content-sdk/nextjs explicitly – it breaks the dependency tree.

2. Central Configuration

sitecore.config.ts (project root)

import { defineSitecoreConfig } from '@sitecore-content-sdk/nextjs';

export const sitecoreConfig = defineSitecoreConfig({
  siteName: process.env.SITECORE_SITE_NAME!,
  apiKey: process.env.SITECORE_API_KEY!,
  endpoint: process.env.SITECORE_API_URL!,
  editingSecret: process.env.SITECORE_EDITING_SECRET!,
  edgeUrl: process.env.NEXT_PUBLIC_SITECORE_EDGE_URL!,
  defaultLanguage: 'en',
  generateStaticPaths: process.env.GENERATE_STATIC_PATHS === 'true',
  rootPlaceholders: ['headless-header', 'headless-main', 'headless-footer'],
});

Update .env.local

# OLD → NEW
SITECORE_API_HOST=...          → SITECORE_API_URL=...
JSS_EDITING_SECRET=...         → SITECORE_EDITING_SECRET=...
DISABLE_SSG_FETCH=false        → GENERATE_STATIC_PATHS=true
SITECORE_EDGE_URL=...          → NEXT_PUBLIC_SITECORE_EDGE_URL=...

3. Unified SitecoreClient

src/lib/sitecore-client.ts

import { createSitecoreClient } from '@sitecore-content-sdk/nextjs';
import { sitecoreConfig } from '../../sitecore.config';

export const sitecoreClient = createSitecoreClient(sitecoreConfig);

Layout service example (70% less code):

import { sitecoreClient } from './sitecore-client';

export async function getLayoutData(path: string, language: string) {
  return await sitecoreClient.layout.fetch({ path, language });
}

4. Explicit Component Mapping

src/lib/component-map.ts

import Hero from '@/components/Hero';
import ContentBlock from '@/components/ContentBlock';
// …import all components

export const componentMap = {
  Hero,
  ContentBlock,
  // Use exact datasource template names!
};

5. Component Updates

// Before (JSS)
import { Text, Image } from '@sitecore-jss/sitecore-jss-nextjs';

// After (Content SDK)
import { Text, Image } from '@sitecore-content-sdk/nextjs';

Also use rendering.uid for keys and remove chromes.

6. Middleware – The Modern Way

import { defineMiddleware } from '@sitecore-content-sdk/nextjs';
import { sitecoreConfig } from './sitecore.config';

export default defineMiddleware({
  config: sitecoreConfig,
  async redirect(req) { /* logic */ },
  async personalize(req) { /* logic */ },
});

export const config = { matcher: '/((?!api|_next/static|_next/image|assets|favicon.ico|sw.js).*)' };

7. Dynamic Route Page ([[...path]].tsx)

import { SitecoreProvider, ComponentRenderer } from '@sitecore-content-sdk/nextjs';
import { componentMap } from '@/lib/component-map';

export default function SitecorePage({ layoutData }: SitecorePageProps) {
  return (
    <SitecoreProvider config={sitecoreConfig} componentMap={componentMap}>
      {layoutData.sitecore.route?.placeholders['headless-main']?.map(c => (
        <ComponentRenderer key={c.id} component={c} />
      ))}
    </SitecoreProvider>
  );
}

Common Pitfalls & Fixes from the PLAY! Trenches

SitecoreAI Advantages You’ll Feel Immediately

• Native @sitecore-cloudsdk/events → events flow straight into SitecoreAI for smarter personalization
• Smaller payloads = faster variant delivery
• XM Cloud Pages is noticeably snappier without chromes

In my benchmarks, Time-to-Interactive dropped ~35% on the homepage.

Summary

The PLAY! Summit foundation on Content SDK is already cleaner, faster, and more future-proof than the original JSS version – and I’m only halfway through.

Start with the dependency + config steps, measure the immediate bundle wins, then decide: finish the migration or spin up a fresh Content SDK app and port features incrementally.

Resources

• Official Migration Guide → https://doc.sitecore.com/sai/en/developers/content-sdk/migrate-jss-22-8-next-js-apps-to-content-sdk-1-0.html
• PLAY! Summit Repo → https://github.com/Sitecore/Sitecore.Demo.XmCloud.PlaySummit
• https://explorewithnikitavashisht.wordpress.com/2025/09/04/migrating-next-js-apps-to-sitecore-content-sdk/
• https://medium.com/@gaur.arun777/blog-1-introduction-to-sitecore-content-sdk-17b64ae1e30e