Upgrade Content SDK 0.3.0 Next.js apps to version 1.0.0

This guide covers most of the changes you must make to your existing Content SDK 0.3.0 applications to take advantage of the new features and improvements in version 1.0.0.

This version of the Content SDK introduces code extraction support for the Design studio, refactors the SitecoreClient class, improves the site resolution logic, and more. Code extraction is the first prerequisite to enable Design studio's AI code generation.

Because JavaScript and Next.js development is very flexible and customizable, this guide provides only general instructions and might not cover the specific configurations, custom code, or architectural decisions present in your existing application.

Before you begin

If you have a JSS app that you want to convert into a Content SDK app, follow the migration guide to upgrade your JSS Next.js 22.8 app to a Content SDK 1.0 app, instead of this topic.
Familiarize yourself with the changelog. 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 describes how to:

Rename service classes

You don't need to follow this procedure if you're using the methods in SitecoreClient. If you are accessing the Content SDK services directly, you must make these changes:

Update references and imports for the following:

Old	New	Type
`RestComponentLayoutService`	`ComponentLayoutService`	service class
`RestComponentLayoutServiceConfig`	`ComponentLayoutServiceConfig`	interface
`GraphQLEditingService`	`EditingService`	service class
`GraphQLEditingServiceConfig`	`EditingServiceConfig`	interface
`GraphQLDictionaryService`	`DictionaryService`	service class
`GraphQLDictionaryServiceConfig`	`DictionaryServiceConfig`	interface
`GraphQLLayoutService`	`LayoutService`	service class
`GraphQLLayoutServiceConfig`	`LayoutServiceConfig`	interface
`GraphQLPersonalizeService`	`PersonalizeService`	service class
`GraphQLPersonalizeServiceConfig`	`PersonalizeServiceConfig`	type
`GraphQLErrorPagesService`	`ErrorPagesService`	service class
`GraphQLErrorPagesServiceConfig`	`ErrorPagesServiceConfig`	interface
`GraphQLRedirectsService`	`RedirectsService`	service class
`GraphQLRedirectsServiceConfig`	`RedirectsServiceConfig`	type
`GraphQLRobotsService`	`RobotsService`	service class
`GraphQLRobotsServiceConfig`	`RobotsServiceConfig`	type
`GraphQLSiteInfoService`	`SiteInfoService`	service class
`GraphQLSiteInfoServiceConfig`	`SiteInfoServiceConfig`	type
`GraphQLSitemapXmlService`	`SitemapXmlService`	service class
`GraphQLSitemapXmlServiceConfig`	`SitemapXmlServiceConfig`	type
`GraphQLSitePathService`	`SitePathService`	service class
`GraphQLSitePathServiceConfig`	`SitePathServiceConfig`	interface

Remove all usages of the DictionaryService interface.

Update application dependencies in your existing app

For your upgraded application to work correctly, you must update dependencies.

To update your dependencies:

In your existing application's package.json file, update every @sitecore-content-sdk package to version 1.0.0.
Install the dependencies with the following command:
RequestResponse
```
npm install
```

Create a template 1.0.0 Content SDK application for Next.js

To simplify the upgrade process as much as possible, create a Content SDK 1.0.0 Next.js application. You can then copy some files from this app into your existing app.

To create a 1.0.0 Content SDK Next.js application:

In a console, run the following command:
RequestResponse
```
npx [email protected] nextjs
```
If prompted to install the [email protected] package, answer y.
Enter the folder path for the new app. For example, enter ./content-sdk-100, to create the app folder in your current working directory.
When prompted, choose the same prerendering method (SSG or SSR) as used in your existing Content SDK application.

The script then installs the application dependencies.

Update the Next.js template files in your existing app

After updating your dependencies, you must synchronize files in your existing application.

To update the Next.js template files:

In src/lib/sitecore-client.ts:
- Delete the following import:
  RequestResponse
  import sites from '.sitecore/sites.json';
