migrating-your-sitecore-jss-app-to-content-sdk-a-complete-guide

By: Koushik MukherjeeNovember 15, 2025

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:

  1. 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.

  2. Install the dependencies:Ā npm install

Create a Template Content SDK App

To create a newĀ Next.js Content SDKĀ application:

  1. Run the following command in your terminal:

    npx create-content-sdk-app@latest nextjs

  2. Use the same prerendering mode (SSGĀ orĀ SSR) as your current app.

  3. 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:

  1. Copy theĀ sitecore.config.tsĀ file from your template app to your existing app.

  2. 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';

  3. 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.

References:

Migrate JSS 22.8 Next.js apps to Content SDK 1.0

Content SDK MigrationJSS to Content SDKSitecoreSitecore Content SDKSitecore DevelopmentSitecore JSSSitecore JSS SDKSitecore MigrationSitecore XM Cloud
Two CMSs, One Website: Managing Routing During WordPress to Sitecore MigrationMastering Identity Resolution in Sitecore CDP: Anonymous to Known Visitors