--- title: "Upgrade JSS 22.0 Next.js apps to Content SDK 2.1" slug: "upgrade-jss-22-0-next-js-apps-to-content-sdk-2-1" abstract: "How to upgrade your JSS 22.0 Next.js apps to Content SDK 2.1." --- # Upgrade JSS 22.0 Next.js apps to Content SDK 2.1 Content SDK is a major upgrade from previous versions of Sitecore JavaScript Services SDK (JSS) for SitecoreAI. It reduces the size and complexity of starter applications, removing redundant functionality not needed for SitecoreAI implementations. As a result, Content SDK applications are easier to understand and maintain than apps built with JSS. This comprehensive guide covers all the changes you must make to your existing JSS 22.0 applications to migrate to Content SDK 2.1. However, because of the nature of JavaScript and Next.js application development, this guide doesn't account for all the customization you might have in your existing application. While upgrading, consider the JSS templates and add-ons you used when creating your Next.js JSS application. You can find them in your `package.json` file. For example, a JSS 22.0 application based on the XM Cloud starter kit uses the following templates and add-ons, so this guide assumes your app includes all of them: - nextjs - nextjs-xmcloud - nextjs-sxa - nextjs-multisite > [!note] > **XM Cloud is now SitecoreAI** > Some code examples, images, and UI labels may still use XM Cloud while engineering assets are being updated. > [!note] > **Before you begin** > - If you haven't already done so, [upgrade your app to JSS 22.0.0](https://doc.sitecore.com/sai/en/developers/jss/22/jss-sai/upgrade-jss-21-7-next-js-apps-to-version-22-0-0.html). > > - We recommend you read the official release notes for [React 19](https://react.dev/blog/2024/04/25/react-19-upgrade-guide) and [Next.js 16](https://nextjs.org/docs/app/guides/upgrading/version-15) to understand what has changed in these new versions. > > - Familiarize yourself with the [JSS](https://github.com/Sitecore/jss/blob/dev/CHANGELOG.md) and [Content SDK](https://github.com/Sitecore/content-sdk/blob/dev/CHANGELOG.md) changelogs. If your application is heavily customized, the changelog can provide guidance on what additional changes you need that are not covered in this topic. This topic covers the following subjects: :::walkthrough 1. [What's new in Content SDK?](https://doc.sitecore.com/sai/en/developers/content-sdk/20/upgrade-jss-22-0-next-js-apps-to-content-sdk-2-1.html#whats-new-in-content-sdk) 2. [Update application dependencies through all versions](https://doc.sitecore.com/sai/en/developers/content-sdk/20/upgrade-jss-22-0-next-js-apps-to-content-sdk-2-1.html#update-application-dependencies-through-all-versions) 3. [Create a Content SDK 2.1 application](https://doc.sitecore.com/sai/en/developers/content-sdk/20/upgrade-jss-22-0-next-js-apps-to-content-sdk-2-1.html#create-a-content-sdk-21-application) 4. [Update the SXA add-on](https://doc.sitecore.com/sai/en/developers/content-sdk/20/upgrade-jss-22-0-next-js-apps-to-content-sdk-2-1.html#update-the-sxa-add-on) 5. [Disable automatic GraphQL code generation](https://doc.sitecore.com/sai/en/developers/content-sdk/20/upgrade-jss-22-0-next-js-apps-to-content-sdk-2-1.html#disable-automatic-graphql-code-generation) 6. [Update existing forms to use the new wrapper](https://doc.sitecore.com/sai/en/developers/content-sdk/20/upgrade-jss-22-0-next-js-apps-to-content-sdk-2-1.html#update-existing-forms-to-use-the-new-wrapper) 7. [Migrate to Content SDK architecture](https://doc.sitecore.com/sai/en/developers/content-sdk/20/upgrade-jss-22-0-next-js-apps-to-content-sdk-2-1.html#migrate-to-content-sdk-architecture) 8. [Obsolete and revised functionality in your existing app](https://doc.sitecore.com/sai/en/developers/content-sdk/20/upgrade-jss-22-0-next-js-apps-to-content-sdk-2-1.html#obsolete-and-revised-functionality-in-your-existing-app) ::: ## What's new in Content SDK? Here's a short overview of the changes introduced in Content SDK: - Includes out-of-the-box support for the Design Studio that serves as a centralized interface to help teams visualize and test components across their organization. - Three brand new site templates in addition to the classic Skatepark template. - A new file, `sitecore.config.ts`, serves as the central point for configuring your application's build and run time. - Another new file, `sitecore.cli.config.ts`, used to configure CLI commands for Content SDK that enable it to replace build-time and dev tools scripts. - The new Sitecore Client Data Fetching API, represented by the `SitecoreClient` class, unifies all data fetching logic and replaces the previous data fetching plugins. - A new utility named `defineProxy` (previously called defineMiddleware in Content SDK version 1.5 and earlier), simplifies proxy composition and provides better visibility by removing the need for proxy plugins. - Supports the enhanced SitecoreAI page builder in place of the Sitecore Experience Editor. - Analytics, event tracking, and personalization support out of the box. ## Update application dependencies through all versions For your upgraded application to work correctly, you will need to update dependencies. To update your dependencies: 1. In your existing application's `package.json` file, update packages progressively: - Remove any dependencies that start with `@sitecore-cloudsdk/` and add the following: ``` "@sitecore-content-sdk/analytics-core": "^2.0.0", "@sitecore-content-sdk/personalize": "^2.0.0", "@sitecore-content-sdk/events": " ^2.0.0", ``` > [!note] > See the Cloud SDK integration section for further steps to complete the migration from `@sitecore-cloudsdk` to the Content SDK packages. - Update `@types/node` to version `^24.10.4`. - Update `@typescript-eslint/eslint-plugin` to version `^8.14.0`. - Update `@typescript-eslint/parser` to version `^8.14.0`. - Update `eslint` to version `^8.56.0`. In Content SDK 1.1 and higher, ESLint 9 is the default linter, but you can continue using the older one or [optionally upgrade to ESLint 9](https://doc.sitecore.com/sai/en/developers/content-sdk/20/update-eslint-to-version-9.html). - Update `typescript` to version `~5.4.0`. - Install `sharp@0.32.6` for improved memory usage using the following command: ```shell npm i sharp@0.32.6 ``` - Update React and Next.js: ```json "next": "^16.1.1", "react": "^19.1.0", "react-dom": "^19.1.0", "@types/react": "^19.1.2", "@types/react-dom": "^19.1.3", "eslint-plugin-react": "^7.37.5" ``` - Update `@sitecore-feaas/clientside` to version `^0.6.0`. - Update `@sitecore/components` to version `~2.1.0`. - Replace `@sitecore-jss/sitecore-jss-nextjs` with `@sitecore-content-sdk/nextjs`. Set the version to `^2.0.0`. - Replace all references to `@sitecore-jss/sitecore-jss-nextjs` with `@sitecore-content-sdk/nextjs` throughout your application. - Replace `@sitecore-jss/sitecore-jss-cli` with `@sitecore-content-sdk/cli`. Set the version to `^2.0.0`. - Delete `@sitecore-jss/sitecore-jss-dev-tools`. 2. Install dependencies with the following command: ```shell npm install ``` 3. Update your ESLint configuration by making the following changes to the `.eslintrc` file: ```csharp "@typescript-eslint/no-unused-vars": [ "error", { "caughtErrorsIgnorePattern": "." } ], ``` 4. Make the following changes to `tsconfig.json`: - Add above the `lib` entry: ```json ... "types": ["node"], ... ``` - Delete the following from `compilerOptions.paths`: ```json "graphql-types": ["node_modules/@types/graphql-let/__generated__/__types__"], ``` ## Create a Content SDK 2.1 application To simplify the upgrade process as much as possible, create a Content SDK application. You can then copy some files from this template app into your existing app. To create a Next.js Content SDK application: 1. In a console, run the following command: ```shell npx create-content-sdk-app@2.1.0 nextjs ``` 2. If prompted to install the `create-content-sdk-app@2.1.0` package, answer `y`. 3. Enter the folder path for the new app. For example, enter `./content-sdk-template`, to create the named subfolder in your current working directory. 4. When prompted, choose the same prerendering method (`SSG` or `SSR`) as used in your existing JSS application. The script then installs the application dependencies. ## Update the SXA add-on The Content SDK template has a lean footprint. It doesn’t have components that were previously available in the JSS starter kit. To use those components, the recommended approach is to copy them from [Content SDK starter kit](https://github.com/Sitecore/xmcloud-starter-js/tree/main). Note that if you’ve customized your components in JSS, you must replicate them in the Content SDK versions too. To update the SXA add-on: 1. Replace the following files with the new versions from the starter kit: - `src/components/Image.tsx` - `src/components/Promo.tsx` - `src/components/Title.tsx` - `src/assets/sass/components/title/_component-title.scss` 2. Update the following SASS files: - `src/assets/sass/components/_component-column-splitter.scss:` ```scss padding-left: $default-padding * 0.5; padding-right: $default-padding * 0.5; ``` - In `/src/assets/sass/components/promo/_promo-shadow.scss`, reposition CSS statements above the `@include respond-to(all-mobile)` block: ```scss ... >.component-content { padding: 15px; margin: 0 0 30px 0; @include respond-to(all-mobile) { margin: 0 10px 30px 10px; } &:before, &:after { ... src/lib/next-config/plugins/sass.js: sassOptions: { ... quietDeps: true, silenceDeprecations: ["import", "legacy-js-api"], }, ``` ## Disable automatic GraphQL code generation To disable automatic GraphQL code generation: 1. Remove the following dependencies from `package.json`: ``` "@graphql-typed-document-node/core": "^3.2.0", "graphql-let": "^0.18.6", "graphql": "~15.8.0", "graphql-tag": "^2.12.6", "@graphql-codegen/cli": "^5.0.0", "@graphql-codegen/import-types-preset": "^3.0.0", "@graphql-codegen/plugin-helpers": "^5.0.1", "@graphql-codegen/typed-document-node": "^5.0.1", "@graphql-codegen/typescript": "^4.0.1", "@graphql-codegen/typescript-operations": "^4.0.1", "@graphql-codegen/typescript-resolvers": "^4.0.1", ``` 2. Remove the `graphql:update` script and remove `graphql-let` reference from `bootstrap` script: ```text "bootstrap": "ts-node --require dotenv-flow/config --project tsconfig.scripts.json scripts/bootstrap.ts", ``` 3. Delete the following files: - `.graphql-let.yml` - `/scripts/fetch-graphql-introspection-data.ts` - `/src/temp/GraphQLIntrospectionResult.json` ## Update existing forms to use the new wrapper To update existing forms: 1. In Content Editor, select the page containing the existing form. 2. Click **Presentation** > **Details**. 3. In the **Final Layout** tab, click **Edit** under **Headless Layout**. 4. Select the **BYOC Wrapper** control and click **Change**. 5. Select **Feature** > **Headless Experience Accelerator** > **Forms** > **Form** and click **Select**. 6. Click **Edit**. 7. Copy the `formId` from the **Component Name** parameter (only the value after `?formId=`). 8. Paste it into the **FormId** field at the top. 9. Delete all items in the **Parameters** section. 10. Click **OK**. 11. Repeat for all forms. When all forms are updated, remove the following from `/src/byoc/index.client.tsx`: ```ts import '@sitecore/components/form'; ``` ## Migrate to Content SDK architecture The following sections explain how to synchronize files in your existing JSS application with corresponding files from your Content SDK template app. This also includes steps to complete the Next.js 16 upgrade, Cloud SDK integration, React 19 refactor, and update other template files. ### Update configurations and environment variables This section updates your existing app's configurations and environment variables to match the new Content SDK app. To update your JSS app's configurations and environment variables: 1. Copy the following files from the template app into your existing app: - `sitecore.config.ts` - `src/Providers.tsx` - `src/Bootstrap.tsx` 2. Throughout your app, replace all imports of `config` from `temp/config` and use the new `sitecore.config.ts` file instead: - Locate all instances of the following: ```ts import config from 'temp/config' ``` - Replace these with the following: ```text import scConfig from 'sitecore.config' ``` 3. A new `page` parameter has been added to `SitecoreContext`. To support this change, update the `SitecoreContext` API configuration in the following files: - `[[...path]].tsx` - `500.tsx` - `404.tsx` In each file, set the `api` parameter to use `scConfig.api` and the `page` parameter to use `page` as shown in the following example: ```ts import scConfig from 'sitecore.config'; ... const page = client.getPage(...); ``` 4. Rename the following environment variables within your JSS app:

