Getting Started with Sitecore Content SDK for XM Cloud - Part 1

The Sitecore Content SDK is the modern way to connect your front-end applications with XM Cloud. It replaces the older JSS SDK, offering a lighter, faster, and framework-agnostic approach. If you’re starting a new project, the Content SDK should be your default choice.

Architecture overview

The Sitecore Content SDK is part of the headless development suite for XM Cloud, created to enable modern development workflows and application architecture.

Content SDK contains:

• Core SDK functionality for retrieving data from various Sitecore services and APIs to facilitate working with Sitecore data and layout in JavaScript.
• SDKs that facilitate building JavaScript applications with Next.js. They help render XM Cloud placeholders, providing components and helpers for rendering XM Cloud fields, while the layout and field values remain editable by authors.
• Developer tooling and utilities.

Why Use the Content SDK?

Here are the main advantages:

• Future-proof → Built for XM Cloud and continuously updated.
• Lightweight → Smaller, faster, and easier than the legacy JSS SDK.
• Framework-agnostic → Works with Next.js, React, Vue, or any modern JS framework.
• Improved GraphQL utilities → Simplifies fetching content, layouts, and dictionaries.
• Multi-site & multilingual → Enterprise-ready by default.
• Flexible rendering → Supports SSR, SSG, ISR, and CSR.
• XM Cloud Pages integration → Seamless editing and previewing experience.
• Open source → Maintained on GitHub under Apache 2.0 license.

In summary: Sitecore JSS Repository https://github.com/Sitecore/jss Sitecore Content SDK Repository https://github.com/Sitecore/content-sdk XM Cloud Foundation Kit URL https://github.com/sitecorelabs/xmcloud-foundation-head XM Cloud Starter Kit URL https://github.com/Sitecore/xmcloud-starter-js

Key Differences Between JSS and Content SDK

JSS also offers some of the features listed above. So, where does Content SDK stand out? Let’s find out.

Official docs: Sitecore Content SDK for XM Cloud

The Future is Now: Sitecore Content SDK 1.3 brings App Router into XM CloudFor years, I’ve been navigating the ever-evolving landscape of Sitecore, and I’ve seen my fair share of game-changing updates. But let me tell you, the recent release of Sitecore Content SDK v1.3 feels different. This isn’t just another incremental update; it’s a fundamental shift in how we build for XM Cloud, and it’s bringing the power of the Next.js App Router to the forefront of Sitecore development. I’ve had the chance to dive deep into this release, and I’m thrilled to share my findings with you.

Why the Content SDK is a Game-Changer

I’ve spent some time with the Content SDK, and I can tell you firsthand that it’s more than just a rebrand of JSS. It’s a leaner, meaner, and more focused toolkit designed specifically for the needs of XM Cloud. Here’s a breakdown of the key differences.

Farewell, Experience Editor

One of the most significant changes is the removal of Experience Editor support. This might sound alarming at first, but it’s a strategic move. By focusing solely on the XM Cloud Pages Builder, the Content SDK sheds a tremendous amount of complexity. This results in a leaner codebase that’s easier to understand, maintain, and, most importantly, faster.

Enter the App Router: A New Era for Next.js in XM Cloud

The headline feature of Content SDK 1.3 is, without a doubt, the introduction of beta support for the Next.js App Router. This is a monumental step forward, aligning XM Cloud development with the latest and greatest from the Next.js ecosystem.
For those unfamiliar, the App Router is a new paradigm in Next.js that simplifies routing, data fetching, and component architecture. It introduces concepts such as server components, nested layouts, and streamlined data fetching, making the building of complex applications more intuitive than ever.I’ve been exploring the xmcloud-starter-js repository, specifically the release/CSDK-1.3.2 branch, to see how all of this comes together.Let’s take a look at some of the code.

The New App Router Structure

The folder structure itself tells a story. Gone is the pages directory, replaced by a more intuitive app directory:

src/├── app/│   ├── [site]/│   │   ├── [locale]/│   │   │   └── [[...path]]/│   │   │       └── page.tsx│   │   └── layout.tsx│   ├── api/│   ├── layout.tsx│   ├── not-found.tsx│   └── global-error.tsx├── components/├── lib/└── middleware.ts

This structure is not only cleaner but also more powerful, allowing for features such as route groups and nested layouts that were previously cumbersome to implement in the Pages Router.Each route file now exports separate handlers for GET, POST and OPTIONS API requests and uses updated request types. See the Next.js documentation for detailed information about the logic behind App Router API routes.

Data Fetching in Server Components

With the App Router, Server Components are the default. This means you can fetch data directly within your components without getServerSideProps or getStaticProps. Here’s a look at the new page.tsx:

// src/app/[site]/[locale]/[[...path]]/page.tsx