- Remove the sites reference from the SitecoreClient declaration.
The site property of the type Page has been renamed to siteName.

In src/Bootstrap.tsx and src/Pages/[[...path]].tsx, replace all occurrences of props.site?.name with props.siteName.
The getStaticPaths() method in the SitecoreClient now has an additional sites parameter of type SiteInfo.

If you're pre-rendering your app using the SSG (Static Site Generation) method, in src/Pages/[[...path]].tsx:
- Add the following import:
  RequestResponse
  import sites from '.sitecore/sites.json';
- Find the following line:
  RequestResponse
  paths = await client.getPagePaths(context?.locales || []);
- Replace it with the following:
  RequestResponse
  paths = await client.getPagePaths( sites.map((site: SiteInfo) => site.name), context?.locales || [] );
SitecorePageProps now uses a standalone page field instead of merging all data into one props object. Update your page-level functions (getStaticProps, getServerSideProps) to return the new structure.
- Find the following:
  RequestResponse
  export const getStaticProps = () => { ... const page = await client.getPage(...); return { props: { ...page } } }
- Replace it with the following:
  RequestResponse
  export const getStaticProps = () => { ... const page = await client.getPage(...); return { props: { page } } }
- Repeat the same steps for the getServerSideProps page-level method.
- Update all pages that consume SitecorePageProps to use the new props.page structure instead of accessing merged properties directly.
The Page type now includes a mode field of type PageMode that provides runtime context (editing, preview, Design studio, and so on). Update references to layout properties like pageState, pageEditing, and renderingType with the new page.mode field as shown in the following examples:

If the rendering mode isDesignLibrary:
- Find the following:
  RequestResponse
  if (layoutData.sitecore.context.renderingType === RenderingType.Component) { ... }
- Replace it with the following:
  RequestResponse
  if (page.mode.isDesignLibrary) { ... }
If the rendering mode isNormal:
- Find the following:
  RequestResponse
  if (pageState === LayoutServicePageState.Normal) { ... }
- Replace it with the following:
  RequestResponse
  if (page.mode.isNormal) { ... }
Lastly, if the rendering mode isEditing or isPreview:
- Find the following:
  RequestResponse
  if (pageState === LayoutServicePageState.Edit || pageState === LayoutServicePageState.Preview) { ... }
- Replace it with the following:
  RequestResponse
  if (page.mode.isEditing || page.mode.isPreview) { ... }

Update the getErrorPages() method with the new getErrorPage() method. This method returns a specific error page, for example, 404.tsx, 500.tsx.

Find references to the getErrorPages() method:

RequestResponse

export const getStaticProps = () => {
  const resultErrorPages = await client.getErrorPages({ site, locale });
  return {
    props: {
      layout: resultErrorPages?.notFoundPage?.rendered || null,
    }
  }
}

Replace it with the following for a 404 page:

RequestResponse

export const getStaticProps = () => {
  const page = await client.getErrorPage(ErrorPage.NotFound, { site, locale });
  return {
    props: {
      page
    }
  }
}

Replace it with the following for a 500 page:

RequestResponse

export const getStaticProps = () => {
  const page = await client.getErrorPage(ErrorPage.InternalServerError, { site, locale });
  return {
    props: {
      page
    }
  }
}

Update the SitecoreProvider component to use the new page prop instead of the layout prop.
- Find the following:
  RequestResponse
  <SitecoreProvider layoutData={layoutData} ...>...</SitecoreProvider>
- Replace it with the following:
  RequestResponse
  <SitecoreProvider page={page} ...>...</SitecoreProvider>
Remove the SitecoreProviderPageContext interface and any references to it. Use the Page interface from the SitecoreClient instead.
Remove the NextjsPage interface and any references to it. All page-generating methods now return a single Page type.

The useSitecore() hook and withSitecore() higher-order component have been updated for clarity and consistency. You can now access all Page entity information directly via the context.

For the useSitecore() hook:

Find the following:

