Showing posts with label Sitecore JSS. Show all posts
Showing posts with label Sitecore JSS. Show all posts

Monday, 6 October 2025

Migrating Your Sitecore JSS App to Content SDK: A Complete Guide

October 06, 2025 0

 


As Sitecore continues its evolution toward a fully composable and cloud-native architecture, the Content SDK for XM Cloud marks a significant shift from the legacy JSS SDK. The Content SDK simplifies development, enhances performance, and introduces modern patterns for integrating Sitecore content into front-end applications.

In my previous blog post on the Sitecore XM Cloud Content SDK, I discussed the key differences between the JSS SDK and the Content SDK, along with some of the new concepts introduced in the Content SDK.

In today's blog, I'll walk you through how you can smoothly migrate your project to the Content SDK.

Prerequisites

Before you begin, make sure to:

  • Upgrade your existing app to JSS 22.8.

  • Review the Content SDK changelog to understand major updates.

  • Note that any customizations in your app may require additional migration effort.

  • Identify templates and add-ons used (nextjs, nextjs-xmcloud, nextjs-sxa, nextjs-multisite) from your package.json file.

Key Changes in the Content SDK

  • Page Editor Only: Experience Editor is no longer available.

  • Centralized Configuration Files:

    • sitecore.config.ts for app configuration.

    • sitecore.cli.config.ts for CLI configuration.

  • New API: SitecoreClient replaces old REST/GraphQL services.

  • Middleware Handling: defineMiddleware replaces middleware plugins.

  • Component Handling: component-map replaces componentBuilder.

Update Application Dependencies

To update your application dependencies:

  1. In your existing app’s package.json, make the following changes:

    • Replace "@sitecore-jss/sitecore-jss-nextjs" with "@sitecore-content-sdk/nextjs", and update all references accordingly.

    • Delete the "@sitecore-jss/sitecore-jss-cli" dependency.

    • Delete the "@sitecore-jss/sitecore-jss-dev-tools" dependency.

  2. Install the dependencies: npm install

Create a Template Content SDK App

To create a new Next.js Content SDK application:

  1. Run the following command in your terminal:

    npx create-content-sdk-app@latest nextjs

  2. Use the same prerendering mode (SSG or SSR) as your current app.

  3. This new template app will serve as your reference for migration.

Update the Next.js Template Files in Your Existing App

Update Configurations

Follow these steps to update your JSS app configuration:

  1. Copy the sitecore.config.ts file from your template app to your existing app.

  2. Replace all imports of config from temp/config and use the new sitecore.config.ts file.
    Example:

    import config from 'temp/config';

    should be replaced with

    import scConfig from 'sitecore.config';

  3. A new page parameter has been added to SitecoreContext.
    To support this, set the api parameter to use scConfig.api and include the page parameter in the following files:

    • [[...path]].tsx

    • 500.tsx

    • 404.tsx

    Update the code as shown below:

    const page = client.getPage(...);

<SitecoreContext
  ...
  api={scConfig.api}
  page={page}
/>

Update Environment Variables

SITECORE_API_KEY  -> NEXT_PUBLIC_SITECORE_API_KEY

SITECORE_API_HOST -> NEXT_PUBLIC_SITECORE_API_HOST

SITECORE_SITE_NAME -> NEXT_PUBLIC_DEFAULT_SITE_NAME

DEFAULT_LANGUAGE -> NEXT_PUBLIC_DEFAULT_LANGUAGE

JSS_EDITING_SECRET -> SITECORE_EDITING_SECRET

SITECORE_EDGE_URL -> NEXT_PUBLIC_SITECORE_EDGE_URL

Refactor Components and Interfaces

Several files in your Next.js app need adjustments. Refactor components, interfaces, and utilities to align with the new Content SDK structure.

  • Copy src/components/SitecoreStyles.tsx from your template app into the same folder in your existing JSS app.

  • In Layout.tsx, import it as follows:

    import SitecoreStyles from 'src/components/SitecoreStyles';

Update References

Components

  • SitecoreContext → SitecoreProvider

