Upgrade Content SDK 0.1.0 Next.js apps to version 0.2.0

This guide covers most of the changes you must make to your existing Content SDK 0.1.0 applications to take advantage of the improvements in version 0.2.0. However, because this process also involves updating React to version 19 and Next.js to version 15, you'll need to refer to the relevant guides for each framework to complete the upgrade process for your apps.

This version of Content SDK adds a new disableStaticPaths property to scConfig. As a result, you no longer need to directly refer to the process.env.DISABLE_SSG_FETCH variable.

It's now optional to pass a configuration object to the defineConfig function in the Sitecore config file. All required config properties that are not given values will now fetch values from corresponding environment variables or, if those variables are not defined, the properties will use their default values instead.

Tip

New 0.2.0 apps, such as the one we recommend you create as part of the upgrade process, include a sitecore.config.ts.example file that you can use to help you create and define your own app's config.

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.

Before you begin

If you have a JSS app that you want to convert into a Content SDK app, follow the migration guide before you upgrade the 0.1.0 app to 0.2.0.
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:

Update application dependencies in your existing app

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

To update your dependencies:

In your existing application's package.json file:

Update every @sitecore-content-sdk package to version 0.2.0.

Update the following packages to the specified versions:

RequestResponse

"next": "^15.3.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",
"typescript": "~5.7.3"

Install the dependencies with the following command:
RequestResponse
```
npm install
```

Create a template 0.2.0 Content SDK application for Next.js

To simplify the upgrade process as much as possible, create a Content SDK 0.2.0 Next.js application with the XM Cloud add-on. You can then copy some files from this app into your existing app.

To create a 0.2.0 Content SDK Next.js application with the XM Cloud add-on included:

In a console, run the following command:
RequestResponse
```
npx @sitecore-content-sdk/[email protected] nextjs
```
If prompted to install the @sitecore-content-sdk/[email protected] package, answer y.
Enter the folder path for the new app. For example, enter ./content-sdk-020, 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.

XM Cloud is now SitecoreAI

Some code examples, images, and UI labels may still use XM Cloud while engineering assets are being updated.

Update the Next.js template files in your existing app

This explains how to synchronize files in your existing application with corresponding files from your new Content SDK 0.2.0 template app.

To update the Next.js template files:

In any file that imports form utilities from @sitecore-content-sdk/core/form, amend the import statement to use @sitecore-content-sdk/core instead.
If you have not customized the next.config.js file, replace it with the version in your template app. Otherwise, add the following extra properties to your sassOptions configuration:
RequestResponse
```
sassOptions: {
  ...
  quietDeps: true,
  silenceDeprecations: ["import", "legacy-js-api"],
},
```
For every component that uses the JSX namespace (for example, if a JSX.Element type is present), add a JSX import from react.
- In the src/Bootstrap.tsx file, the existing react import might look like this:
  RequestResponse
  import { useEffect } from 'react';
- In which case, add JSX to create the following:
  RequestResponse
  import { useEffect, JSX } from 'react';
If you have not customized the sitecore.config.ts file, replace it with the version in your template app. Otherwise, do the following:
- Add a new empty export to the end of the file, as shown in the following example:
  RequestResponse
  export default defineConfig({ // Your existing export ... }); export default defineConfig();
  Tip
  
  The defineConfig included as part of earlier Content SDK versions is no longer required here because passing config properties is no longer mandatory. If any of these properties are not given explicit values, they will use the value of the corresponding environment variables or, if those are not defined, they will revert to default values.
- If your customizations affect your existing export statement and are still needed, make sure you implement equivalent customizations in the new, empty defineConfig function.
- Delete the old defineConfig export, leaving only the import statement, the new export statement, and your customizations.
If you have not customized the src/assets/sass/components/_component-column-splitter.scss file, replace it with the version in your template app. Otherwise, do the following:
- Locate the following padding rules:
  RequestResponse
  padding-left: $default-padding / 2; padding-right: $default-padding / 2;
- Replace those rules with the following:
  RequestResponse
  padding-left: $default-padding * 0.5; padding-right: $default-padding * 0.5;
If you have not customized the src/middleware.ts file, replace it with the version in your template app. Otherwise, delete all references to clientFactory. For example:
- Imports such as this:
  RequestResponse
  import { createGraphQLClientFactory } from '@sitecore-content-sdk/nextjs/client';
- Assignments such as this:
  RequestResponse
  const clientFactory = createGraphQLClientFactory({ api: scConfig.api });
- Any usage in the personalize and redirects middleware constructors.
Replace your existing app's src/pages/api/robots.ts file with the version in your template app.
In any file that directly references the process.env.DISABLE_SSG_FETCH environment variable, replace that reference to use the new scConfig.disableStaticPaths property instead.
- For example, in your [[...path]].tsx, 404.tsx, and 500.tsx files, locate the following condition:
  RequestResponse
  if (process.env.DISABLE_SSG_FETCH?.toLowerCase() !== 'true') { ... }
- Replace it as follows:
  RequestResponse
  if (!scConfig.disableStaticPaths) { ... }

In your app's package.json file, replace the following scripts with updated versions:

Existing script	Updated script
`"sitecore-tools:build": "sitecore-tools build",`	`"sitecore-tools:build": "sitecore-tools project build",`
`"start:connected": "cross-env NODE_ENV=development npm-run-all --serial sitecore-tools:build next:dev",`	`"dev": "cross-env NODE_ENV=development npm-run-all --serial sitecore-tools:build next:dev",`
`"start:production": "cross-env-shell NODE_ENV=production npm-run-all --serial build next:start"`	`"start": "cross-env-shell NODE_ENV=production npm-run-all --serial build next:start"`

Use the framework-specific upgrade guides to make the necessary changes to your application for the latest versions:
- React 19 upgrade guide
- Next.js version 15 upgrade guide
Tip

For any affected files that you've not customized in your existing app, you can save time by replacing them with the versions in your 0.2.0 template app.

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,