--- title: "Upgrade Content SDK 0.3.0 Next.js apps to version 1.0.0" slug: "upgrade-content-sdk-0-3-0-next-js-apps-to-version-1-0-0" abstract: "How to upgrade your Content SDK 0.3.0 Next.js apps to version 1.0.0 to get the latest features like brand new site templates, simplified app creation, and more." --- # 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. > [!important] > **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](https://doc.sitecore.com/sai/en/developers/content-sdk/10/upgrade-jss-22-8-next-js-apps-to-content-sdk-1-0.html "Upgrade JSS 22.8 Next.js apps to Content SDK 1.0"), instead of this topic. > > - Familiarize yourself with the [changelog](https://github.com/Sitecore/content-sdk/blob/v1.0.0/CHANGELOG.md#100). 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: :::walkthrough 1. [Rename service classes](https://doc.sitecore.com/sai/en/developers/content-sdk/10/upgrade-content-sdk-0-3-0-next-js-apps-to-version-1-0-0.html#rename-service-classes) 2. [Update application dependencies in your existing app](https://doc.sitecore.com/sai/en/developers/content-sdk/10/upgrade-content-sdk-0-3-0-next-js-apps-to-version-1-0-0.html#update-application-dependencies-in-your-existing-app) 3. [Create a template 1.0.0 Content SDK application for Next.js](https://doc.sitecore.com/sai/en/developers/content-sdk/10/upgrade-content-sdk-0-3-0-next-js-apps-to-version-1-0-0.html#create-a-template-100-content-sdk-application-for-nextjs) 4. [Update the Next.js template files in your existing app](https://doc.sitecore.com/sai/en/developers/content-sdk/10/upgrade-content-sdk-0-3-0-next-js-apps-to-version-1-0-0.html#update-the-nextjs-template-files-in-your-existing-app) ::: ## 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: 1. 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