Interfaces

  • SitecoreContextProps → SitecoreProviderProps

  • SitecoreContextState → SitecoreProviderState

  • SitecoreContextReactContext → SitecoreProviderReactContext

  • WithSitecoreContextOptions → WithSitecoreOptions

  • WithSitecoreContextProps → WithSitecoreProps

  • WithSitecoreContextHocProps → WithSitecoreHocProps

Higher-Order Components

  • useSitecoreContext() → useSitecore()

  • withSitecoreContext() → withSitecore()

Properties

  • context → page

  • updateSitecoreContext → updatePage

  • sitecoreContext → page

Methods

  • getServerSideProps / getStaticProps → getComponentServerProps

Update Service References and Imports

RestComponentLayoutService -> ComponentLayoutService

RestComponentLayoutServiceConfig -> ComponentLayoutServiceConfig

GraphQLEditingService -> EditingService

GraphQLEditingServiceConfig -> EditingServiceConfig

GraphQLDictionaryService -> DictionaryService

GraphQLDictionaryServiceConfig -> DictionaryServiceConfig

GraphQLLayoutService -> LayoutService

GraphQLLayoutServiceConfig -> LayoutServiceConfig

GraphQLPersonalizeService -> PersonalizeService

GraphQLPersonalizeServiceConfig -> PersonalizeServiceConfig

GraphQLErrorPagesService -> ErrorPagesService

GraphQLErrorPagesServiceConfig -> ErrorPagesServiceConfig

GraphQLRedirectsService -> RedirectsService

GraphQLRedirectsServiceConfig -> RedirectsServiceConfig

GraphQLRobotsService -> RobotsService

GraphQLRobotsServiceConfig -> RobotsServiceConfig

GraphQLSiteInfoService -> SiteInfoService

GraphQLSiteInfoServiceConfig -> SiteInfoServiceConfig

GraphQLSitemapXmlService -> SitemapXmlService

GraphQLSitemapXmlServiceConfig -> SitemapXmlServiceConfig

GraphQLSitePathService -> SitePathService

GraphQLSitePathServiceConfig -> SitePathServiceConfig

Final Clean-Up

Remove all obsolete or replaced code and files as per the official documentation.
This includes legacy GraphQL, dictionary, layout, page-props, and middleware utilities now managed by the Content SDK.

Finally, ensure you:

  • Resolve all errors and warnings during migration.

  • Enable debug logging for Content SDK to identify any runtime issues.

Conclusion

Migrating from the JSS SDK to the Content SDK is a necessary step toward leveraging the full power of XM Cloud.
The new SDK simplifies configuration, reduces dependency complexity, and offers improved integration with the XM Cloud ecosystem.

While the migration process involves several structural updates, following this guide step by step will help you transition smoothly and ensure your application is ready for the modern Sitecore experience.

References:

Migrate JSS 22.8 Next.js apps to Content SDK 1.0

Tags # Content SDK Migration # JSS to Content SDK # Sitecore Continue Reading
By at No comments:
Labels: , , , , , , , ,

Monday, 22 September 2025

Sitecore XM Cloud Content SDK vs. JSS SDK: Key Differences and New Features

September 22, 2025 0

 


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:

    import scConfig from 'sitecore.config';

  • 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:

sitecore-tools project component scaffold

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
    The sitecore-tools project build command 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 the build: section of your CLI config file.

  • The scaffold command
    The sitecore-tools project component scaffold command generates a new component in the src/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 SitecoreClient class 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 SitecoreClient class, centralized config files (sitecore.config.ts, sitecore.cli.config.ts), and the defineMiddleware utility.

The Sitecore XM Cloud Content SDK represents a major step forward in headless development on XM Cloud. Content SDK is providing a streamlined, efficient, and developer-friendly experience. 

References

Tags # headless development # Sitecore CLI # Sitecore Content SDK Continue Reading
By at No comments:
Labels: , , , , , , , , ,

Wednesday, 23 April 2025

Personalization in Sitecore XM Cloud: A Comparative Insight

April 23, 2025 0


Personalization in Sitecore is one of its most powerful and important features, enabling brands to deliver personalized digital experiences to end users and ensure the right content reaches the right contacts. Sitecore XP includes built-in personalization capabilities.

