Sitecore MVP Amit Kumar

How to Migrate Your Next.js App from Sitecore JSS to Content SDK

Amit Kumar 0

👋 Introduction
The Sitecore Content SDK for XM Cloud is a transformative tool for front-end development. This modern SDK simplifies the complexities of the JSS Next.js SDK, enhancing performance and developer efficiency. It offers seamless integration with XM Cloud’s headless architecture, featuring built-in GraphQL utilities, real-time visual editing, and support for multi-site, personalization, and analytics. Learn how to migrate your existing JSS app to the Content SDK and connect it to a local XM Cloud setup using Docker, optimizing your development process with a streamlined Next.js template.

In this guide, we’ll explore:
  1. What the Content SDK is    
  2. Key benefits over JSS
  3. How to migrate from JSS   
  4. Connecting to a local XM Cloud Docker setup   
📋 What Is the Sitecore Content SDK for XM Cloud?   

  • Overview  
    The Sitecore Content SDK for XM Cloud is a modern, open-source toolkit for developers creating JavaScript apps that integrate smoothly with Sitecore XM Cloud. This SDK offers APIs and services to easily access, manage, and deliver content, focusing on scalability, speed, and simplicity. 
  •  
  • It's a lightweight alternative to the traditional Sitecore JSS framework, optimized for XM Cloud, and provides tools and APIs for high-performance headless apps. The Content SDK removes unnecessary JSS features, speeding up development. It replaces the older JSS Next.js SDK with a streamlined JavaScript SDK for XM Cloud, featuring built-in GraphQL tools, real-time visual editing, multi-site support, personalization, and analytics, all in a simple Next.js template. This toolkit simplifies setup, offering a Next.js starter template with the necessary tools and services for XM Cloud development.
  • Benefits of Sitecore Content SDK  
    The Content SDK provides several key benefits for developers using Sitecore XM Cloud. Key features include:
    1. Simplified Architecture: Reduced complexity compared to JSS   
    2. Enhanced Performance: Optimized for XM Cloud-specific scenarios   
    3. Better TypeScript Support: Improved type definitions and IntelliSense   
    4. Smaller Bundle Size: Lighter footprint for faster loading times   
    5. Streamlined Development: Fewer configuration decisions required   
⚖ Content SDK vs. Sitecore JSS: Key Differences
Here’s how the Content SDK differs from JSS:

Feature Sitecore JSS Next.js SDK Sitecore Content SDK
Bundle SizeLarger, includes unused XP featuresSmaller, XM Cloud-optimized
ComplexityHigh configuration overhead (supports multiple platforms)Lower (XM Cloud-focused)
TypeScript SupportBasicEnhanced with better IntelliSense
PerformanceGoodOptimized for headless scenarios
Learning CurveSteepEasier and more user-friendly
IntegrationRequires manual setupPre-configured for XM Cloud
Supported EditorsExperience Editor, partial PagesXM Cloud Pages (metadata)
Personalization & AnalyticsLimited, more setup neededBuilt-in
Maintenance & UpgradesTied to XM/XP releasesDecoupled, independent
Customization FlexibilityHighly extensible, but complexEnhanced via starter kit
Environment VariablesUses legacy variable names (e.g., SITECORE_API_KEY)Uses NEXT_PUBLIC_ prefixes for consistency

  • Performance Improvements  
    The Content SDK offers significant performance improvements:
    1. Faster Build Times: Fewer dependencies and better bundling
    2. Improved Runtime Performance: Lightweight API calls
    3. Better Tree Shaking: More effective removal of unused code
    4. Enhanced Caching: Better content delivery systems

