Blog 6: The Migration Journey from JSS to Sitecore Content SDK — A Developer’s Guide

Hello Sitecorian Community! 👋

Migrating from Sitecore JSS to the new Content SDK for XM Cloud is an important step for developers who want to simplify their workflows and reduce complexity in their applications. If you’re planning to make the switch, it’s crucial to understand the process and what to expect along the way. In this post, we’ll walk through the typical steps and challenges you’ll face during the migration journey from JSS to Content SDK.

Why Migrate to Sitecore Content SDK?

The release of Content SDK represents a significant change in how Sitecore handles headless development for XM Cloud. It is designed to replace JSS for Next.js projects, offering a more streamlined and simplified way to connect with Sitecore’s content delivery services.

For developers familiar with JSS, the migration may seem daunting at first. However, once you understand the changes in architecture and configuration, the benefits become clear. The Content SDK is more focused and optimized for XM Cloud, offering cleaner, leaner starter apps, fewer files, and fewer moving parts.

But before you dive into the migration process, there are a few key things to know about the Content SDK.

The Biggest Change — Goodbye Experience Editor

One of the biggest shifts when migrating from JSS to the Content SDK is the removal of the Experience Editor. Previously, the Experience Editor (EE) was a core feature of JSS, allowing developers and marketers to visually edit components and page content.

In the Content SDK, the Experience Editor is replaced by the XM Cloud Page Builder, which is now the primary tool for page customization. If your current JSS application relies on Experience Editor features (like edit frames or chrome rendering), you’ll need to rethink those workflows. While the transition may initially feel like a significant disruption, the Page Builder covers most of the functionality that Experience Editor provided, simplifying the overall setup.

Typical Steps in the Migration Journey

1. Update Dependencies and Clean Install

The first step in migrating your project is to update the dependencies. This involves replacing the JSS Next.js dependency with the new Content SDK version. Along with this, you’ll want to remove old CLI and development tool packages that are no longer supported in the Content SDK.

After updating dependencies, perform a clean install of your project. This helps clear out any outdated files and ensures you’re starting with a fresh environment.

2. Set Up a Template App

Once your project is cleaned up, the next step is to create a new Content SDK template app. This serves as a useful reference to help you understand how the new SDK is structured. You can compare this template app with your existing JSS app to see which files, folder structures, and configurations need to be updated.

3. Switch to New Configuration Files

In the Content SDK, there are new configuration files, notably sitecore.config.ts and sitecore.cli.config.ts, that replace the scattered config setup used in JSS.

• sitecore.config.ts is now the main configuration file for build and runtime settings.
• sitecore.cli.config.ts handles build tools and development commands.

It’s essential to copy these configuration files into your project and update your imports accordingly to ensure your app is aligned with the new structure.

4. Update Environment Variables

Content SDK introduces new naming conventions for environment variables. For instance, SITECORE_API_KEY now becomes NEXT_PUBLIC_SITECORE_API_KEY. These changes are important to ensure your app can still connect to the Sitecore backend properly.

Updating all relevant environment variables early on is key to avoiding connectivity issues later in the process.

5. Refactor Components and Imports

As you start migrating your app, you’ll notice that some components and interfaces have changed. For example, SitecoreContext is now replaced with SitecoreProvider, and several hooks and props have new names. While these updates are relatively straightforward, it’s important to systematically go through your codebase and make the necessary changes.

6. Remove Unused Files and Scripts

JSS apps often contain extra scripts for scaffolding, configuration, and build setup, which are no longer required in Content SDK. As you migrate, make sure to delete unnecessary scripts and folders to clean up the project and make it more manageable.

What’s Different in the New SDK?

When you start working with the Content SDK, there are a few key differences that will stand out:

• Unified Data Fetching: Instead of relying on multiple services to fetch layout, dictionary data, and other content, the Content SDK uses a single SitecoreClient class to manage all data fetching. This simplifies the process and reduces the need for multiple data fetching plugins.
• Simplified Middleware: The Content SDK introduces the defineMiddleware utility, which simplifies middleware handling and integrates it better with how Next.js works.
• Cleaner Project Structure: The new SDK eliminates the need for temporary or generated configuration files, which were often a source of confusion in JSS. Instead, the configuration is more streamlined and centralized in a consistent way.

Challenges You May Encounter

While the migration process itself is not overwhelmingly complex, there are a few challenges developers typically face:

• Learning the New Architecture: The Content SDK introduces new concepts, such as the SitecoreClient class and the defineMiddleware utility. It may take some time to get used to these changes, especially if you’re coming from a JSS background.
• Removing Deprecated Features: Features like Experience Editor are no longer supported, which can be a challenge for teams who are heavily reliant on that functionality. Transitioning to the Page Builder may take time to adjust to, but it offers a more unified experience for content editing.
• Refactoring Components: Updating component names, imports, and structure can be a bit tedious, especially in larger projects. However, this step is necessary to ensure that the app is compatible with the new SDK.

What You Need to Know Before You Start

If you’re preparing to migrate your app from JSS to Content SDK, here are a few things to keep in mind:

1. Don’t Rush: Migrating from JSS isn’t something you can complete in one sitting. Take it step by step, ensuring that you update all the necessary dependencies and configurations along the way.
2. Use the Content SDK Starter App: The new Content SDK template app is an invaluable resource. Compare it side by side with your JSS app to easily spot what needs updating.
3. Test Thoroughly: After making the migration, test your application thoroughly to ensure that all content is loading correctly, and all features are working as expected.

Conclusion: A New Era for XM Cloud Development

Migrating from JSS to Content SDK is a manageable process that results in a more streamlined, simplified development workflow. With fewer files, more cohesive data fetching, and a cleaner project structure, the Content SDK is a major improvement for headless development on XM Cloud.

While there are changes to be made and new concepts to learn, the benefits of the Content SDK — including faster development and easier maintenance — make it worth the effort. Whether you’re starting a new project or migrating an existing one, the Content SDK is the future of Sitecore’s headless development platform.

I hope you enjoy this blog. Stay tuned for more Sitecore related articles.

Till that happy Sitecoring :)

Please leave your comments or share this article if it’s useful for you.