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

_ _ Koushik Mukherjee
Sitecore (Koushik) Technology

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

♥
×