Sitecore JSS to Content SDK: What Actually Changes (Next.js App Router + XM Cloud)

The problem If you run a headless Sitecore site on Next.js, you probably built it on JSS. JSS was centered on the Pages Router: getStaticProps and getStaticPaths, a generated temp/config, and a component builder that registered your renderings. The Content SDK is the supported path for XM Cloud headless apps on the Next.js App Router. (Sitecore now brands XM Cloud as SitecoreAI, and you will see both names in the docs.) It changes the plumbing, and that is where the migration effort goes. The good news is that most of your CMS-facing code does not need rewriting. One note on versions: the code in this post reflects a migration to Content SDK 1.x with the App Router. Content SDK 2.x changes a few names, and I call those out where they apply. Sitecore also publishes step-by-step upgrade guides for each JSS version, which I link at the end. This post is the conceptual map to read alongside them. I recently moved a production app across, so this post is the map I wish I had a

Sitecore JSS to Content SDK: What Actually Changes (Next.js App Router + XM Cloud)

The problem

If you run a headless Sitecore site on Next.js, you probably built it on JSS. JSS was centered on the Pages Router: getStaticProps and getStaticPaths, a generated temp/config, and a component builder that registered your renderings.

The Content SDK is the supported path for XM Cloud headless apps on the Next.js App Router. (Sitecore now brands XM Cloud as SitecoreAI, and you will see both names in the docs.) It changes the plumbing, and that is where the migration effort goes. The good news is that most of your CMS-facing code does not need rewriting.

One note on versions: the code in this post reflects a migration to Content SDK 1.x with the App Router. Content SDK 2.x changes a few names, and I call those out where they apply. Sitecore also publishes step-by-step upgrade guides for each JSS version, which I link at the end. This post is the conceptual map to read alongside them.

I recently moved a production app across, so this post is the map I wish I had at the start. It stays general and only covers patterns that apply to any JSS app.

What stays the same

Before the changes, here is what you keep:

  • The layout JSON shape
  • Placeholders and rendering UIDs
  • Field types (Field, ImageField, and so on)
  • Component names matching renderings
  • Integrated GraphQL on renderings

Your Sitecore item structure and most presentation components stay as they are. What you replace is the adapter layer and the imports.

What changes at a glance

Area JSS Content SDK
Runtime package @sitecore-jss/sitecore-jss-nextjs @sitecore-content-sdk/nextjs
CLI Bootstrap and component builder scripts @sitecore-content-sdk/cli (sitecore-tools)
Config scjssconfig.json and temp/config sitecore.config.ts
Generated output temp/componentBuilder .sitecore/ (component map, import map, sites, metadata)
Routing pages/[[...path]].tsx app/[...path]/page.tsx
Data fetching Layout service factories and page-props plugins SitecoreClient
React context SitecoreContext SitecoreProvider
Context hook useSitecoreContext() useSitecore()
Editing Pages API routes App Router route handlers

1. Dependencies and build toolchain

Swap the runtime package and add the CLI. Your scripts typically become:

  • sitecore-tools project build, which generates metadata, sites and imports
  • sitecore-tools project component generate-map, which generates the component map (often with --watch in dev)

The important rule is that the Sitecore tools must run before next build. In my setup, sitecore.cli.config.ts wires up generateMetadata, generateSites, extractFiles and writeImportMap over the Sitecore component folder, with excludes for tests and non-component files.

2. Configuration: one typed config file

JSS spread host names and keys across scjssconfig.json, temp/config and environment variables. The Content SDK pulls this into one file, sitecore.config.ts, using defineConfig:

import { defineConfig } from '@sitecore-content-sdk/nextjs/config';

export default defineConfig({
  api: {
    edge: { /* contextId, edgeUrl, clientContextId */ },
    local: { /* apiKey, apiHost */ },
  },
  defaultSite: process.env.NEXT_PUBLIC_DEFAULT_SITE_NAME,
  // defaultLanguage, editingSecret, redirects, multisite, personalize...
});

api.edge covers XM Cloud and Edge. api.local covers local XM, containers and fallback. Middleware and the client both consume the redirects, multisite and personalize settings.

Commit a sitecore.config.ts.example and keep secrets in environment variables only. The mental shift is to stop reading temp/config everywhere. You import sitecore.config and build a single SitecoreClient from it.