RequestResponse

import { useSitecore } from '@sitecore-content-sdk/nextjs'

const { pageContext, updateContext } = useSitecore();

Replace it with the following:

RequestResponse

import { useSitecore } from '@sitecore-content-sdk/nextjs'

const { page, updatePage } = useSitecore();

For the withSitecore() higher-order component:

Find the following:

RequestResponse

import { withSitecore } from '@sitecore-content-sdk/nextjs'

function MyComponent({ pageContext, updateContext }) {...}

export default withSitecore(MyComponent);

Replace it with the following:

RequestResponse

import { withSitecore } from '@sitecore-content-sdk/nextjs'

function MyComponent({ page, updatePage }) {...}

export default withSitecore(MyComponent);

You must provide an additional sites parameter to the RobotsMiddleware constructor.

In src/pages/api/robots.ts:
- Add the following import:
  RequestResponse
  import sites from '.sitecore/sites.json';
- Find the following line:
  RequestResponse
  const handler = new RobotsMiddleware(scClient).getHandler();
- Replace it with the following:
  RequestResponse
  const handler = new RobotsMiddleware(scClient, sites).getHandler();
You must provide an additional sites parameter to the SitemapMiddleware constructor.

In src/pages/api/sitemap.ts:
- Add the following import:
  RequestResponse
  import sites from '.sitecore/sites.json';
- Find the following line:
  RequestResponse
  const handler = new SitemapMiddleware(scClient).getHandler();
- Replace it with the following:
  RequestResponse
  const handler = new SitemapMiddleware(scClient, sites).getHandler();

In sitecore.cli.config.ts:

Find the following import:

RequestResponse

import { generateSites, generateMetadata } from '@sitecore-content-sdk/nextjs/tools';

Replace it with the following:

RequestResponse

import { generateSites, generateMetadata, extractFiles } from '@sitecore-content-sdk/nextjs/tools';

Inside the defineCliConfig block, after generateSites({...}), add the following:

RequestResponse

export default defineCliConfig({
  build: {
    commands: [
      generateMetadata(),
      generateSites({
        scConfig: config,
      }),
      extractFiles({
        scConfig: config,
      }),
    ],
  },
  ...
});

Important

Code extraction is enabled by default. If you want to opt out of it, in sitecore.config.ts, add the following parameter inside defineConfig({...}) block:

RequestResponse

export default defineConfig({
    ...
    disableCodeGeneration: true,
    ...
});

Upgrade Content SDK 1.0.0 Next.js apps to version 1.0.1

Apps based on Content SDK 1.0.0 and earlier had a middleware-related bug that was fixed in Content SDK 1.0.1. When upgrading to 1.0.1, you must, in addition to updating dependencies in the package.json file, do the following:

In the console, run the following command to create a template app:
RequestResponse
```
npx [email protected] nextjs
```
If you have not customized the src/middleware.ts file, replace it with the version in your template app.
If you have customized the src/middleware.ts file, make the following changes:
- Find the following import statement:
  RequestResponse
  import { type NextRequest, type NextFetchEvent } from 'next/server';
- Update it with the following:
  RequestResponse
  import { type NextRequest, type NextFetchEvent, NextResponse } from 'next/server';
- At the beginning of the middleware() function, add the following:
  RequestResponse
  if (!scConfig.api?.edge?.contextId) { return NextResponse.next(); }
  This allows the middleware logic to be skipped when running locally or without Edge context.
- Shift the creation of multisite, redirects, and personalize middlewares after the above if statement. This avoids running constructors when they’re not needed.
Ensure you've updated every @sitecore-content-sdk package to version 1.0.1 in the package.json file.
Install the dependencies with the following command:
RequestResponse
```
npm install
```

Next steps

To finalize the upgrade process, make sure you resolve any errors and warnings you encounter. Enable debug logging for Content SDK specific issues to assist you if necessary.

Do you have some feedback for us?

If you have suggestions for improving this article,