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: -
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:
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
Thesitecore-tools project buildcommand 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 thebuild:section of your CLI config file. -
The scaffold command
Thesitecore-tools project component scaffoldcommand generates a new component in thesrc/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
SitecoreClientclass 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
SitecoreClientclass, centralized config files (sitecore.config.ts,sitecore.cli.config.ts), and thedefineMiddlewareutility.