3. Generated artifacts: .sitecore/

The component builder output is replaced by a .sitecore/ folder containing the component map, client component map, import maps, sites.json and metadata.json.

import components from '.sitecore/component-map';

A client-side provider passes that map into SitecoreProvider and loads .sitecore/import-map.client for editor and design library scenarios.

Most teams git-ignore these generated files. If you do, document that CI has to run sitecore-tools before the build, or the build will fail on missing imports.

4. Routing: Pages Router to App Router

The JSS catch-all route had getStaticPaths, getStaticProps, a page-props factory with plugins for layout, dictionary, component props and redirects, and SitecoreContext with a component factory.

The Content SDK version is an async Server Component:

// app/[...path]/page.tsx
const page = await client.getPage(path, { site, locale });

For components that export getServerSideProps, a small helper resolves their data:

getComponentProps(page, componentMap, context);

The rest is a thin presentational wrapper plus a client SitecorePageProvider.

A few changes here are Next.js shifts and not Sitecore-specific: params is now a Promise, you call notFound() from next/navigation, and revalidate and dynamic become route segment config instead of getStaticProps.revalidate.

When stripping multisite or personalization prefixes from the URL, use the SDK helpers normalizeSiteRewrite and normalizePersonalizedRewrite, since middleware may add those prefixes back.

5. Data access: layout service factories to SitecoreClient

Retire the GraphQLLayoutService and RestLayoutService factories and the large page-props factory. Replace them with one client:

import { SitecoreClient } from '@sitecore-content-sdk/nextjs/client';
import scConfig from 'sitecore.config';

const client = new SitecoreClient({ ...scConfig });

await client.getPage(itemPath, { site, locale });
await client.getDictionary({ site, locale });
client.getHeadLinks(layoutData, options);

If you run custom GraphQL, import GraphQLRequestClient from @sitecore-content-sdk/nextjs/client and not from JSS.

6. React integration: context and hooks

JSS Content SDK
SitecoreContext with layoutData SitecoreProvider with page: Page
useSitecoreContext() useSitecore()
layoutData.sitecore.context.pageEditing page.mode.isEditing
withSitecoreContext withSitecore

An editing check after migration looks like this:

const { page } = useSitecore();
return page.mode.isEditing ?? false;

Pass page, not only raw layoutData, into the placeholder.

One caution: because placeholders are client-bound, it is tempting to mark the whole Layout as a client component. Sitecore's own migration notes warn against this, since it cancels out the benefits of the App Router. Keep the main Layout a Server Component where you can, and push the client boundary down to the providers and components that need it.

7. Placeholders

becomes:

<AppPlaceholder
  page={page}
  componentMap={components}
  name="..."
  rendering={route}
/>

Nested placeholder keys and rendering UIDs are largely unchanged. Only the component API is different.

8. Middleware: multisite, locale, redirects, personalize

JSS used a custom plugin list from its middleware package. The Content SDK gives you ready-made classes:

import {
  defineMiddleware,
  LocaleMiddleware,
  AppRouterMultisiteMiddleware,
  RedirectsMiddleware,
  PersonalizeMiddleware,
} from '@sitecore-content-sdk/nextjs/middleware';
import sites from '.sitecore/sites.json';
import scConfig from 'sitecore.config';

// Chain: locale, multisite, redirects, personalize
await defineMiddleware(locale, multisite, redirects, personalize).exec(req, ev);

A version note: in Content SDK 2.x, defineMiddleware is renamed defineProxy, in line with Next.js 16. The composition idea is the same, so check which name your SDK version uses.

Order matters. Run LocaleMiddleware first when your locales are not only defined in next.config.js i18n, which is common with App Router and next-intl. Feed sites from the generated sites.json and spread the relevant slice of scConfig into each middleware.

9. Experience Editor and Pages builder

JSS used Pages API routes: an editing render route backed by EditingRenderMiddleware, and an editing data route that cached stashed payloads in Preview Mode.

The Content SDK replaces these with App Router route handlers:

  • app/api/editing/render/route.ts using createEditingRenderRouteHandlers
  • app/api/editing/config/route.ts using createEditingConfigRouteHandler, with the component map, client map and metadata

The handlers include CORS and OPTIONS handling for the page builder, so there is less custom glue. Set editingSecret in sitecore.config.ts and make sure the rendering host URL in Sitecore matches your deployed app.

