Sitecore has introduced the Content SDK for XM Cloud-now Sitecore AI to streamline the process of fetching content and rendering it on modern JavaScript front-end applications. If you’re building a website on Sitecore AI, the new Content SDK is the modern, recommended tool for your development team.
Think of it as a specialized, lightweight toolkit built for one specific job: getting content from Sitecore AI and displaying it on your modern frontend application (like a site built with Next.js).
Because it’s purpose-built for Sitecore AI, it’s fast, efficient, and doesn’t include a lot of extra baggage. It focuses purely on the essential “headless” task of fetching and rendering content.
What About the JSS SDK?
This is the original toolkit Sitecore created for headless development.
The key difference is that the JSS SDK was designed to be a one-size-fits-all solution. It had to support both the new, headless Sitecore AI and Sitecore’s older, all-in-one platform, Sitecore XP/XM.
To do this, it had to include extra code and dependencies to support older features, like the “Experience Editor”. This makes the JSS SDK “bulkier” and more complex. If you’re only using Sitecore AI, you’re carrying around a lot of extra weight you simply don’t need.
The Sitecore Content SDK is the modern, purpose-built toolkit for developers using Sitecore AI, providing seamless, out-of-the-box integration with the platform’s most powerful capabilities. This includes seamless visual editing that empowers marketers to build and edit pages in real-time, as well as built-in hooks for personalization and analytics that simplify the delivery and tracking of targeted user experiences. For developers, it provides GraphQL utilities to streamline data fetching and is deeply optimized for Next.js, enabling high-performance features like server-side rendering. Furthermore, with the recent introduction of App Router support (in beta), the SDK is evolving to give developers even more granular control over performance, SEO, bundle sizes, and security through a more modern, modular code structure.
What does the Content SDK offer?
1) App Router support (v1.2)
With version 1.2.0, Sitecore Content SDK introduces App Router support in beta. While the full fledged stable release is expected soon, developers can already start exploring its benefits and work flow with 1.2 version.
This isn’t just a minor update; it’s a huge step toward making your front-end development more flexible and highly optimized.
Why should you care? –
The App Router introduces a fantastic change to your starter application’s code structure and how routing works. Everything becomes more modular and declarative, aligning perfectly with modern architecture practices. This means defining routes and layouts is cleaner, content fetching is neatly separated from rendering, and integrating complex Next.js features like dynamic routes is easier than ever. Ultimately, this shift makes your applications much simpler to scale and maintain as they grow on Sitecore AI.
Performance: Developers can fine-tune route handling with nested layouts and more aggressive and granular caching to seriously boost overall performance, leading to faster load times.
Bundle Size: Smaller bundle size because it uses React Server Components (RSC) to render components. It help fetch and render component from server side without making the static files in bundle.
Security: It helps with security by giving improved control over access to specific routes and content.
With the starter kit applications, this is how app router routing structure looks like:
2) New configs – sitecore.config.ts & sitecore.cli.config.ts
The sitecore.config.ts file, located in the root of your application, acts as the central configuration point for Content SDK projects. It is replacement of the older temp/config file used by the JSS SDK. It contains properties that can be used throughout the application just by importing the file. It contains important properties like sitename, defaultLanguage, edge props like contextid. Starter templates include a very lightweight version containing only the mandatory parameters necessary to get started. Developers can easily extend this file as the project grows and requires more specific settings.
Key Aspects:
Environment Variable Support: This file is designed for deployment flexibility using a layered approach. Any configuration property present in this file can be sourced in three ways, listed in order of priority:
- Explicitly defined in the configuration file itself.
- Fallback to a corresponding environment variable (ideal for deployment pipelines).
- Use a default value if neither of the above is provided.
This layered approach ensures flexibility and simplifies deployment across environments.
The sitecore.cli.config.ts file is dedicated to defining and configuring the commands and scripts used during the development and build phases of a Content SDK project.
Key Aspects:
CLI Command Configuration: It dictates the commands that execute as part of the build process, such as generateMetadata() and generateSites(), which are essential for generating Sitecore-related data and metadata for the front-end.
Component Map Generation: This file manages the configuration for the automatic component map generation. This process is crucial for telling Sitecore how your front-end components map to the content structure, allowing you to specify file paths to scan and define any files or folders to exclude. Explored further below.
Customization of Build Process: It allows developers to customize the Content SDK’s standard build process by adding their own custom commands or scripts to be executed during compilation.
While sitecore.config.ts handles the application’s runtime settings (like connection details to Sitecore AI), sitecore.cli.config.ts works in conjunction to handle the development-time configuration required to prepare the application for deployment.
3) Component map
In Sitecore Content SDK-based applications, every custom component must be manually registered in the .sitecore/component-map.ts file located in the app’s root. The component map is a registry that explicitly links Sitecore renderings to their corresponding frontend component implementations. The component map tells the Content SDK which frontend component to render for each component receives from Sitecore. When the rendering gets added to any page via presentation, component map tells which frontend rendering should be rendered at the place.
Key Aspects:
Unlike JSS implementations that automatically maps components, the Content SDK’s explicit component map enables better tree-shaking. Your final production bundle will only include the components you have actually registered and use, resulting in smaller, more efficient application sizes.
This is how it looks like: (Once you start creating custom component, you have to add the component name here to register.)
4) Import map
The import map is a tool used specifically by the Content SDK’s code generation feature. It manages the import paths of components that are generated or used during the build process. It acts as a guide for the code generation engine, ensuring that any new code it creates correctly references your existing components.
Where it is: It is a generated file, typically found at ./sitecore/import-map.ts, that serves as an internal manifest for the build process. You generally do not need to edit this file manually.
It simplifies the logic of code generation, guaranteeing that any newly created code correctly and consistently references your existing component modules.
The import map generation process is configurable via the sitecore.cli.config.ts file. This allows developers to customize the directories scanned for components.
5) defineMiddleware in the Sitecore Content SDK
defineMiddleware is a utility for composing a middleware chain in your Next.js app. It gives you a clean, declarative way to handle cross-cutting concerns like multi-site routing, personalization, redirects, and security all in one place. This centralization aligns perfectly with modern best practices for building scalable, maintainable functions.
The JSS SDK leverages a “middleware plugin” pattern. This system is effective for its time, allowing logic to be separated into distinct files. However, this separation often requires developers to manually manage the ordering and chaining of multiple files, which could become complex and less transparent as the application grew. The Content SDK streamlines this process by moving the composition logic into a single, highly readable utility which can customizable easily by extending Middleware
6) Debug Logging in Sitecore Content SDK
Debug logging helps you see what the SDK is doing under the hood. Super useful for troubleshooting layout/dictionary fetches, multisite routing, redirects, personalization, and more. The Content SDK uses the standard DEBUG environment variable pattern to enable logging by namespace. You can selectively turn on logging for only the areas you need to troubleshoot, such as: content-sdk:layout (for layout service details) or content-sdk:dictionary (for dictionary service details)
For all available namespaces and parameters, refer to sitecore doc – https://doc.sitecore.com/sai/en/developers/content-sdk/debug-logging-in-content-sdk-apps.html#namespaces
7) Editing & Preview
In the context of Sitecore’s development platform, editing and preview render optimization with the Content SDK involves leveraging middleware, architecture, and framework-specific features to improve the performance of rendering content in editing and preview modes. The primary goal is to provide a fast and responsive editing experience for marketers using tools like Sitecore AI Pages and the Design Library. EditingRenderMiddleware: The Content SDK for Next.js includes optimized middleware for editing scenarios. Instead of a multi-step process involving redirects, the optimized middleware performs an internal, server-side request to return the HTML directly. This reduces overhead and speeds up rendering significantly.
This feature Works out of the box in most environments: Local container, Vercel / Netlify, SitecoreAI (defaults to localhost as configured)
For custom setups, override the internal host with: SITECORE_INTERNAL_EDITING_HOST_URL=https://host
This leverages a Integration with XM Cloud/Sitecore AI Pages for visual editing and testing of components.
8) SitecoreClient
The SitecoreClient class in the Sitecore Content SDK is a centralized data-fetching service that simplifies communication with your Sitecore content backend typically with Experience Edge or preview endpoint via GraphQL endpoints.
Instead of calling multiple services separately, SitecoreClient lets you make one organized request to fetch everything needed for a page layout, dictionary, redirects, personalization, and more.
Key Aspect:
Unified API: One client to access layout, dictionary, sitemap, robots.txt, redirects, error pages, multi-site, and personalization.
To understand all key methods supported, please refer to sitecore documentation: https://doc.sitecore.com/sai/en/developers/content-sdk/the-sitecoreclient-api.html#key-methods
9) Built-In Capabilities for Modern Web Experiences
GraphQL Utilities: Easily fetch content, layout, dictionary entries, and site info from Sitecore AI’s Edge and Preview endpoints.
Personalization & A/B/n Testing: Deploy multiple page or component variants to different audience segments (e.g., by time zone or language) with no custom code.
Multi-site Support: Seamlessly manage and serve content across multiple independent sites from a single Sitecore AI instance.
Analytics & Event Tracking: Integrated support via the Sitecore Cloud SDK for capturing user behavior and performance metrics.
Framework-Specific Features: Includes Next.js locale-based routing for internationalization, and supports both SSR and SSG for flexible rendering strategies.
10) Cursor for AI development
Starting with Content SDK version 1.1, Sitecore has provided comprehensive “Cursor rules” to facilitate AI-powered development.
The integration provides Cursor with sufficient context about the Content SDK ecosystem and Sitecore development patterns. These set of rules and context helps to accelerate the development. The cursor rules are created for contentsdk with starter application under .cursor folder. This enables the AI to better assist developers with tasks specific to building headless Sitecore components, leading to improved development consistency and speed following same patterns just by providing few commands in generic terms. Example given in below screenshot for Hero component which can act as a pattern to create another similar component by cursor.
11) Starter Templates and Example Applications
To accelerate development and reduce setup time, the Sitecore Content SDK includes a set of starter templates and example applications designed for different use cases and development styles.
The SDK provides a Next.js JavaScript starter template that enables rapid integration with Sitecore AI. This template is optimized for performance, scalability, and best practices in modern front-end development.
Starter Applications in examples
basic-nextjs -A minimal Next.js application showcasing how to fetch and render content from Sitecore AI using the Content SDK. Ideal for SSR/SSG use cases and developers looking to build scalable, production-ready apps.
basic-spa -A single-page application (SPA) example that demonstrates client-side rendering and dynamic content loading. Useful for lightweight apps or scenarios where SSR is not required.
Other demo site to showcase Sitecore AI capabilities using the Content SDK:
kit-nextjs-article-starter
kit-nextjs-location-starter
kit-nextjs-product-starter
kit-nextjs-skate-park
Final Thoughts
The Sitecore Content SDK represents a major leap forward for developers building on Sitecore AI. Unlike the older JSS SDK, which carried legacy dependencies, the Content SDK is purpose-built for modern headless architectures—lightweight, efficient, and deeply optimized for frameworks like Next.js. With features like App Router support, runtime and CLI configuration flexibility, and explicit component mapping, it empowers teams to create scalable, high-performance applications while maintaining clean, modular code structures.