import { notFound } from 'next/navigation';import { draftMode } from 'next/headers';import client from 'src/lib/sitecore-client';import Layout from 'src/Layout';export default async function Page({ params, searchParams }: PageProps) { const { site, locale, path } = await params; const draft = await draftMode();  let page;if (draft.isEnabled) {    const editingParams = await searchParams;    // ... handle preview and design library data } else {    page = await client.getPage(path ?? [], { site, locale });  } if (!page) {notFound();  }  return <Layout page={page} />;}

Notice how clean and concise this is. We’re using async/await directly in our component, and Next.js handles the rest. This is a huge win for developer experience.

A New Approach to Layouts

The App Router also introduces a more powerful way to handle layouts. You can now create nested layouts that are automatically applied to child routes. Here’s a simplified example from the starter kit:

// src/app/[site]/layout.tsx

import { draftMode } from 'next/headers';import Bootstrap from 'src/Bootstrap'; export default async function SiteLayout({  children,  params,}: {  children: React.ReactNode;  params: Promise<{ site: string }>;}) { const { site } = await params;  const { isEnabled } = await draftMode();  return (    <>      <Bootstrap siteName={site} isPreviewMode={isEnabled} />      {children}    </>  );}

This SiteLayout component wraps all pages within a given site, providing a consistent structure and allowing for site-specific logic.

Migrating from JSS to the Content SDK: A Checklist

For those of us with existing JSS projects, the migration to the Content SDK is now a top priority. While Sitecore provides a comprehensive migration guide, here’s a high-level checklist to get you started:

1. Update Dependencies: Replace your jss-nextjscode> packages with the new @sitecore-content-sdk/nextjs packages.
2. Centralize Configuration: Create sitecore.config.ts and sitecore.cli.config.ts to consolidate your settings.
3. Refactor Data Fetching: Replace your data fetching logic with the new SitecoreClient class.
4. Update Middleware: Consolidate your middleware into a single middleware.ts file using the defineMiddleware utility.
5. Register Components: Manually register your components in the .sitecore/component-map.ts file.
6. Update CLI Commands: Replace your jss CLI scripts with the new sitecore-tools commands.
7. Remove Experience Editor Code: Clean up any code related to the Experience Editor, as it’s no longer supported.

This is a non-trivial effort, but the benefits in terms of performance, maintainability, and developer experience are well worth it.

The Rise of AI in Sitecore Development

Another fascinating aspect of the Content SDK is its deep integration with AI-assisted development. The repository now includes guidance files for Claude, GitHub Copilot, and other AI tools. This is more than just a novelty; it’s a serious productivity booster. These guidance files instruct your AI assistant on Sitecore-specific conventions, ensuring that the code it generates adheres to best practices.
I’ve been experimenting with this, and the results are impressive. When I ask my AI assistant to create a new component, it knows to:

• Use the correct naming conventions.
• Create the necessary props interface.
• Use the Sitecore field components (<Text>, <RichText>, etc.).
• Handle missing fields gracefully.

This is a huge time-saver, ensuring that even junior developers can write high-quality, consistent code.

The Road Ahead

The release of Content SDK 1.3 and the introduction of the App Router mark a pivotal moment for Sitecore XM Cloud. It’s a clear signal that Sitecore is fully committed to modern, composable architecture and is dedicated to delivering a world-class developer experience.
For those of us who have been in the Sitecore trenches for years, this is an exciting time. We’re seeing the platform evolve in ways that will allow us to build faster, more robust, and more engaging digital experiences than ever before. The road ahead is bright, and I, for one, can’t wait to see what we build with these new tools.

Getting started with Next.js App Router using Content SDK

Official Docs: Getting started with Next.js App Router using Content SDK

Setting Up a New Project

Here’s how to set up a Next.js app with Content SDK.

1. Prerequisites

• XM Cloud tenant (with API key).
• Node.js (LTS).
• Familiarity with Next.js.

2. Create Next.js Project

Scaffolding: You can generate a new project using the CLI:

npx create-content-sdk-app "nextjs-app-router"// *SSG// SSR

3. Local Setup:

Install the global CLI for development tasks:

npm install -g @sitecore-content-sdk/cli

4. Component Mapping:

Unlike JSS, components must be manually registered in the .sitecore/component-map.ts file, though this can be automated via the sitecore-tools project component generate-map command.

5. Configure Environment Variables

Create .env.local:

SITECORE_EDGE_CONTEXT_ID=NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID=NEXT_PUBLIC_DEFAULT_SITE_NAME=NEXT_PUBLIC_DEFAULT_LANGUAGE=SITECORE_EDITING_SECRET=NEXT_PUBLIC_SITECORE_API_KEY=NEXT_PUBLIC_SITECORE_ENDPOINT=NEXT_PUBLIC_SITECORE_API_HOST=

6. Fetch Content Example

// lib/sitecore.ts


import { GraphQLClient } from 'graphql-request';
const client = new GraphQLClient (
 
  process.env.SITECORE_ENDPOINT!,
 
  { apiKey: process.env.SITECORE_API_KEY! });
 
export async function getHomePage() {
 
  const query = `query {
 
    item(path: "/sitecore/content/home") {
 
      id
 
      name
 
      fields {
 
        title {
 
          value
 
        }
 
      }
 
    }
 
  }`;
 
  return client.request(query);
 
}

7. Display in a Next.js Page

// app/page.tsx (Next.js App Router)


import { getHomePage } from '../lib/sitecore';
 
export default async function Home() {
 
  const data = await getHomePage();
 
  return (
 
    <main>
 
      <h1>{data.item.fields.title.value}</h1>
 
    </main>
 
  );
 
}

Run your app:Go to your project directory and open cmd and execute below command to run applicationnpm run dev
Happy Coding!