--- title: "Upgrade Content SDK 0.1.0 Next.js apps to version 0.2.0" slug: "upgrade-content-sdk-0-1-0-next-js-apps-to-version-0-2-0" abstract: "How to upgrade your Content SDK 0.1.0 Next.js apps to version 0.2.0 to get the latest features. This involves updating React to version 19 and Next.js to version 15." --- # 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](https://react.dev/blog/2024/04/25/react-19-upgrade-guide) and [Next.js to version 15](https://nextjs.org/docs/app/guides/upgrading/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](https://doc.sitecore.com/sai/en/developers/content-sdk/10/the-sitecore-configuration-file.html "The Sitecore configuration file") 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](https://doc.sitecore.com/sai/en/developers/content-sdk/10/upgrade-content-sdk-0-1-0-next-js-apps-to-version-0-2-0.html#UUID-94fd3470-841f-fe0f-4c80-24af86a2aa23_section-idm4620167227648034120210091693 "Create a template 0.2.0 Content SDK application for Next.js"), 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. > [!note] > **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](https://github.com/Sitecore/content-sdk/releases/tag/v0.2.0). 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. [Update application dependencies in your existing app](https://doc.sitecore.com/sai/en/developers/content-sdk/10/upgrade-content-sdk-0-1-0-next-js-apps-to-version-0-2-0.html#update-application-dependencies-in-your-existing-app) 2. [Create a template 0.2.0 Content SDK application for Next.js](https://doc.sitecore.com/sai/en/developers/content-sdk/10/upgrade-content-sdk-0-1-0-next-js-apps-to-version-0-2-0.html#create-a-template-020-content-sdk-application-for-nextjs) 3. [Update the Next.js template files in your existing app](https://doc.sitecore.com/sai/en/developers/content-sdk/10/upgrade-content-sdk-0-1-0-next-js-apps-to-version-0-2-0.html#update-the-nextjs-template-files-in-your-existing-app) ::: ## Update application dependencies in your existing app 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 every `@sitecore-content-sdk` package to version `0.2.0`. - Update the following packages to the specified versions: ```json "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" ``` 2. Install the dependencies with the following command: ```shell 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: 1. In a console, run the following command: ```shell npx @sitecore-content-sdk/create-sitecore-jss@0.2.0 nextjs ``` 2. If prompted to install the `@sitecore-content-sdk/create-sitecore-jss@0.2.0` package, answer *y*. 3. Enter the folder path for the new app. For example, enter `*./content-sdk-020*`, 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. > [!note] > **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: 1. In any file that imports form utilities from `@sitecore-content-sdk/core/form`, amend the import statement to use `@sitecore-content-sdk/core` instead. 2. 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: ```javascript sassOptions: { ... quietDeps: true, silenceDeprecations: ["import", "legacy-js-api"], }, ``` 3. 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: ```typescript import { useEffect } from 'react'; ``` - In which case, add `JSX` to create the following: ```typescript import { useEffect, JSX } from 'react'; ``` 4. 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: ```typescript 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](https://doc.sitecore.com/sai/en/developers/content-sdk/10/the-sitecore-configuration-file.html "The Sitecore configuration file") 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. 5. 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: ```scss padding-left: $default-padding / 2; padding-right: $default-padding / 2; ``` - Replace those rules with the following: ```scss padding-left: $default-padding * 0.5; padding-right: $default-padding * 0.5; ``` 6. 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: ```typescript import { createGraphQLClientFactory } from '@sitecore-content-sdk/nextjs/client'; ``` - Assignments such as this: ```typescript const clientFactory = createGraphQLClientFactory({ api: scConfig.api }); ``` - Any usage in the `personalize` and `redirects` middleware constructors. 7. Replace your existing app's `src/pages/api/robots.ts` file with the version in your template app. 8. 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: ```typescript if (process.env.DISABLE_SSG_FETCH?.toLowerCase() !== 'true') { ... } ``` - Replace it as follows: ```typescript if (!scConfig.disableStaticPaths) { ... } ``` 9. 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"

10. Use the framework-specific upgrade guides to make the necessary changes to your application for the latest versions: - [React 19 upgrade guide](https://react.dev/blog/2024/04/25/react-19-upgrade-guide) - [Next.js version 15 upgrade guide](https://nextjs.org/docs/app/guides/upgrading/version-15) > [!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](https://doc.sitecore.com/sai/en/developers/content-sdk/10/debug-logging-in-content-sdk-apps.html "Debug logging in Content SDK apps") for Content SDK 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.