In recent years, the approach has shifted toward headless solutions, which offer greater flexibility, omni-channel delivery, and seamless integration with other digital systems. As a result, Sitecore XM Cloud has emerged as the next logical step for delivering modern digital experiences. However, when transitioning from Sitecore XP to XM Cloud, customers will notice some significant changes—especially in personalization features.

In this blog post, I’ll discuss the embedded personalization feature in XM Cloud, how it differs from Sitecore XP personalization, and its strengths and limitations.

XM Cloud Embedded Personalization

XM Cloud Embedded Personalization is a built-in feature that offers out-of-the-box personalization functionality, allowing marketers to target specific audience segments and tailor content based on audience behavior and characteristics. The capabilities include:

  • Real-time data stream collection

  • Predefined personalization conditions



Additionally, XM Cloud provides real-time website and page analytics—available for each page variant. This gives marketers insights into user behavior on digital properties and allows them to measure the impact of personalized content.



How Personalization Works in XM Cloud

Personalization in XM Cloud is designed to be intuitive and accessible. It is applied at the page level, meaning a specific page variant is shown to a particular audience segment. This approach simplifies the content personalization process and enables marketers to implement changes quickly, without relying on developers.

Personalization in XM Cloud can be based on:

  • Site Behavior: Tailor content based on a visitor’s current behavior.

  • External Referrals: Personalize content for users coming from campaigns like social media ads or email newsletters.

  • Session Data: Deliver content based on location, device type, or browsing history.

Out of the Box Conditions for XM Cloud Personalization

You can define target audiences using any combination of the following conditions:

  • Time – Specific times of day when someone visits the page

  • Date – Specific dates, days of the week/month, or months

  • Device – Device type (e.g., mobile, desktop, tablet) and operating system (e.g., Android, iOS)

  • Geography – Country, region, or state of the visitor

  • Visit – Pages visited during the session or number of past visits

  • User Interaction – Referrer URLs, UTM parameters, and whether the user is new or returning

  • Point of Sale – Audiences that have visited multiple websites under the same site identifier


Sitecore XP Personalization vs XM Cloud Personalization

Sitecore XP offers Rule-based, adaptive and customer historical behavior based personalization where as XM Cloud offer current session based personalization.

Sitecore XP track customer data and experiences across multiple sessions and as per those data customer get personalized experiences. XM Cloud focus on current session/visit only. 

Sitecore XP allows OOTB as well as custom personalization rules, but XM cloud offers only embedded OOTB personalization rules.

Sitecore XP offers component level personalization. Marketers can navigate to a component on a page that has a data source and configure personalization on that component using the trusted rule-set editor, and mapping rules to what content will be shown if certain rule criteria are met. XM Cloud primarily offers page-level personalization, meaning different page variants can be displayed based on predefined conditions.

In Sitecore XP, personalization is more robust with long-term data tracking and support for complex custom rules. Marketers can configure personalization directly on components using the Rule Set Editor.
In contrast, XM Cloud uses a simplified model focusing on session-level personalization and page variants. While this reduces complexity, it also limits the depth of personalization.

Limitations

  • No Custom Conditions: Unlike XP, XM Cloud does not support custom personalization rules.

  • Variant Limits: A maximum of 8 page variants per page and 5 conditions per variant.

  • No Long-Term Tracking: Personalization is session-based; behavior is not retained across visits.

Conclusion

Sitecore XM Cloud Embedded Personalization offers a powerful, easy-to-use solution for delivering targeted content to anonymous users. With built-in real-time data collection, page variants, and analytics, marketers can personalize experiences at scale—favoring simplicity and speed.

However, for businesses requiring advanced features like identity resolution, cross-session tracking, or complex rule logic, Sitecore Personalize is a recommended upgrade. It offers deeper control, API access, and sophisticated audience targeting—ideal for delivering personalized experiences to known users.

In my upcoming blog, I’ll discuss about the how to how to implement personalization in XM cloud.

Tags # Component Development # Headless SXA # Next.js Tutorial Continue Reading
By at No comments:
Labels: , , , , , , , , ,