Upgrade JSS 22.0 Next.js apps to Content SDK 2.1

Copy the following files from the template app into your existing app:

Throughout your app, replace all imports of config from temp/config and use the new sitecore.config.ts file instead:

A new page parameter has been added to SitecoreContext. To support this change, update the SitecoreContext API configuration in the following files:

In each file, set the api parameter to use scConfig.api and the page parameter to use page as shown in the following example:

import scConfig from 'sitecore.config'; 
... 
const page = client.getPage(...); 
<SitecoreContext 
  ... 
  api={scConfig.api} 
  page={page} 
>

Rename the following environment variables within your JSS app:

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.

If you have explicitly configured edgeUrl in sitecore.config, set it to the following:

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.

If your existing app uses DISABLE_SSG_FETCH rename it to GENERATE_STATIC_PATHS.

Copy the src/lib/sitecore-client.ts file from your template app into the same folder in your existing JSS app.

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:

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.

In [[..path]].tsx, 404.tsx, 500.tsx, and Layout.tsx, remove all usages of headLinks.

In Bootstrap.tsx:

In CdpPageView.tsx:

The @sitecore-content-sdk/react package introduces the following updated types and signatures:

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:

No runtime changes are required in this step beyond adjusting renamed fields.

The withPlaceholder higher-order component now only accepts the component as an argument and injects a placeholders prop derived from props.rendering.placeholders.

The withSitecore higher-order component is deprecated. The recommended alternative is the useSitecore hook.

To update your code, find the current implementation:

import {
  withSitecore,
  type SitecoreProviderState,
} from '@sitecore-content-sdk/react';
type Props = Partial<SitecoreProviderState> & { customProp: string };
const MyComponent: React.FC<Props> = ({ page, api, setPage, customProp }) => {
  // ...
};
export default withSitecore({ updatable: true })(MyComponent);

Replace it with the following:

import { useSitecore } from '@sitecore-content-sdk/react';
type Props = { customProp: string };
const MyComponent: React.FC<Props> = ({ customProp }) => {
  const { page, api, setPage } = useSitecore({ updatable: true });
  // ...
};

Placeholder and AppPlaceholder are stricter and now pass only the following props to the components rendered for a placeholder:

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 best practices.

The SitecoreProvider component now requires the loadImportMap prop. Update the SitecoreProvider implementation as shown:

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 ( 
    <ComponentPropsContext value={componentProps || {}}> 
      <SitecoreProvider 
        componentMap={components} 
        api={scConfig.api} 
        page={page} 
        loadImportMap={() => import('.sitecore/import-map')} 
      > 
        {children} 
      </SitecoreProvider> 
    </ComponentPropsContext> 
  ); 
}; 

export default Providers; 

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:

... 
      <div className={mainClassPageEditing}> 
        {mode.isDesignLibrary ? ( 
          <DesignLibrary /> 
        ) : ( 
          <> 
            <header> 
              <div id="header"> 
.. 

The renderEmptyPlaceholder method from the Placeholder class has been removed.

import React from 'react'; 
import { Placeholder } from '@sitecore-content-sdk/react'; 

class MyCustomPlaceholder extends Placeholder { 
  render() { 
    ... 
    if (!placeholderRenderings.length) { 
      ... 
      return this.renderEmptyPlaceholder(emptyContent); 
    } 
    // Regular rendering logic 
    return super.render(); 
  } 
} 

If your implementation relies on that method for custom placeholders, you can use the renderEmptyPlaceholder helper method exported from react and nextjs packages.

import React from 'react'; 
import { PlaceholderComponent, renderEmptyPlaceholder } from '@sitecore-content-sdk/react'; 

class Placeholder extends Placeholder { 
  render() { 
    ... 
    if (!placeholderRenderings.length) { 
      ... 
      return renderEmptyPlaceholder(emptyContent); 
    }
    // Regular rendering logic 
    return super.render(); 
  }
} 

By disabling React Suspense in placeholders, components render faster without the added Suspense overhead. However, if your app uses lazy-loaded components inside a <Placeholder> and expects a loading fallback to appear, you need to perform the following steps while upgrading:

Copy the new component src/components/content-sdk/SitecoreStyles.tsx from your template app into the same folder in your existing JSS app.

In Layout.tsx, import SitecoreStyles and place the component after Scripts, as shown in the following example:

import SitecoreStyles from 'src/components/SitecoreStyles'; 
...  
    <Scripts /> 
    <SitecoreStyles layoutData={layoutData} /> 
...

Throughout your JSS app, remove all usages of the publicUrl property of the now-obsolete config.

Update references and imports for the following component, interfaces, higher-order components, and properties:

Remove the SitecoreContext interface and update any references with the new Page interface from the SitecoreClient.

Update references to the getServerSideProps and getStaticProps methods to getComponentServerProps without changing the existing method signature.

If your component contains code that's executed based on static or server side Next.js context, import the isServerSidePropsContext helper method and implement it based on the following example:

import { isServerSidePropsContext } from '@sitecore-content-sdk/nextjs/utils';  
...  
export const getComponentServerProps: GetComponentServerProps = async (  
rendering,  
layoutData,  
context  
) => {  
if (isServerSidePropsContext(context)) {  
    // function implementation  
}  
};

Update references and imports for the following services if you use them directly or substitute them by using the methods in the SitecoreClient class:

Delete the DictionaryService interface and remove any references to it.

Update the src/lib/component-props/index.ts file in your existing app using the one from your template app.

Throughout your app, wherever is used, do the following:

Update any remaining imports of temp/componentBuilder to use .sitecore/component-map instead.

The @sitecore-content-sdk/content package has been decoupled from @sitecore-content-sdk/core to create a more focused "core" that can be referenced by other packages. The following changes are only required if you directly import from @sitecore-content-sdk/core.

In your package.json file, do the following:

Copy the sitecore.cli.config.ts file from your template app into your existing app.

Because the build time artifacts metadata.json and sites.json (the second of which used to be called config.sites) are now created under the .sitecore temp folder at the root of the app, you need to update the imports of these artifacts accordingly throughout your application, making sure to rename instances of config.sites to sites.json.

Content SDK introduces the sitecore-tools:build command that, similar to next:build, is used to generate build-time artifacts required for your app to function. Make sure this script is executed before you start your application.

In your existing app's next.config.js file, make the following changes:

Next.js 16 expects you to define allowable external image sources using remotePatterns instead of images.domains. Remove all entries of images.domains and set remotePatterns to allow Sitecore media URLs. Refer to the template app's next.config.js|ts file for more information.

The Page type now includes a mode field of type PageMode, that provides runtime context (editing, preview, the Design Studio, etc). Update references to layout context properties like pageState, pageEditing, and renderingType with the new page.mode field as shown in the examples below:

If you've customized your existing JSS app, refer to the obsolete JSS functionality section and make all changes necessary to refactor your code and then remove the obsolete parts of your app, such as: