1. Sitecore Content SDK

Upgrade JSS Next.js apps to Content SDK

Version:

Migrating from the JavaScript Services (JSS) SDK to the Sitecore Content SDK provides a cleaner separation of concerns, a unified data‑fetching model, and improved alignment with framework-native patterns, making applications easier to maintain and evolve over time.

This section provides guidance to help you transition your existing JSS application to the Content SDK.

Migration overview

The migration guide available in this section walks you through the upgrade process using a clean Content SDK starter application as a reference point. By following the guides, you will:

  • Understand how the Content SDK architecture differs from JSS.

  • Learn how to map key concepts such as routing, data fetching, and application configuration.

  • Replace JSS-specific dependencies and patterns with their Content SDK equivalents.

  • Align your application with current Sitecore and framework best practices.

Important

Because every JSS application can include project-specific customisations, integrations, and architectural decisions, these guides cannot account for all possible scenarios. The procedures focus on a clean upgrade path and demonstrate how to transition a standard JSS starter application. If your solution contains custom code or deviations from the starter template, you will need to adapt the steps accordingly.

The recommended migration approach depends on the version of JSS you’re using. If you’re on the latest version of JSS, you can follow the upgrade guide specific to it. But, for older versions, you can use a new Content SDK application as the target and migrate features into it in a controlled, incremental way rather than attempting an in‑place conversion of the existing JSS codebase.

The following steps present a high-level overview:

  1. Start with a newly created Content SDK application.

  2. Use it as a reference to understand the target structure and behaviour.

  3. Gradually move custom functionality from your JSS application into the new app, one feature at a time. This could be a single package, module, or a slice containing specific functionality.

  4. Verify the functionality in the target app and repeat the process.

This staged process allows you to validate each change independently, identify issues early, reduce the risk of regressions, and simplify testing and troubleshooting as your application transitions to the Content SDK.

By following this approach, you can transition to the Content SDK in a controlled and predictable manner while preserving the behaviour of your existing application. The following steps highlight at a high-level the process you'd follow during migration:

  • Start from a clean Content SDK app

    • You can create a new Content SDK Next.js application using the official starter kit and copy the head application into your existing solution. Another alternative is to use the CLI to generate a new head application. You can then use this as the target for your migration rather than converting your existing JSS app in place.

    • Update the new app’s metadata in the package.json file (such as site name and scripts), so it matches your existing project and deployment setup.

  • Move functionality and update imports.

    • Copy your functionality from the JSS application (as components, modules, or slices) into the Content SDK project structure.

    • Replace JSS imports with the corresponding Content SDK imports so that components reference the new SDK libraries instead of @sitecore-jss packages.

    • Run builds or type‑checking to catch and fix any missing or outdated references as you go.

  • Align placeholders, routing, and editing behaviour

    • Update placeholder usage and routing to follow the patterns used by the Content SDK starter

    • Update page‑mode checks so components that behave differently in the editor use the Content SDK page mode API (for example, page.mode.isEditing) to control how empty fields, helper UI, or configuration‑only fields are rendered for content authors.

  • Modernize dependencies and component structure

    • Remove older helper libraries that are no longer needed with newer framework features (for example, replacing class‑name helpers such as clsx with native string templating or framework‑native patterns).

    • Where you use rendering variants, split large multi‑variant components into separate files, following the Content SDK file‑based rendering variant approach to keep each variant focused and easier to maintain.

  • Update configuration, environment variables, and deployments

    • Switch from legacy JSS connection settings (such as API‑key‑only configuration) to the connection model used by the Content SDK, which typically relies on context IDs and related environment variables.

    • Add the required environment variables in your hosting platform (for example, Vercel) and verify that both server‑side and client‑side values are correctly configured for your sites.

    • Ensure the Node.js version in your build and hosting environment meets the minimum LTS requirement for the Content SDK and your chosen Next.js version and perform a full build and deployment to confirm behaviour.

By following these patterns in the version‑specific guides, you can move even older or heavily customised JSS applications onto the Content SDK while gradually aligning them with current Sitecore and framework best practices.

If you have suggestions for improving this article, let us know!