Koushik Mukherjee | Sitecore Architect, Sitecore MVP & AI/DXP Expert: Sitecore Content SDK

Showing posts with label Sitecore Content SDK. Show all posts

Monday, 6 October 2025

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

Koushik Mukherjee October 06, 2025 0

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.

References:

Migrate JSS 22.8 Next.js apps to Content SDK 1.0

Monday, 22 September 2025

Sitecore XM Cloud Content SDK vs. JSS SDK: Key Differences and New Features

Koushik Mukherjee September 22, 2025 0

In my previous blog post on the Sitecore XM Cloud Content SDK, I discussed how you can install and start working with the Content SDK. In this blog, I'll focus on the differences between the JSS SDK and the Content SDK, along with some of the new concepts introduced in the Content SDK.

Comparison with JSS SDK

1. Reduced Folder Size and Complexity
The Content SDK removes functionality not strictly required for XM Cloud, leading to smaller, less complex starter applications that are inherently easier to understand and maintain.

2. Experience Editor Removal
This is one of the most impactful changes. Unlike JSS, the Content SDK does not support the Experience Editor. Instead, all visual editing is handled through the XM Cloud Pages Builder in metadata integration mode. This eliminates the need for chromes integration mode—previously central to the Experience Editor—and enables further code optimizations.

3. Mapping Components
In the Content SDK, all components must be manually registered in the app’s .sitecore/component-map.ts file. Unlike traditional JSS apps, Content SDK apps don’t automatically update mappings for newly scaffolded components through a file watcher. This approach gives developers greater control, allowing them to decide when and how components are exposed to XM Cloud. At the same time, the Content SDK provides flexibility by offering an automated option to generate component maps using the sitecore-tools project component generate-map CLI command, which includes a file watcher mode.

4. Centralized Configuration Files

.env.container.example — Used when working with a Sitecore container instance. Copy this file, rename it to .env.local, and update the required environment variables.
.env.remote.example — Used when working with a Sitecore remote instance. Copy this file and rename it to .env.local.
sitecore.config.ts — Serves as the central configuration file for the app. To access values from sitecore.cli.config, use:
```
import scConfig from 'sitecore.config';
```
sitecore.cli.config.ts — Provides CLI commands and supports scripts for common tasks during Content SDK project development.

5. Data Fetching
The new Sitecore Client Data Fetching API, powered by the SitecoreClient class, centralizes all data-fetching logic. This replaces the older JSS data-fetching plugins, offering a more unified and streamlined way to retrieve content.

6. Middleware Handling
Middleware is now managed within the middleware.ts file in Next.js. A new utility function, defineMiddleware, simplifies middleware composition and improves visibility into execution order. This removes the need for separate middleware plugin files used in JSS, making middleware logic easier to maintain.

7. CLI Tooling
The Content SDK introduces its own set of dedicated CLI commands, replacing legacy JSS CLI tools. For instance, the familiar jss scaffold component command is now replaced by:


sitecore-tools project component scaffold

8. XM Cloud Starter Kit
Alongside the Content SDK, a new XM Cloud Starter Kit is available. The xmcloud-foundation-head repository continues to serve as the JSS-based starter kit. Both provide a Next.js skatepark demo site, but the Content SDK version uses Tailwind CSS instead of Bootstrap.

In addition, the new starter kit includes:

An empty Next.js head app example
An empty Angular head app example
Three new Next.js demo head app examples

Some New Concepts

SitecoreClient API
The SitecoreClient class is a generic, framework-agnostic client that you can use to interact with XM Cloud's headless APIs and services. It provides a unified interface for retrieving and managing content, layout, dictionary data, error pages, preview data, sitemaps, robots.txt, and other site-related information from an XM Cloud backend, typically via GraphQL endpoints.

CLI Commands

The build command
The sitecore-tools project build command prepares app-specific build artifacts, such as those required for the app to connect to XM Cloud. It does this by sequentially executing the functions listed in the build: section of your CLI config file.
The scaffold command
The sitecore-tools project component scaffold command generates a new component in the src/components/ folder of your app, based on the default template for the framework.
Generate-map Command
(sitecore-tools project component generate-map)
This command generates the component map file at /.sitecore/component-map.ts. It supports defining component source paths, importing components from NPM packages, applying exclude patterns, and specifying a custom destination.

Content SDK Pros and Cons

Pros

Reduced Size & Complexity: Content SDK apps are smaller and less complex than JSS apps, making them easier to understand, maintain, and run faster with smaller bundle sizes.
Seamless XM Cloud Pages Integration: Out-of-the-box visual editing and component testing directly in XM Cloud Pages, empowering marketing teams.
Unified Data Fetching: The SitecoreClient class provides a single, streamlined interface for all XM Cloud headless API interactions.
Modern Development Workflow: Enables contemporary workflows and architectures for headless development.
Rapid Development: Includes an empty Next.js head app and multiple demo apps to accelerate project setup and customization.
Rich Out-of-the-Box Features: Supports personalization, A/B/n testing, multisite setups, GraphQL utilities, SSR/SSG, and locale-based routing.
Developer Autonomy: Offers more control over component mapping, allowing developers to decide which components to register.

Cons

No Experience Editor Support: With the shift to XM Cloud Pages (and the deprecation of the Experience Editor), teams relying heavily on EE must adapt their workflows.
Migration Effort for Existing JSS Apps: Migrating to Content SDK requires dependency updates, configuration changes, and code refactoring, which can be complex depending on the app. Sitecore provides an upgrade guide.
Learning Curve for New Concepts: Developers need to get familiar with new elements such as the SitecoreClient class, centralized config files (sitecore.config.ts, sitecore.cli.config.ts), and the defineMiddleware utility.

The Sitecore XM Cloud Content SDK represents a major step forward in headless development on XM Cloud. Content SDK is providing a streamlined, efficient, and developer-friendly experience.

References

Sitecore Content SDK for XM Cloud

What Is Content SDK in a Nutshell?

Tags # headless development # Sitecore CLI # Sitecore Content SDK Continue Reading

Wednesday, 17 September 2025

Getting Started with Sitecore Content SDK for XM Cloud

Koushik Mukherjee September 17, 2025 0

Sitecore has announced the release of the Content SDK. The Content SDK helps developers integrate XM Cloud content with their front-end applications. It is set to replace the existing JSS SDK for XM Cloud. This new Content SDK will exclusively support XM Cloud, providing a cleaner and more streamlined solution.

In this blog, I’ll discuss the key features of the Content SDK, how to install it locally, and how to connect it with an XM Cloud instance for local development.