Migrating Your Sitecore JSS App to Content SDK: A Complete Guide

As Sitecore continues its evolution toward a fully composable and cloud-native architecture, the Content SDK for XM Cloud marks a significant shift from the legacy JSS SDK. The Content SDK simplifies development, enhances performance, and introduces modern patterns for integrating Sitecore content into front-end applications.

In my previous blog post on the Sitecore XM Cloud Content SDK, I discussed the key differences between the JSS SDK and the Content SDK, along with some of the new concepts introduced in the Content SDK.

In today’s blog, I’ll walk you through how you can smoothly migrate your project to the Content SDK.

Prerequisites

Before you begin, make sure to:

Upgrade your existing app to JSS 22.8.
Review the Content SDK changelog to understand major updates.
Note that any customizations in your app may require additional migration effort.
Identify templates and add-ons used (nextjs, nextjs-xmcloud, nextjs-sxa, nextjs-multisite) from your package.json file.

Key Changes in the Content SDK

Page Editor Only: Experience Editor is no longer available.
Centralized Configuration Files:
- sitecore.config.ts for app configuration.
- sitecore.cli.config.ts for CLI configuration.
New API: SitecoreClient replaces old REST/GraphQL services.
Middleware Handling: defineMiddleware replaces middleware plugins.
Component Handling: component-map replaces componentBuilder.

Update Application Dependencies

To update your application dependencies:

In your existing app’s package.json, make the following changes:
- Replace "@sitecore-jss/sitecore-jss-nextjs" with "@sitecore-content-sdk/nextjs", and update all references accordingly.
- Delete the "@sitecore-jss/sitecore-jss-cli" dependency.
- Delete the "@sitecore-jss/sitecore-jss-dev-tools" dependency.
Install the dependencies: npm install

Create a Template Content SDK App

To create a new Next.js Content SDK application:

Run the following command in your terminal:

npx create-content-sdk-app@latest nextjs
Use the same prerendering mode (SSG or SSR) as your current app.
This new template app will serve as your reference for migration.

Update the Next.js Template Files in Your Existing App

Update Configurations

Follow these steps to update your JSS app configuration:

Copy the sitecore.config.ts file from your template app to your existing app.
Replace all imports of config from temp/config and use the new sitecore.config.ts file.
Example:

import config from 'temp/config';

should be replaced with

import scConfig from 'sitecore.config';
A new page parameter has been added to SitecoreContext.
To support this, set the api parameter to use scConfig.api and include the page parameter in the following files:
- [[...path]].tsx
- 500.tsx
- 404.tsx
Update the code as shown below:

const page = client.getPage(...);
<SitecoreContext ... api={scConfig.api} page={page} />

Update Environment Variables

SITECORE_API_KEY -> NEXT_PUBLIC_SITECORE_API_KEY

SITECORE_API_HOST -> NEXT_PUBLIC_SITECORE_API_HOST

SITECORE_SITE_NAME -> NEXT_PUBLIC_DEFAULT_SITE_NAME

DEFAULT_LANGUAGE -> NEXT_PUBLIC_DEFAULT_LANGUAGE

JSS_EDITING_SECRET -> SITECORE_EDITING_SECRET

SITECORE_EDGE_URL -> NEXT_PUBLIC_SITECORE_EDGE_URL

Refactor Components and Interfaces

Several files in your Next.js app need adjustments. Refactor components, interfaces, and utilities to align with the new Content SDK structure.

Copy src/components/SitecoreStyles.tsx from your template app into the same folder in your existing JSS app.
In Layout.tsx, import it as follows:

import SitecoreStyles from 'src/components/SitecoreStyles';

Update References

Components

SitecoreContext → SitecoreProvider

Interfaces

SitecoreContextProps → SitecoreProviderProps
SitecoreContextState → SitecoreProviderState
SitecoreContextReactContext → SitecoreProviderReactContext
WithSitecoreContextOptions → WithSitecoreOptions
WithSitecoreContextProps → WithSitecoreProps
WithSitecoreContextHocProps → WithSitecoreHocProps

Higher-Order Components

useSitecoreContext() → useSitecore()
withSitecoreContext() → withSitecore()

Properties

context → page
updateSitecoreContext → updatePage
sitecoreContext → page

Methods

getServerSideProps / getStaticProps → getComponentServerProps

Update Service References and Imports

RestComponentLayoutService -> ComponentLayoutService

RestComponentLayoutServiceConfig -> ComponentLayoutServiceConfig

GraphQLEditingService -> EditingService

GraphQLEditingServiceConfig -> EditingServiceConfig

GraphQLDictionaryService -> DictionaryService

GraphQLDictionaryServiceConfig -> DictionaryServiceConfig

GraphQLLayoutService -> LayoutService

GraphQLLayoutServiceConfig -> LayoutServiceConfig

GraphQLPersonalizeService -> PersonalizeService

GraphQLPersonalizeServiceConfig -> PersonalizeServiceConfig

GraphQLErrorPagesService -> ErrorPagesService

GraphQLErrorPagesServiceConfig -> ErrorPagesServiceConfig

GraphQLRedirectsService -> RedirectsService

GraphQLRedirectsServiceConfig -> RedirectsServiceConfig

GraphQLRobotsService -> RobotsService

GraphQLRobotsServiceConfig -> RobotsServiceConfig

GraphQLSiteInfoService -> SiteInfoService

GraphQLSiteInfoServiceConfig -> SiteInfoServiceConfig

GraphQLSitemapXmlService -> SitemapXmlService

GraphQLSitemapXmlServiceConfig -> SitemapXmlServiceConfig

GraphQLSitePathService -> SitePathService

GraphQLSitePathServiceConfig -> SitePathServiceConfig

Final Clean-Up

Remove all obsolete or replaced code and files as per the official documentation.
This includes legacy GraphQL, dictionary, layout, page-props, and middleware utilities now managed by the Content SDK.

Finally, ensure you:

Resolve all errors and warnings during migration.
Enable debug logging for Content SDK to identify any runtime issues.

Conclusion

Migrating from the JSS SDK to the Content SDK is a necessary step toward leveraging the full power of XM Cloud.
The new SDK simplifies configuration, reduces dependency complexity, and offers improved integration with the XM Cloud ecosystem.

While the migration process involves several structural updates, following this guide step by step will help you transition smoothly and ensure your application is ready for the modern Sitecore experience.