Farewell to JSS, Welcome to Sitecore Content SDK

What Is Content SDK in a Nutshell?

Sitecore has finally released the Content SDK. For those of us deeply invested in the Sitecore ecosystem, especially with XM Cloud, this release is the future. I wanted to take some time to demystify what the Sitecore Content SDK is, why it matters, and what it means for your development workflow.

The Sitecore Content SDK is a new, streamlined toolkit designed to enable developers to integrate XM Cloud content seamlessly with their front-end JavaScript applications. It's an integral part of Sitecore's headless development suite for XM Cloud, built to facilitate modern development workflows and application architectures.

Here's the gist of it:

• It provides a unified set of APIs and services that fetch data from XM Cloud, making it easier than ever to build and deliver dynamic, engaging pages to your site visitors using modern JavaScript frameworks like Next.js and Angular.
• As with Sitecore JSS SDK, it has a seamless integration with XM Cloud Pages for visual editing of components.
• You can jumpstart your development with a starter kit template, immediately generating a new Content SDK app that you can customize to suit your business needs.
• The SDK specifically targets XM Cloud and is designed to significantly reduce the size and complexity of your template applications compared to JSS SDK based applications.
• Ultimately, Content SDK applications are easier to understand and maintain than their JSS predecessors due to their leaner footprint.

Head Application Sitecore SDK History

To truly appreciate the Content SDK, it's helpful to look back. Sitecore JavaScript Services (JSS) SDK was the predecessor for building head applications with Sitecore. JSS was, and still is, a powerful tool that enabled developers to build fully headless front-end applications communicating with Sitecore via APIs, primarily the Layout Service.

The Content SDK is described as a major upgrade from the Sitecore JavaScript Services SDK (JSS) for XM Cloud. Sitecore's goal with this new SDK is clear: to reduce the size and complexity of starter applications by removing functionality not explicitly needed for XM Cloud implementations. This means the Content SDK effectively extracts the functionality of JSS that was specifically designed for XM Cloud development and makes that functionality simpler to build with and maintain. It's all about focus and optimization.

Comparison With JSS

Now, let's dive into the details of how Content SDK differs from its JSS roots. For those of us who've built our fair share of JSS applications, these distinctions are important.

• Reduced Complexity and Size: This is a recurring theme, and for good reason. Content SDK removes the functionality not strictly required for XM Cloud, leading to smaller, less complex starter applications that are inherently easier to understand and maintain. This means less boilerplate and more focus on your unique business logic. Preliminary numbers show that Content SDK is 49% smaller than JSS SDK. A Content SDK sample application has about 81% less files and about 39% less lines of code.
• Experience Editor (EE) Removal: This is perhaps the most significant functional change. Unlike JSS, Content SDK does not support the Experience Editor tool. This means all visual editing with Content SDK is done exclusively with the XM Cloud Pages Builder using metadata integration mode. This shift removes the need for chromes integration mode, which was a core part of how EE worked, and consequently leads to further code optimizations.
• Component Map:
  • In Content SDK, every component you create must be registered in the app's .sitecore/component-map.ts file. This explicit mapping ensures your components are recognized and usable as renderings within XM Cloud Pages for marketers.
  • One notable change is that, unlike traditional JSS apps, Content SDK apps do not automatically add a mapping for newly scaffolded components via a file change watcher. This grants Content SDK developers more autonomy and control when creating components, as you decide when and how they are exposed to XM Cloud.
  • The Content SDK however introduces the option to automatically generate component maps for your project via the sitecore-tools project component generate-map CLI command that has a file change watcher mode.
• Configuration Files:
  • A new file, sitecore.config.ts, now serves as the central point for configuring your application's build and runtime settings. This streamlines configuration by replacing previous runtime config generation scripts, giving you a single source of truth.
  • Another new file, sitecore.cli.config.ts, is used to configure CLI commands for Content SDK, enabling it to replace many of the build-time and development tools scripts you might be familiar with from JSS.
• Data Fetching: The new Sitecore Client Data Fetching API, represented by the SitecoreClient class, unifies all data fetching logic. This replaces the previous data fetching plugins used in JSS, providing a more cohesive and simplified approach to retrieving content.
• Middleware Handling: All the middlewares are now defined in the next.js middleware.ts file. A new utility function named defineMiddleware simplifies middleware composition and provides better visibility into the order the middleware are executed. This removes the need for separate middleware plugin files, which were previously used in JSS, making your middleware logic more straightforward to manage.
• CLI Tooling: Content SDK brings its own dedicated CLI commands, replacing older JSS CLI tools and scripts. For example, the familiar jss scaffold component command is now replaced by sitecore-tools project component scaffold.
• XM Cloud Starter Kit: With the Content SDK comes a new XM Cloud starter kit. The xmcloud-foundation-head repository will continue to be the JSS flavor of the starter kit. Both have a Next.js skatepark demo site head application example, but the Content SDK version is using Tailwind CSS instead of Bootstrap. Compared to its predecessor, the new starter kit has an empty Next.js head application example, an empty Angular head application example, as well as 3 new Next.js demo head application examples.

