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:

  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

Comments

Post a Comment

Popular posts from this blog

Setup New Project in Sitecore XMCloud – Part 1

Image
In my previous blog , I discussed about the XMCloud Introduction and features of XMCloud. In this blog I will show, how to create a new Project and environments in the Sitecore XM cloud. In the next blog, I will show how easily you can set up your local app development for XM Cloud and run the Sitecore XM Cloud project on your development machine. Prerequisites: • You must have one Organization account in Sitecore portal ( https://portal.sitecorecloud.io/ ) which has access to XMCloud.  And your account should be associated with that Organization account with admin access.  • Organization must have proper Sitecore licensing to run the XMCloud site in local docker environments. • Create your own Github account to link with XMCloud project. Steps to setup your project 1. Click on “Manage My projects” menu to open https://deploy.sitecorecloud.io/projects.io/projects site to Create a new project or manage existing one. 2. Then click on “Create New Project” button to cr...
Read more

Step by Step installation of Sitecore 10.3 on Azure PaaS

Image
  In this document we will learn how to setup Sitecore 10.3 XP on Azure PaaS. We shall briefly cover the step by step process and overview of Sitecore 10.3 XP setup. While doing the installation, I follow Deploying a new Sitecore environment to the Microsoft Azure App service . Thanks, Sitecore Team! Prerequisites: To setup Sitecore 10.3 on Azure PaaS, we shall need the following: Check PowerShellGet Module. If not found please install PowerShell Gallery Install the Azure Az PowerShell module. Download Sitecore Azure Toolkit 2.8.0 . This will provide a zip file that can be extracted and used for setup.  Deployment Topologies We will do the setup for Sitecore 10.3 XP. Sitecore XP product edition is the full Sitecore Experience Platform, which includes all Sitecore roles and services, including xConnect. This is a Sitecore Experience Platform configuration that runs: Three Sitecore roles: Content Delivery, Content Management, and Processing, as a single WebA...
Read more

Step by Step installation of Sitecore 10.3 on Docker

Image
  In this document, we will learn how to setup Sitecore 10.3 on docker desktop in Windows 11. We shall briefly cover the step-by-step process and overview of Sitecore 10.3 setup. While doing the installation in my windows, I followed Installation Guide for Developer Workstation with Containers . Thanks, Sitecore Team! Prerequisites - To setup Sitecore 10.3 on docker, we shall need the following - Docker Desktop Installed on Windows Desktop Docker Desktop support for windows containers 16 GB of RAM Approximately 50GB of free disk space for Sitecore container images. SSD storage is highly recommended. The default Sitecore container configuration uses specific ports. To avoid any conflicts, we should ensure the following ports are not being used by another process: 443, 8079, 8081, 8984, and 14330 To check the prerequisites for Sitecore 10.3 installation, please check the below link - Support Information - Sitecore compatibility table for Sitecore XP 9.0 and later Setup Files - Docker...
Read more