2. 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: 1. In your existing application's `package.json` file, update every `@sitecore-content-sdk` package to version `1.0.0`. 2. Install the dependencies with the following command: ```shell 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: 1. In a console, run the following command: ```shell npx create-content-sdk-app@1.0.0 nextjs ``` 2. If prompted to install the `create-content-sdk-app@1.0.0` package, answer `y`. 3. Enter the folder path for the new app. For example, enter `./content-sdk-100`, to create the app folder in your current working directory. 4. 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: 1. In `src/lib/sitecore-client.ts`: - Delete the following import: ```ts import sites from '.sitecore/sites.json'; ``` - Remove the `sites` reference from the `SitecoreClient` declaration. 2. 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`. 3. 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: ```ts import sites from '.sitecore/sites.json'; ``` - Find the following line: ```ts paths = await client.getPagePaths(context?.locales || []); ``` - Replace it with the following: ```ts paths = await client.getPagePaths( sites.map((site: SiteInfo) => site.name), context?.locales || [] ); ``` 4. `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: ```ts export const getStaticProps = () => { ... const page = await client.getPage(...); return { props: { ...page } } } ``` - Replace it with the following: ```ts 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. 5. 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: ```ts if (layoutData.sitecore.context.renderingType === RenderingType.Component) { ... } ``` - Replace it with the following: ```ts if (page.mode.isDesignLibrary) { ... } ``` If the rendering mode `isNormal`: - Find the following: ```ts if (pageState === LayoutServicePageState.Normal) { ... } ``` - Replace it with the following: ```ts if (page.mode.isNormal) { ... } ``` Lastly, if the rendering mode `isEditing` or `isPreview`: - Find the following: ```ts if (pageState === LayoutServicePageState.Edit || pageState === LayoutServicePageState.Preview) { ... } ``` - Replace it with the following: ```ts if (page.mode.isEditing || page.mode.isPreview) { ... } ``` 6. 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: ```ts 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: ```ts export const getStaticProps = () => { const page = await client.getErrorPage(ErrorPage.NotFound, { site, locale }); return { props: { page } } } ``` - Replace it with the following for a 500 page: ```ts export const getStaticProps = () => { const page = await client.getErrorPage(ErrorPage.InternalServerError, { site, locale }); return { props: { page } } } ``` 7. Update the `SitecoreProvider` component to use the new `page` prop instead of the `layout` prop. - Find the following: ```ts ... ``` - Replace it with the following: ```ts ... ``` 8. Remove the `SitecoreProviderPageContext` interface and any references to it. Use the `Page` interface from the `SitecoreClient` instead. 9. Remove the `NextjsPage` interface and any references to it. All page-generating methods now return a single `Page` type. 10. 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: ```ts import { useSitecore } from '@sitecore-content-sdk/nextjs' const { pageContext, updateContext } = useSitecore(); ``` - Replace it with the following: ```ts import { useSitecore } from '@sitecore-content-sdk/nextjs' const { page, updatePage } = useSitecore(); ``` For the `withSitecore()` higher-order component: - Find the following: ```ts import { withSitecore } from '@sitecore-content-sdk/nextjs' function MyComponent({ pageContext, updateContext }) {...} export default withSitecore(MyComponent); ``` - Replace it with the following: ```ts import { withSitecore } from '@sitecore-content-sdk/nextjs' function MyComponent({ page, updatePage }) {...} export default withSitecore(MyComponent); ``` 11. You must provide an additional `sites` parameter to the `RobotsMiddleware` constructor. In `src/pages/api/robots.ts`: - Add the following import: ```ts import sites from '.sitecore/sites.json'; ``` - Find the following line: ```ts const handler = new RobotsMiddleware(scClient).getHandler(); ``` - Replace it with the following: ```ts const handler = new RobotsMiddleware(scClient, sites).getHandler(); ``` 12. You must provide an additional `sites` parameter to the `SitemapMiddleware` constructor. In `src/pages/api/sitemap.ts`: - Add the following import: ```ts import sites from '.sitecore/sites.json'; ``` - Find the following line: ```ts const handler = new SitemapMiddleware(scClient).getHandler(); ``` - Replace it with the following: ```ts const handler = new SitemapMiddleware(scClient, sites).getHandler(); ``` 13. In `sitecore.cli.config.ts`: - Find the following import: ```ts import { generateSites, generateMetadata } from '@sitecore-content-sdk/nextjs/tools'; ``` - Replace it with the following: ```ts import { generateSites, generateMetadata, extractFiles } from '@sitecore-content-sdk/nextjs/tools'; ``` - Inside the `defineCliConfig` block, after `generateSites({...})`, add the following: ```ts 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: > > ```ts > 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](https://github.com/Sitecore/content-sdk/releases/tag/v1.0.1). When upgrading to 1.0.1, you must, in addition to updating dependencies in the `package.json` file, do the following: 1. In the console, run the following command to create a template app: ```text npx create-content-sdk-app@1.0.1 nextjs ``` 2. If you have not customized the `src/middleware.ts` file, replace it with the version in your template app. 3. If you have customized the `src/middleware.ts` file, make the following changes: - Find the following import statement: ```text import { type NextRequest, type NextFetchEvent } from 'next/server'; ``` - Update it with the following: ```text import { type NextRequest, type NextFetchEvent, NextResponse } from 'next/server'; ``` - At the beginning of the `middleware()` function, add the following: ```csharp 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. 4. Ensure you've updated every `@sitecore-content-sdk` package to version 1.0.1 in the `package.json` file. 5. Install the dependencies with the following command: ```text 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](https://doc.sitecore.com/sai/en/developers/content-sdk/10/debug-logging-in-content-sdk-apps.html "Debug logging in Content SDK apps") specific issues to assist you if necessary. > [!note] > **Web experiences and experiments** > If you use Sitecore Personalize web experiences or experiments, after upgrading the Content SDK, start or restart a single experience or experiment (or start a dummy one) in order to republish it and regenerate the `cloud-version.min.js` library. For instructions, see [Start an experience in Sitecore Personalize](https://doc.sitecore.com/personalize/en/users/sitecore-personalize/introduction-to-experiences/managing-experience-status-in-sitecore-personalize/start-an-experience-in-sitecore-personalize.html), or [Start an experiment in Sitecore Personalize](https://doc.sitecore.com/personalize/en/users/sitecore-personalize/introduction-to-experiments-in-sitecore-personalize/managing-experiment-status-in-sitecore-personalize/start-an-experiment-in-sitecore-personalize.html). [Pausing experiments](https://doc.sitecore.com/personalize/en/users/sitecore-personalize/introduction-to-experiments-in-sitecore-personalize/managing-experiment-status-in-sitecore-personalize/pause-an-experiment-in-sitecore-personalize.html) and [experiences](https://doc.sitecore.com/personalize/en/users/sitecore-personalize/introduction-to-experiences/managing-experience-status-in-sitecore-personalize/pause-an-experience-in-sitecore-personalize.html) and restarting them can invalidate test results.