Old (JSS)

New (Content SDK)

SITECORE_API_KEY

NEXT_PUBLIC_SITECORE_API_KEY

SITECORE_API_HOST

NEXT_PUBLIC_SITECORE_API_HOST

SITECORE_SITE_NAME

NEXT_PUBLIC_DEFAULT_SITE_NAME

DEFAULT_LANGUAGE

NEXT_PUBLIC_DEFAULT_LANGUAGE

JSS_EDITING_SECRET

SITECORE_EDITING_SECRET

5. If your application currently depends on `SITECORE_EDGE_URL`, remove all instances of `SITECORE_EDGE_URL` from env files and deployment configurations. Set the following new variable(s) to the same value and restart the app. Rebuild for Next.js so that `NEXT_PUBLIC_*` is in the client bundle. - `NEXT_PUBLIC_SITECORE_EDGE_PLATFORM_HOSTNAME` - for Next.js projects so both server and client use the custom host. - `SITECORE_EDGE_PLATFORM_HOSTNAME` - non Next.js or server only If you have explicitly configured `edgeUrl` in `sitecore.config`, set it to the following: ```ts edgeUrl: process.env.NEXT_PUBLIC_SITECORE_EDGE_PLATFORM_HOSTNAME || 'https://edge-platform.sitecorecloud.io', ``` For non‑Next.js environments, mirror this pattern with the `SITECORE_EDGE_PLATFORM_HOSTNAME` variable instead. > [!note] > Newly scaffolded apps use `defineConfig()` and get `edgeUrl` from the new environment variable automatically, so you might not have the `edgeUrl` section under edge. > > The default value of `` is used unless you use the new variables. > > `SITECORE_EDGE_CONTEXT_ID` does not need to be renamed unless you need client-side access. > > If needed, create `NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID` with the same value. Doing this will expose your context ID secret on the client. 6. If your existing app uses `DISABLE_SSG_FETCH` rename it to `GENERATE_STATIC_PATHS`. > [!note] > The meaning and value of this variable has been logically inverted. If your existing solution uses this variable in the code, you must adjust them accordingly. 7. Copy the `src/lib/sitecore-client.ts` file from your template app into the same folder in your existing JSS app. 8. Middleware has been renamed to proxy in Next.js 16 to better reflect its purpose. Instead of Next.js discovering middleware automatically by filename, it now runs the `proxy.ts` file directly. Refactor all Next.js middleware in your existing app to use the new `defineProxy` utility: - Create `src/proxy.ts`. Add your proxy logic here. The file must export a single function (default export or named proxy) that accepts a `NextRequest` and returns the result of the proxy chain as shown: ```ts export default function proxy(req: NextRequest) { // ... create locale, multisite, redirects, personalize instances ... return defineProxy(locale, multisite, redirects, personalize).exec(req); } export const config = { matcher: [...] }; ``` - Ensure that your proxy order is correct: - For Next.js apps using App Router - locale → multisite → redirects → personalize - For Next.js apps using Pages Router - multisite → redirects → personalize > [!note] > Ensure you delete `src/proxy.ts` and the old `src/lib/middleware/` (or equivalent) before adding `src/middleware.ts` with `defineMiddleware`, using the template as reference. 9. Individual API route files (for sitemap, robots, editing endpoints, health) still use the `Middleware` classes to implement their actual behavior for those specific routes. The `proxy.ts` file only handles edge requests and routing behavior.

