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--watchin 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
<Placeholder name="..." rendering={route} /> 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.tsusingcreateEditingRenderRouteHandlers -
app/api/editing/config/route.tsusingcreateEditingConfigRouteHandler, 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_IDandNEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID -
SITECORE_EDGE_URLandNEXT_PUBLIC_SITECORE_EDGE_URL SITECORE_EDITING_SECRET
Often retained for local development:
-
NEXT_PUBLIC_SITECORE_API_KEYandNEXT_PUBLIC_SITECORE_API_HOST -
NEXT_PUBLIC_DEFAULT_SITE_NAMEandNEXT_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
- Upgrade Next.js and adopt the App Router, or start from Sitecore's official Content SDK starter.
- Swap packages and add
sitecore.config.tsandsitecore.cli.config.ts. - Wire build scripts and generate the
.sitecore/artifacts. - Replace the catch-all data fetching with
SitecoreClient.getPage. - Replace
SitecoreContextwithSitecoreProviderand the component map. - Run a global find-and-replace for imports,
useSitecore,AppPlaceholderand the editing routes. - Port middleware to the Content SDK classes and
sites.json. - Remove the layout service factories, old page-props plugins,
pages/[[...path]]and the archived editing API routes. - Regression test production paths, multisite, preview and editing, personalization and ISR or revalidation.
Gotchas
-
Forgetting the pre-build step. If
sitecore-toolsdoes not run beforenext 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
pageinto the placeholders. -
Version drift. Names such as
defineMiddlewareanddefineProxydiffer 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
getComponentPropshelper 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.tsreplaces 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
getComponentPropsand the middleware chain. - Add a CI check that fails fast when
sitecore-toolshas not generated.sitecore/. - Document a rollback path for multisite and personalization during cutover.
Further reading
- JSS to Content SDK upgrade, Sitecore's overview of the migration paths, including a first-hand account.
- Upgrade JSS 22.0 Next.js apps to Content SDK 2.1, the step-by-step guide for the latest version.
- Upgrade your JSS 22.9/22.10 Next.js apps to Content SDK 1.3.1, which includes the App Router general release.
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.
Top comments (0)