10. Component-level server data

This part barely changes. Components still export getServerSideProps and read rendering, layout context and componentProps[uid] through context. The difference is that you call a small getComponentProps helper that walks the placeholders on page.layout, instead of relying on the JSS page-props factory.

Integrated GraphQL fields still come with the layout from getPage(). getServerSideProps is only for extra queries, the same split as before.

11. Types and page props

SitecorePageProps gains a first-class page: Page. I kept layoutData, componentProps, dictionary, site and locale alongside it so I could refactor gradually. Imports move from @sitecore-jss/sitecore-jss-nextjs to @sitecore-content-sdk/nextjs.

12. Environment variables checklist

Add or emphasize for Edge:

  • SITECORE_EDGE_CONTEXT_ID and NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID
  • SITECORE_EDGE_URL and NEXT_PUBLIC_SITECORE_EDGE_URL
  • SITECORE_EDITING_SECRET

Often retained for local development:

  • NEXT_PUBLIC_SITECORE_API_KEY and NEXT_PUBLIC_SITECORE_API_HOST
  • NEXT_PUBLIC_DEFAULT_SITE_NAME and NEXT_PUBLIC_DEFAULT_LANGUAGE

Retire or repoint:

  • JSS-only disconnected mode variables such as JSS_MODE
  • Debug namespaces like sitecore-jss:*. Confirm the Content SDK logging names in the docs.

13. BYOC and FEAAS

BYOC bundles still use @sitecore-feaas/clientside. The context usually comes from SitecoreProviderReactContext and page.layout.sitecore.context for page state, with the Edge URL and context ID taken from sitecore.config.

Suggested migration order

  1. Upgrade Next.js and adopt the App Router, or start from Sitecore's official Content SDK starter.
  2. Swap packages and add sitecore.config.ts and sitecore.cli.config.ts.
  3. Wire build scripts and generate the .sitecore/ artifacts.
  4. Replace the catch-all data fetching with SitecoreClient.getPage.
  5. Replace SitecoreContext with SitecoreProvider and the component map.
  6. Run a global find-and-replace for imports, useSitecore, AppPlaceholder and the editing routes.
  7. Port middleware to the Content SDK classes and sites.json.
  8. Remove the layout service factories, old page-props plugins, pages/[[...path]] and the archived editing API routes.
  9. Regression test production paths, multisite, preview and editing, personalization and ISR or revalidation.

Gotchas

  • Forgetting the pre-build step. If sitecore-tools does not run before next build, the .sitecore/ imports are missing and the build fails.
  • Client and server split on the layout. Marking the whole Layout as a client component undoes the App Router benefits. Keep it a Server Component where possible and keep client boundaries small. Pass page into the placeholders.
  • Version drift. Names such as defineMiddleware and defineProxy differ between Content SDK 1.x and 2.x, so match the code to the guide for your version.
  • Experience Editor is gone. The Content SDK supports visual editing only through the page builder, and Content Editor preview is not supported. Plan for that if your editors still rely on it.
  • Reimplementing component props walking. Use a single getComponentProps helper and do not scatter this logic.
  • Middleware order with i18n. Run locale handling first, then multisite, redirects and personalize.

Why this approach

  • Typed, central config. One sitecore.config.ts replaces scattered keys and generated config.
  • App Router and Edge-first client. Server Components fetch the page directly with SitecoreClient.
  • Simpler editing setup. Route handlers replace most of the custom editing middleware.
  • Small blast radius. Item structure, rendering names and most presentation components stay as they are. Only the adapter layer and SDK imports change.

What I would improve next

  • Add automated tests around getComponentProps and the middleware chain.
  • Add a CI check that fails fast when sitecore-tools has not generated .sitecore/.
  • Document a rollback path for multisite and personalization during cutover.

Further reading

Wrap up

Moving from JSS to the Content SDK is mostly a plumbing exercise: one typed config, generated .sitecore/ artifacts, the App Router, one SitecoreClient, and updated providers, hooks and middleware. Your content model and most components carry over.

If you are planning this migration, start by upgrading to the App Router and generating the .sitecore/ artifacts, then work through the data fetching and provider changes in the order above.

I would love to hear what tripped you up when moving from JSS to the Content SDK. Let me know in the comments.

Share