Item

Description

For sitemap and robots.txt

Use SitemapMiddleware or RobotsMiddleware from @sitecore-content-sdk/nextjs/middleware

Editing APIs

Use EditingConfigMiddleware, EditingRenderMiddleware, or FEAASRenderMiddleware from @sitecore-content-sdk/nextjs/editing

Healthcheck

Use the HealthcheckMiddleware from @sitecore-content-sdk/nextjs/monitoring

10. In `[[..path]].tsx`, `404.tsx`, `500.tsx`, and `Layout.tsx`, remove all usages of `headLinks`. ### Cloud SDK integration The Content SDK has undergone a major architectural transformation to include functionality from the Cloud SDK. The Content SDK now includes tracking, events, and personalization. To enable these changes: 1. In `Bootstrap.tsx`: - Find the CloudSDK initialization logic: ```ts CloudSDK({ sitecoreEdgeUrl: config.api.edge.edgeUrl, sitecoreEdgeContextId: config.api.edge.clientContextId, siteName: page.siteName || config.defaultSite, enableBrowserCookie: true, // Replace with the top level cookie domain of the website that is being integrated e.g ".example.com" and not "www.example.com" cookieDomain: window.location.hostname.replace(/^www\./, ''), }) .addEvents() .initialize(); ``` - Replace it with the following: ```ts initContentSdk({ config: { contextId: config.api.edge.clientContextId, edgeUrl: config.api.edge.edgeUrl, siteName: page.siteName || config.defaultSite, }, plugins: [ analyticsPlugin({ options: { enableCookie: true, cookieDomain: window.location.hostname.replace(/^www\./, ''), }, adapter: analyticsBrowserAdapter(), }), eventsPlugin(), ], }); ``` - Remove the following imports: ```ts import { CloudSDK } from '@sitecore-cloudsdk/core/browser'; import { SitecorePageProps } from '@sitecore-content-sdk/nextjs'; import '@sitecore-cloudsdk/events/browser'; ``` - Add the following imports: ```ts import { SitecorePageProps, initContentSdk } from '@sitecore-content-sdk/nextjs'; import { eventsPlugin } from '@sitecore-content-sdk/events'; import { analyticsBrowserAdapter, analyticsPlugin } from '@sitecore-content-sdk/analytics-core'; ``` 2. In `CdpPageView.tsx`: - Find the following import: ```ts import { pageView } from '@sitecore-cloudsdk/events/browser'; ``` - Replace it with the following: ```ts import { pageView } from '@sitecore-content-sdk/events'; ``` You might also have to make further changes to other files that contains older Cloud SDK logic based on your implementation. See Initializing tracking, events, and personalization in the Content SDK for more information. ### Refactor aligned with React 19 best practices React logic in the Content SDK has been refactored to follow React 19 best practices. The following section outlines the breaking changes introduced by this refactor and provides examples of the new implementations. 1. The `@sitecore-content-sdk/react` package introduces the following updated types and signatures: - `useSitecore(options?: UseSitecoreOptions): SitecoreProviderState` - `SitecoreProviderState` now includes: - `page: Page` - `api?: SitecoreProviderProps['api']` - `setPage?: (value: Page) => void (renamed from updatePage)` - `componentMap: ComponentMap (new)` - `loadImportMap: () => Promise (new)` - `PlaceholderProps` is expanded to explicitly list all supported properties: ```ts export interface PlaceholderProps { name: string; rendering: ComponentRendering | RouteData; componentMap?: ComponentMap; page?: Page; fields?: { [name: string]: Field | Item | Item[] }; params?: { [name: string]: string }; disableSuspense?: boolean; errorComponent?: React.ComponentClass | React.FC; hiddenRenderingComponent?: React.ComponentClass | React.FC; missingComponentComponent?: React.ComponentClass | React.FC; componentLoadingMessage?: string; renderEmpty?: (components: React.ReactNode[]) => React.ReactNode; renderEach?: (component: React.ReactNode, index: number) => React.ReactNode; render?: (components: React.ReactNode[], data: ComponentRendering[], props: PlaceholderProps) => React.ReactNode; passThroughComponentProps?: { [key: string]: unknown }; } ``` These updates make the context shape and placeholder behavior explicit and compatible with React 19 best practices, especially for server and client components. The additional fields (`componentMap`, `loadImportMap`) support more flexible composition and lazy loading. To update your code: - Review all imports and usages of `SitecoreProviderState` and `PlaceholderProps`. - If you relied on implicit properties, update your type annotations to the new explicit interface. - If you used `updatePage`, rename it to `setPage`. - If you previously inferred types from usage, consider importing the updated types from `@sitecore-content-sdk/react` to align with 2.1. No runtime changes are required in this step beyond adjusting renamed fields. 2. The `withPlaceholder` higher-order component now only accepts the component as an argument and injects a placeholders prop derived from `props.rendering.placeholders`. - Find implementations of a single placeholder: ```ts import { withPlaceholder, PlaceholderProps } from '@sitecore-content-sdk/react'; type HomeProps = PlaceholderProps; const Home: React.FC = ({ pageContent }) => (
{pageContent}
); export default withPlaceholder('page-content')(Home); ``` - Replace it with the following: ```csharp import { withPlaceholder } from '@sitecore-content-sdk/react'; type HomeProps = { placeholders: Record; }; const Home: React.FC = ({ placeholders }) => (
{placeholders['page-content']}
); export default withPlaceholder(Home); ``` > [!important] > When rendering the wrapper on a server component in Next.js App Router while using `withAppPlaceholder`, you must still pass the `rendering`, `page`, and `componentMap` props: > > ```javascript > const WrappedHome = withAppPlaceholder(Home); > > rendering={page.layout.sitecore.route} > page={page} > componentMap={componentMap} > /> > ; > ``` - If you rely on a multi-placeholder mapping as shown: ```ts type HomeProps = PlaceholderProps & { subProp?: React.ReactElement; }; const Home: React.FC = ({ subProp, pageContent }) => (
{subProp}
{pageContent}
); export default withPlaceholder( [ { placeholder: 'page-header', prop: 'subProp' }, 'page-content', ] )(Home); ``` - Convert it as shown: ```ts type HomeProps = { placeholders: Record; }; const Home: React.FC = ({ placeholders }) => (
{placeholders['page-header']}
{placeholders['page-content']}
); export default withPlaceholder(Home); ``` 3. The `withSitecore` higher-order component is deprecated. The recommended alternative is the `useSitecore` hook. To update your code, find the current implementation: ```ts import { withSitecore, type SitecoreProviderState, } from '@sitecore-content-sdk/react'; type Props = Partial & { customProp: string }; const MyComponent: React.FC = ({ page, api, setPage, customProp }) => { // ... }; export default withSitecore({ updatable: true })(MyComponent); ``` Replace it with the following: ```ts import { useSitecore } from '@sitecore-content-sdk/react'; type Props = { customProp: string }; const MyComponent: React.FC = ({ customProp }) => { const { page, api, setPage } = useSitecore({ updatable: true }); // ... }; ``` > [!note] > If you continue using `withSitecore`, the `updatePage` prop it previously injected is now named `setPage`. 4. `Placeholder` and `AppPlaceholder` are stricter and now pass only the following props to the components rendered for a placeholder: - Context properties (`page`, `componentMap`) - `fields`, `params` and `rendering` data ```ts fields: { [name: string]: Field | Item | Item[]; }; params: { [name: string]: string; }; rendering: ComponentRendering; ``` The `modifyComponentProps` callback is still available, but it should not be required for simple prop injection. For example, the following usage: ```ts { ...props, extraDiv: true } } /> ``` Can be streamlined using `passThroughComponentProps` as shown: ```ts ``` 5. All built-in Content SDK components that previously relied on `React.forwardRef` (such as `RichText`, `Link`, and others) now treat `ref` as a regular prop instead of using `forwardRef`. This change follows [React 19 recommendations](https://react.dev/reference/react/forwardRef) best practices. > [!important] > Please refer to the official [React 19 upgrade guide](https://react.dev/blog/2024/04/25/react-19-upgrade-guide) to update other parts of your application that's not specific to the Content SDK. 6. The `SitecoreProvider` component now requires the `loadImportMap` prop. Update the `SitecoreProvider` implementation as shown: ```ts import { ComponentPropsCollection, ComponentPropsContext, Page, SitecoreProvider, } from '@sitecore-content-sdk/nextjs'; import components from '.sitecore/component-map'; import scConfig from 'sitecore.config'; const Providers = ({ children, componentProps, page, }: { children: React.ReactNode; componentProps?: ComponentPropsCollection; page: Page; }) => { return ( import('.sitecore/import-map')} > {children} ); }; export default Providers; ``` 7. The `DesignLibrary` component no longer receives an import map as a prop. Instead, it is provided by the `SitecoreProvider` component. For Content SDK apps based on Pages Router, the `DesignLibrary` component is present in `src/Layout.tsx` and must be updated: ```ts ...
{mode.isDesignLibrary ? ( ) : ( <>