With the end of technical support for Sitecore JSS scheduled for June 2026, teams running XM Cloud must transition to Content SDK 2.1. This update is more than a simple library swap, it is an architectural re-engineering that optimizes content delivery and natively unlocks the real-time personalization capabilities of the SitecoreAI platform.
On the left, the legacy framework carries a heavy ~8.15 MB footprint driven by dual-purpose abstractions and outdated page routing. Conversely, the right side highlights the optimized SitecoreAI integration, where advanced tree-shaking and native React Server Components (RSC) slash the final bundle size below 1 MB delivering a 49% reduction in bundle overhead, 81% fewer files, and 39% less code.
JSS vs. Content SDK: Key Differences
The Content SDK abandons JSS’s monolithic design in favor of a decoupled, modular model, drastically reducing client bundle sizes.
Runtime Comparison
| Parameter | Sitecore JSS 22.0 | Sitecore Content SDK 2.1 |
|---|---|---|
| Required Node.js | >= 18 or 20 | >= 24 |
| Compatible Next.js | ^15.0.0 | 16.2 |
| Architecture | Unified Monolithic | Modular by responsibilities |
| Routing | Traditional JSS Middleware | Optimized Proxies & Route Handlers |
| Layout Access | Manual GraphQL Queries | Unified SitecoreClient Class |
1. Environment Cleanup & Dependencies
Before refactoring your application, clean up package.json to prevent dependency resolution conflicts during build time
1.1 Package Replacement
Uninstall deprecated JSS modules and install the modular SDK 2.1 packages
# 1. Uninstall legacy JSS packages
npm uninstall @sitecore-jss/sitecore-jss-nextjs @sitecore-jss/sitecore-jss-cli @sitecore-jss/sitecore-jss-dev-tools
# 2. Install the new Content SDK ecosystem
npm install @sitecore-content-sdk/nextjs @sitecore-content-sdk/react @sitecore-content-sdk/core @sitecore-content-sdk/events
1.2 Environment Variables (.env) Map
The Content SDK simplifies environment configuration by resolving endpoints internally rather than requiring rigid configuration variables
| JSS 22.0 Variable (Legacy) | New SDK 2.1 Variable | Action / Behavior |
|---|---|---|
| SITECORE_API_KEY | NEXT_PUBLIC_SITECORE_API_KEY | Keep value |
| SITECORE_API_HOST | NEXT_PUBLIC_SITECORE_API_HOST | Keep value |
| SITECORE_SITE_NAME | NEXT_PUBLIC_DEFAULT_SITE_NAME | Rename |
| JSS_EDITING_SECRET | SITECORE_EDITING_SECRET | Rename |
| DISABLE_SSG_FETCH | GENERATE_STATIC_PATHS | Rename |
| GRAPH_QL_ENDPOINT | Remove | No longer required |
2. Code Refactoring
2.1. SitecoreClient Initialization
Dynamic configuration generation inside temporary directories (temp/config) has been removed. The SDK now relies on a static sitecore.config.ts file in the root directory to initialize the unified client
// src/lib/sitecore-client.ts
import scConfig from 'sitecore.config';
import { client } from 'lib/sitecore-client';
// Inside your data fetcher (getStaticProps or getServerSideProps):
const page = await client.getPage({
path: context.params?.path,
language: context.locale,
});
// Inside your root React component:
<SitecoreContext api={scConfig.api} page={page}>
<Component {...pageProps} />
</SitecoreContext>
2.2. Proxy Implementation (Replacing Middleware)
To avoid performance overhead on every HTTP request, complex routing and URL rewrites in Next.js have moved from middleware.ts to chained proxy definitions
Rename middleware.ts to proxy.ts inside the src/ directory and configure sequential execution
// src/proxy.ts
import { NextRequest } from 'next/server';
import { defineProxy } from '@sitecore-content-sdk/nextjs/proxy';
export default function proxy(req: NextRequest) {
// Internal initialization of sub-proxies (locale, multisite, redirects, personalize)
return defineProxy(locale, multisite, redirects, personalize).exec(req);
}
export const config = {
matcher: [
/* Route path matching patterns */
],
};Critical Execution Order for App Router:
- Locale
- Multisite
- Redirects
- Personalize
2.3. React Placeholder Declarations
The React component wrapper API has been simplified. Instead of using dynamic string declarations inside the wrapper function, placeholders are now injected as a unified property on props
Legacy JSS Implementation
import { withPlaceholder, PlaceholderProps } from '@sitecore-jss/sitecore-jss-nextjs';
const Home: React.FC<PlaceholderProps> = ({ pageContent }) => (
<div className="container">{pageContent}</div>
);
export default withPlaceholder('page-content')(Home);Content SDK 2.1 Implementation:
import { withPlaceholder } from '@sitecore-content-sdk/react';
type HomeProps = {
placeholders: Record<string, React.ReactNode>;
};
const Home: React.FC<HomeProps> = ({ placeholders }) => (
<div className="container">
{placeholders['page-content']}
</div>
);
export default withPlaceholder(Home);2.4. State Management with PageMode
Multiple legacy Boolean flags (pageEditing, pageState) have been deprecated. They are now unified into a single structured PageMode object within the retrieved page data.
// Native state checking in SDK 2.1
if (page.mode.isDesignLibrary) {
// Render layout builder options or editing UI
}
Recomendations
- DO: Remove all references to headLinks. The Content SDK automatically manages meta tag and resource injection. Keeping legacy links causes duplicate DOM nodes and slows page rendering.
- DO: Call setCachedPageParams in Next.js App Router layouts. This ensures static error pages (such as 404) resolve the correct language and site context on CDN nodes.
- DON’T: Maintain legacy REST calls or use getErrorPages(). Transition to getErrorPage(), which drastically reduces the payload size retrieved from Experience Edge.
- DON’T: Attempt to compile SDK 2.1 on Node.js < 24. The internal compilation and streaming engine utilizes native runtime features introduced in modern Node versions.
Migration Automation
For enterprise-scale applications containing hundreds of components, manual refactoring is slow and error-prone. It is highly recommended to leverage the SitecoreAI SDK Upgrade Assistant.
This assistant combines deterministic scripts to clean up dependencies and rewrite .env files, with specialized AI agents that scan your React component structures to automatically translate and re-map JSS placeholder wrappers into Content SDK properties.
References
- Sitecore Product Lifecycle Guidelines. XM Cloud Support and Deprecation Roadmap for JSS Packages.
- SitecoreAI Technical Case Studies. Reducing Maintenance Overhead with the Automated Upgrade Assistant.
- Sitecore Developer Portal (2026). Upgrade JSS 22.0 Next.js Apps to Content SDK 2.1.
- Sitecore Content SDK Architectural Documentation (v2.1). Transitioning from Layout Service API to Unified SitecoreClient.
- Sitecore Content SDK 2.1 Release Notes. Changelogs, Route Handlers, and PageMode API Implementations. May 2026.
- Sitecore Headless Services Development Best Practices. Configuring Environment Variables and Clean Build Pipelines.
- Edge Routing Patterns in XM Cloud Deployments. Replacing Next.js Middlewares with Proxy Chains for High Performance.