🔄 Migrating from JSS Next.js SDK to Content SDK
To migrate an existing JSS Next.js app (version 22.5) to the Sitecore Content SDK, it's essential to follow the official guidelines provided by Sitecore. By adhering to these steps, you can ensure a smooth transition from the JSS Next.js SDK to the Content SDK, optimizing your application for enhanced performance and streamlined development.
  • 1️⃣ Update Environment Variables  
    The Content SDK now uses new environment variable names with the NEXT_PUBLIC_  prefix to match Next.js standards, and some environment variables have been renamed. Update your .env or .env.local file like this:
    Old Name (JSS)New Name (Content SDK)
    SITECORE_API_KEYNEXT_PUBLIC_SITECORE_API_KEY
    SITECORE_API_HOSTNEXT_PUBLIC_SITECORE_API_HOST
    SITECORE_SITE_NAMENEXT_PUBLIC_DEFAULT_SITE_NAME
    DEFAULT_LANGUAGENEXT_PUBLIC_DEFAULT_LANGUAGE
    JSS_EDITING_SECRETSITECORE_EDITING_SECRET

  • 2️⃣ Removal of Unnecessary JSS-Specific Files  
    Simplify your project by getting rid of old JSS-specific scripts and settings. This will reduce clutter and make things run more smoothly:
    1. src/sxastarter/src/lib/layout-service-factory.ts (replaced with Content SDK’s built-in methods)
    2. sconfig/index.ts
    3. plugins like computed.ts, multisite.ts, etc. inside plugins folder
    4. src/temp/config.js (JSS config)
    5. src/sxastarter/.graphql-let.yml
    6. src/sxastarter/scripts/config/index.ts
    7. src/sxastarter/scripts/config/plugins
    8. src/sxastarter/scripts/bootstrap.ts
    9. src/sxastarter/scripts/generate-component-builder
    10. src/sxastarter/scripts/scaffold-component

    Check out the detailed change log here.
  • 3️⃣ Refactor Code  
    1. Replace @sitecore-jss/sitecore-jss-nextjs ➡️ @sitecore-content-sdk/nextjs
    2. Replace import { componentBuilder } from '../src/temp/componentBuilder' ➡️ import componentMap from '.sitecore/component-map'
    3. Remove refrences of require('./src/temp/config') and require('./src/temp/next-config-plugins')
    4. Changes in next.config.js:
      1. Removed JSS-specific webpack configurations
      2. Consolidate all Next.js configuration in next.config.js
      3. Set defaultLocale dynamically.
      4. Migrate all Next config plugin logic (previously located in the src/lib/next-config folder) and all associated custom settings into the next.config.js file, then delete the now-redundant files from the lib folder
      5. Modify next.config.js to integrate Content SDK middleware and services
    5. Refactor all middleware to use the defineMiddleware utility in src/sxastarter/src/middleware.ts
    6. Added src/lib/sitecore-client.ts
    7. Added src/sxastarter/src/components/content-sdk/SitecoreStyles.tsx

  • 4️⃣ Update Pages and Components  
    1. Replace 'temp/config' ➡️ 'sitecore.config'
    2. Replace 'temp/componentBuilder' ➡️ '.sitecore/component-map'
    3. Remove obsolete headLinks usages from page files ([[...path]].tsx , 404.tsx , 500.tsx , Layout.tsx )
    4. Replace import { SitecorePageProps } from 'lib/page-props' and import { SitecorePageProps } from '@sitecore-content-sdk/nextjs'
    5. Remove the usage of WidgetsProvider
    6. Replace temp/metadata.json' ➡️ '.sitecore/metadata.json'
    7. Replace import type { NextApiRequest, NextApiResponse } from 'next' ➡️ import { RobotsMiddleware } from '@sitecore-content-sdk/nextjs/middleware' in src/sxastarter/src/pages/api/robots.ts
    8. Replace import type { NextApiRequest, NextApiResponse } from 'next'; ➡️ import { SitemapMiddleware } from '@sitecore-content-sdk/nextjs/middleware'; in src/sxastarter/src/pages/api/sitemap.ts
    9. Add an import for import { JSX } from 'react'; wherever JSX.Element is used in the components
    10. Change how you access environment variables from process.env ➡️ config , for example, change process.env.NEXT_PUBLIC_PERSONALIZE_SCOPE to config.personalize?.scope
    11. Change how you access nextConfig using 'next.config' from nextConfig() ➡️ nextConfig
    12. Update how you check if the page is in EDIT mode from layoutData.sitecore.context.pageEditing / sitecoreContext.pageEditing to span page.mode.isEditing
    13. Change how you access styles from the properties parameters. Instead of using props.params.styles.trimEnd(), use styles with the parameter style property (params). Check the example in src/sxastarter/src/components/PageContent/Accordion.tsx
    14. Access the field values from the fields object instead of props.fields
    15. Replace useSitecoreContext ➡️ useSitecore
    16. Replace props.rendering ➡️ rendering

  • 5️⃣ Final Clean-up  
    Remove all obsolete or replaced code and files according to the documentation, including legacy GraphQL, dictionary, layout, page-props, and middleware utilities now managed by the Content SDK. Ensure you resolve any errors or warnings during migration and enable debug logging for Content SDK issues if needed.

    To see the migration process, check the changes in the Sitecore XM Cloud Vertical Demo codebase between the main branch and the feature/XMC-VERTICALS-CONTENT-SDK-V1 branch. You can view the detailed change log at Sitecore XM Cloud Verticals: JSS to Content SDK Migration - Complete Commit Log.

🌐 Connecting Your Content SDK App Locally or Docker
To use the updated Content SDK app after the upgrade, follow these steps:
  • 1️⃣ Go to the src/sxastarter folder and do the following changes in .env file:

    The Content SDK uses new environment variable names with the NEXT_PUBLIC_  prefix to match Next.js standards. Update your .env or .env.local file like this:
    • XM Cloud Preview Context  
      1. Environment variables needed to set up the XM Cloud Preview site locally 
        SITECORE_EDITING_SECRET=<ADD THE JSS EDITING SECRET>
NEXT_PUBLIC_DEFAULT_SITE_NAME=<ADD THE SITE NAME>
SITECORE_EDGE_CONTEXT_ID=<ADD THE PREVIEW CONTEXT ID>
NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID=<KEEP IT EMPTY>

      2. Environment variables needed to set up the XM Cloud Preview site on Vercel 
        SITECORE_EDITING_SECRET=<ADD THE JSS EDITING SECRET>
