Blog 3: Hands-on Migration Walkthrough: Migrating Next.js from JSS to Sitecore Content SDK

Hi Sitecorian Folks! 👋

Welcome back to our hands-on migration series! In the last blog, we covered how to prepare your project for migrating from JSS to the Sitecore Content SDK. Now it’s time to get into the nitty-gritty details with a practical, step-by-step walkthrough of how to migrate a Next.js app to the Sitecore Content SDK.

By the end of this blog, you’ll be ready to start migrating your own Next.js apps with the Sitecore Content SDK. Let’s dive right in!

1. Setting Up Your Sitecore Content SDK Environment

Before diving into code migration, the first thing you’ll need to do is set up the Sitecore Content SDK in your development environment.

Step 1: Install Dependencies

For this migration, you’ll need to install the required packages for Next.js and the Sitecore Content SDK. The official Sitecore documentation provides instructions on how to integrate the SDK with your app.

# Create a new Next.js project (if you don't have one)
npx create-next-app sitecore-content-sdk-nextjs
cd sitecore-content-sdk-nextjs
# Install Sitecore Content SDK dependencies
npm install @sitecore/content-sdk @sitecore/nextjs

These packages enable seamless communication between your Next.js front-end and Sitecore’s headless APIs.

Step 2: Set Up Your Sitecore Instance

To work with the Content SDK, you’ll need a Sitecore instance, either on Sitecore XM Cloud or a self-hosted Sitecore solution. Here’s how to configure it for headless delivery:

• Create a Sitecore Experience Edge for content delivery (this is necessary to access headless content through APIs).
• Generate an API key from the Sitecore Experience Edge dashboard. This key will be used to authenticate API calls.

For more details on configuring Sitecore XM Cloud and Experience Edge, refer to the official Sitecore XM Cloud documentation.

Once you have the API key, you’ll configure the Content SDK to point to your Sitecore instance.

2. Migrating Content Fetching Logic

In JSS, content was often fetched using GraphQL queries or Sitecore Web API calls. The Sitecore Content SDK simplifies this process by using built-in API calls that are easier to integrate into modern front-end frameworks.

Here’s an example of how content fetching changes when migrating from JSS to Content SDK:

JSS Example (Before):

In JSS, you might have used GraphQL to fetch content:

query getHomePageData {
  homePage {
    title
    description
    featuredImage {
      src
      alt
    }
  }
}

Sitecore Content SDK Example (After):

With the Content SDK, fetching content is more direct and streamlined:

import { createClient } from '@sitecore/content-sdk';
 
const client = createClient({
  endpoint: 'https://your-sitecore-instance-url',
  apiKey: 'your-api-key'
});

async function getHomePageContent() {
  const response = await client.fetch('homePage'); // Fetches the homepage data
  return response.data;
}

export default async function HomePage() {
  const content = await getHomePageContent();
 
  return (
    <div>
      <h1>{content.title}</h1>
      <p>{content.description}</p>
      <img src={content.featuredImage.src} alt={content.featuredImage.alt} />
    </div>
  );
}

Key Sources:

• Sitecore Content SDK Documentation
• Sitecore Experience Edge API Documentation

3. Migrating Component Structure

In JSS, components were typically tied to Sitecore items, and you used JSS’s React components (or other framework-specific components) to fetch and render content. The Content SDK simplifies this structure by enabling direct API calls.

Here’s a practical migration of a Featured Article component:

JSS Example (Before):

import { graphql } from 'react-apollo';
import gql from 'graphql-tag';
 
const FeaturedArticle = ({ data }) => {
  return (
    <div>
      <h2>{data.featuredArticle.title}</h2>
      <p>{data.featuredArticle.content}</p>
    </div>
  );
};

const GET_FEATURED_ARTICLE = gql`
  query getFeaturedArticle {
    featuredArticle {
      title
      content
    }
  }
`;

export default graphql(GET_FEATURED_ARTICLE)(FeaturedArticle);
Sitecore Content SDK Example (After):
import { createClient } from '@sitecore/content-sdk';
import { useState, useEffect } from 'react';
 
const client = createClient({
  endpoint: 'https://your-sitecore-instance-url',
  apiKey: 'your-api-key'
});
 
const FeaturedArticle = () => {
  const [article, setArticle] = useState(null);
 
  useEffect(() => {
    async function fetchData() {
      const response = await client.fetch('featuredArticle');
      setArticle(response.data);
    }
 
    fetchData();
  }, []);
 
  if (!article) return <div>Loading...</div>;
 
  return (
    <div>
      <h2>{article.title}</h2>
      <p>{article.content}</p>
    </div>
  );
};
 
export default FeaturedArticle;

Key Sources:

• Sitecore Content SDK React Integration Guide
• Next.js with Sitecore Content SDK

4. Migrating Media Management

Media management is another important aspect when migrating from JSS to Content SDK. Sitecore’s media handling improves in the Content SDK, offering easier ways to manage and display media.

In JSS, you may have used GraphQL to fetch media data. With the Content SDK, media items can be easily accessed via the API:

JSS Example (Before):

query getMediaItem {
  mediaItem(id: "12345") {
    url
    altText
  }
}

Sitecore Content SDK Example (After):

const getMediaItem = async (mediaId) => {
 const response = await client.fetch(`media/${mediaId}`);
 return response.data;
};

const MediaComponent = ({ mediaId }) => {
const [media, setMedia] = useState(null);
useEffect(() => {
  async function fetchMedia() {
  const mediaData = await getMediaItem(mediaId);
  setMedia(mediaData);
}
fetchMedia();
}, [mediaId]);
if (!media) return <div>Loading…</div>;
  return <img src={media.url} alt={media.altText} />;
};

Key Sources:

• Sitecore Media API Documentation

5. Testing and Debugging

Once your migration is complete, it’s essential to thoroughly test and debug your Next.js app. Even though Sitecore Content SDK simplifies the process, here are a few best practices for testing:

• Check for Missing Data: Ensure that all your content models and APIs are correctly integrated into your app.
• Profile Performance: Although the Content SDK is optimized, make sure to profile your application using tools like Chrome DevTools to avoid performance bottlenecks.
• QA Across Environments: Always test both in local development and production environments to ensure smooth content delivery.

For testing and debugging tips, refer to Sitecore’s best practices guide for headless applications.

Conclusion

That’s a wrap on our hands-on migration from JSS to Sitecore Content SDK! 🎉 We’ve walked through the essential steps of migrating your Next.js app, including setting up the SDK, migrating content fetching logic, simplifying components, and working with media management.

In our next blog, we’ll dive into best practices and troubleshooting tips to help you with any bumps along the way.

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.