In summary:

New Concepts

Beyond the comparisons, the Content SDK introduces some fresh concepts that are worth highlighting:

• SitecoreClient Class: This is a big one. The SitecoreClient class is a generic, framework-agnostic client designed to interact with XM Cloud's headless APIs and services. Its primary purpose is to provide a unified interface for retrieving and managing content, layout, dictionary data, error pages, preview data, sitemaps, robots.txt, and other site-related information from the XM Cloud backend, typically via GraphQL endpoints. It's built for extensibility, allowing developers to customize its behavior.
• CLI Commands: The Content SDK CLI is your new best friend for common development tasks. You'll need to install it globally.
  • The build command (sitecore-tools project build): This command prepares app-specific build artifacts, connecting your app to XM Cloud. It executes functions listed in the build section of your sitecore.cli.config.ts file, running every time your app is built.
  • The scaffold command (sitecore-tools project component scaffold <ComponentName>): This command generates a new named component in your src/components/ folder, based on default or custom templates. It supports scaffolding standard components and Sitecore BYOC (Bring Your Own Component) components.
  • The generate-map command (sitecore-tools project component generate-map): This command generates the component map located at /.sitecore/component-map.ts. It supports component source paths, imported components from NPM packages, exclude patterns, and a custom destination. If called with the --watch switch, it will watch your component source paths for changes and regenerate the component map as you code.
• Centralized Configuration Files:
  • sitecore.config.ts: The central configuration point for your Content SDK application, including essential settings for connecting to XM Cloud (API keys, host, Edge URL, context ID), default site and language, and an editing secret for visual editing. It also allows for configuration of various Content SDK services.
  • sitecore.cli.config.ts: Configures the Content SDK CLI, defining commands executed by the build process, allowing for custom component templates for the scaffold command, and defining the configuration to automatically generate the component map using the generate-map command.
• defineMiddleware Utility: This utility simplifies integrating custom middlewares. To create a new middleware in the Next.js middleware.ts file, you define a new variable that extends the Middleware abstract class and you pass the middleware instance to the defineMiddleware function at the position you prefer it to be executed. This offers better visibility and removes the need for plugins.

Content SDK Pros and Cons

Every new technology comes with its advantages and considerations.

Pros

• Reduced Size and Complexity: Content SDK apps are explicitly designed to be smaller and less complex than JSS apps for XM Cloud, leading to easier understanding and maintenance, smaller bundle size, and faster execution.
• Seamless XM Cloud Pages Integration: You get out-of-the-box visual editing and testing of components directly within XM Cloud Pages, empowering your marketing teams.
• Unified Data Fetching: The SitecoreClient class provides a single, coherent interface for all your XM Cloud headless API interactions.
• Modern Development Workflow: It strongly enables modern development workflows and application architectures.
• Rapid Development: The inclusion of an empty Next.js head application and multiple demo head applications accelerates application generation and customization.
• Out-of-the-Box Capabilities: Supports personalization, component A/B/n testing, multi-site environments, GraphQL utilities, and leverages framework-specific features like SSR/SSG and locale-based routing.
• Developer Autonomy: Offers more control over component mapping, allowing you to decide which components to register.

Cons

• No Experience Editor Support: This is a direct consequence of the shift to XM Cloud Pages and soon deprecation of Experience Editor in XM Cloud. Teams heavily reliant on the Experience Editor will need to adapt their workflows and transition to XM Cloud Pages for visual editing.
• Migration Effort for Existing JSS Apps: Existing JSS applications will require a migration process to adopt Content SDK. This involves updating dependencies, configuration files, and refactoring existing code, which can be a non-trivial effort depending on the complexity of your current application. Sitecore released an upgrade guide.
• Learning Curve for New Concepts: Developers will need to familiarize themselves with new concepts like the SitecoreClient class, the new centralized configuration files (sitecore.config.ts, sitecore.cli.config.ts), and the defineMiddleware utility.

Community and Resources

Sitecore has always had a fantastic community, and the Content SDK is no exception. This is an open-source project, which means we, as developers, have a unique opportunity to contribute and shape its future.

• Developers are highly encouraged to read the source code, contribute feedback, bug reports and improvement ideas, and submit contributions via pull requests to the public GitHub repository. This is how we collectively make the ecosystem stronger!
• For in-depth information and detailed guides, refer to the official documentation, which is a comprehensive resource for getting started and understanding advanced concepts.
• For community support and discussions, don't hesitate to utilize platforms like Sitecore StackExchange and the Sitecore Community #headless Slack channel. These are invaluable resources for problem-solving and connecting with peers.
• For the official announcement from Sitecore, read the following changelog entry.

The release of the Sitecore Content SDK marks an exciting new chapter in headless development for XM Cloud. It’s clear Sitecore is committed to providing a streamlined, efficient, and developer-friendly experience. While there’s a learning curve and a migration path for existing JSS users, the benefits of reduced complexity and decreased size are compelling.

Happy Sitecoring!