NEXT_PUBLIC_DEFAULT_SITE_NAME=<ADD THE SITE NAME>
SITECORE_EDGE_CONTEXT_ID=<ADD THE PREVIEW CONTEXT ID>
NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID=<KEEP IT EMPTY>
FETCH_WITH=GraphQL 
PUBLIC_URL=<KEEP IT EMPTY>

    • XM Cloud Live Context (XM Cloud PROD Site)  
      1. Environment variables needed to set up the XM Cloud Live (PROD) site locally 
        NEXT_PUBLIC_DEFAULT_SITE_NAME=<ADD THE SITE NAME>
SITECORE_EDGE_CONTEXT_ID=<ADD THE PREVIEW CONTEXT ID>
NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID=<KEEP IT EMPTY>

      2. Environment variables needed to set up the XM Cloud Live (PROD) site on Vercel ℹ️ I'm having trouble setting up the XM Cloud Website on Vercel with XM Cloud LIVE Context. I'm working on fixing these issues and will update the settings once I find a solution. Thank you for your patience and understanding.
  • 2️⃣ In the src/sxastarter folder, run the following commands: 

    npm install

npm ci --silent

npm run lint

npm prettier --write .

  • 3️⃣ Execute npm run build in your front-end project directory

  • 4️⃣ Execute npm run start:connected or npm run dev in your front-end project directory

  • 5️⃣ Once you see the below logs then access the http://localhost:3000 on your browser: 
    For help, see: https://nodejs.org/en/docs/inspector
   the --inspect option was detected, the Next.js router server should be inspected at 9230.
   ▲ Next.js 15.4.3
   - Local:        http://localhost:3000
   - Network:      http://192.168.1.155:3000
   - Environments: .env

 ✓ Starting...
 ✓ Ready in 34.5s

    Site should load:
🔚Conclusion
The Sitecore Content SDK for XM Cloud significantly advances front-end development by simplifying and optimizing the creation and management of XM Cloud applications. It offers a streamlined, lightweight approach compared to the Sitecore JSS Next.js SDK, tailored for XM Cloud’s headless architecture. By following migration steps and connecting to a local XM Cloud setup, developers can achieve faster development cycles, easier customization, and seamless integration, enhancing the Sitecore XM Cloud experience for modern cloud development.

ℹ️ Visit the XM Cloud Vertical GitHub Repo (Scan the QR code below 👇) to explore the complete codebase and resources. This will help you understand how the project is set up, its structure, and the migration process using the Sitecore Content SDK.

If you've had similar issues with SCS, share your solutions 🔠 or tips 💬 to help others in the community.

If you enjoy this content, consider subscribing 📰 for more updates and insights. Your engagement is very important to me and helps me keep providing valuable resources! 🌟
🔗Pingback
Connect XM Cloud Pages to your local XM instance: When you use Docker for full-stack development in XM Cloud, and after you set up your local XM Cloud development environment, XM Cloud Pages is not connected to your locally running XM instance. Set up your full-stack XM Cloud local development environment: When you create an XM Cloud project using the XM Cloud Deploy app and choose the foundation template as the source for the initial deployment, the process adds the foundation template to the source control repository you configured for the initial environment. XM Cloud dynamic placeholders and Content SDK: Content SDK takes advantage of dynamic placeholders to drive layout and content dynamically in Content SDK applications
Upgrade Your Sitecore XM Cloud Next.js Front-End: Streamline your Sitecore XM Cloud Next.js upgrades with expert tips, tools, and step-by-step guidance for safer, faster front-end updates. Meet the Sitecore Content SDK for XM Cloud Upgrade JSS 22.5 Next.js apps to version 22.6
Avoiding Sitecore XM Cloud Errors - Enlighten with Amit 🚨 XM Cloud (XMC) Update 🚨 | Amit Kumar XM Cloud Changelog | Sitecore Developer Portal
Handling Duplicate Content in Sitecore – Strategies to identify and resolve duplicate content problems in large-scale Sitecore implementations. XM Cloud Serialization Best Practices – Sitecore Docs Sitecore’s recommendations for serialization in XM Cloud, including modular architecture tips. How to Fix Sitecore Content Serialization Errors (SCS) for Duplicate Items with Sitecore PowerShell (SPE)
Fixing Serialization Conflicts - A community discussion on resolving ‘non-unique path’ errors in Sitecore SCS, with tested solutions. Sitecore CLI and Serialization How to integrate Sitecore CLI with serialization for DevOps-friendly workflows. SPE Script Repository – Sitecore Community - A curated collection of PowerShell scripts for Sitecore, including content tree maintenance.
Tags

Amit Kumar

My name is Amit Kumar. I work as a hands-on Solution Architect. My experience allows me to provide valuable insights and guidance to organizations looking to leverage cutting edge technologies for their digital solutions.As a Solution Architect, I have extensive experience in designing and implementing robust and scalable solutions using server-side and client-side technologies. My expertise lies in architecting complex systems, integrating various modules, and optimizing performance to deliver exceptional user experiences. Additionally, I stay up-to-date with the latest industry trends and best practices to ensure that my solutions are always cutting-edge and aligned with business objectives.

Post a Comment

Post a Comment
Previous Post Next Post