---
title: "Upgrade Content SDK 1.5.1 Next.js apps to version 2.0"
slug: "upgrade-content-sdk-1-5-1-next-js-apps-to-version-2-0"
abstract: "How to upgrade your Content SDK 1.5.1 Next.js apps to version 2.0.0 to get the latest features like Next.js 16, Node.js 24, tracking, events, personalization, and more."
---
# Upgrade Content SDK 1.5.1 Next.js apps to version 2.0

This guide covers most of the changes you must make to your existing Content SDK 1.5.1 applications to take advantage of the new features and improvements in version 2.0.0. However, because this process also involves updating Next.js to version 16 and Node.js to version 24, you'll need to refer to the relevant guides for each framework to complete the upgrade process for your apps.

This version of the Content SDK introduces tracking, events, and personalization capabilities, custom query parameters in editing render handlers, custom hostname support, and more.

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**
> -   Familiarize yourself with the [changelog](https://github.com/Sitecore/content-sdk/blob/dev/CHANGELOG.md#200). 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/20/upgrade-content-sdk-1-5-1-next-js-apps-to-version-2-0.html#update-application-dependencies-in-your-existing-app)
2. [Create a template 2.0.0 Content SDK application for Next.js](https://doc.sitecore.com/sai/en/developers/content-sdk/20/upgrade-content-sdk-1-5-1-next-js-apps-to-version-2-0.html#create-a-template-200-content-sdk-application-for-nextjs)
3. [Update your existing app](https://doc.sitecore.com/sai/en/developers/content-sdk/20/upgrade-content-sdk-1-5-1-next-js-apps-to-version-2-0.html#update-your-existing-app)
:::

## 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 `2.0.0`.
2. Update the following dependencies to the specified versions:
    - Node.js has been updated to version 24. You may need to apply changes not mentioned here to your app based on the [Node 24 upgrade guide](https://nodejs.org/en/blog/migrations/v22-to-v24).

        ```json
        "@types/node": "^24.10.4",
        ```

    - Next.js has been updated to version 16. See the [Upgrade Next.js to version 16](https://doc.sitecore.com/sai/en/developers/content-sdk/20/upgrade-content-sdk-1-5-1-next-js-apps-to-version-2-0.html#UUID-4685522c-3a1c-eaa5-6825-f6b0cafa83b2_section-id235461058472189 "Upgrade Next.js to version 16") section for further steps to complete the update:

        ```json
        "next": "^16.1.1",
        ```

    - Remove any dependencies that start with `@sitecore-cloudsdk/` and add the following:

        ```json
        "@sitecore-content-sdk/analytics-core": "^2.0.0",
        "@sitecore-content-sdk/personalize": "^2.0.0",
        "@sitecore-content-sdk/events": " ^2.0.0",
        ```

        See the [Cloud SDK integration](https://doc.sitecore.com/sai/en/developers/content-sdk/20/upgrade-content-sdk-1-5-1-next-js-apps-to-version-2-0.html#UUID-4685522c-3a1c-eaa5-6825-f6b0cafa83b2_section-id235473551736624 "Cloud SDK integration") section for further steps to complete the update.

3. Install the dependencies with the following command:

    ```shell
    npm install
    ```

## Create a template 2.0.0 Content SDK application for Next.js

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

To create a 2.0.0 Content SDK Next.js application:

1. In a console, run the following command:

    ```shell
    npx create-content-sdk-app@2.0.1
    ```

2. If prompted to install the `create-content-sdk-app@2.0.0` package, answer `y`.
3. When prompted, choose the same template as your existing app (`nextjs` for Pages Router and `nextjs-app-router` for App Router).
4. Enter the folder path for the new app. For example, enter `./content-sdk-200`, to create the app folder in your current working directory.
5. 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 your existing app

After updating your dependencies, you must synchronize files in your existing application. The following sections contains steps to complete the Next.js 16 upgrade, Cloud SDK integration, React 19 refactor, and updating other template files.

### Upgrade Next.js to version 16

The Content SDK uses Next.js 16 starting from version 2.0. The following section describes the updates you must make for your app to work with Next.js 16:

1. Middleware has been [renamed to proxy](https://nextjs.org/docs/app/getting-started/proxy) to better reflect its purpose. Rename `middleware.ts` to `proxy.ts` or copy it from the template app. Instead of Next.js discovering your middleware automatically by filename, it now runs the `proxy.ts` file directly. To update your implementation:
    - Create `src/proxy.ts` or rename your current `middleware.ts` file to `proxy.ts`. Add your proxy logic here. The file must export a single function (default export or named `proxy`) that accepts a `NextRequest` and returns the result of the proxy chain as shown:

        ```csharp
        export default function proxy(req: NextRequest) {
          // ... create locale, multisite, redirects, personalize instances ...
          return defineProxy(locale, multisite, redirects, personalize).exec(req);
        }
        export const config = { matcher: [...] };
        ```

    - Ensure that your proxy order is correct:
        - For Next.js apps using App Router - locale → multisite → redirects → personalize
        - For Next.js apps using Pages Router - multisite → redirects → personalize
    - When renaming your current `middleware.ts` file, you must replace the following import statements:

        ```javascript
        import {
        defineMiddleware,
        MultisiteMiddleware,
        AppRouterMultisiteMiddleware,
        PersonalizeMiddleware,
        RedirectsMiddleware,
        LocaleMiddleware, } from '@sitecore-content-sdk/nextjs/middleware';
        ```

    - Replace it with the following:

        ```javascript
        import {
        defineProxy,
        MultisiteProxy,
        AppRouterMultisiteProxy,
        PersonalizeProxy,
        RedirectsProxy,
        LocaleProxy, } from '@sitecore-content-sdk/nextjs/proxy';
        ```

        Ensure that you use the updated names in the initialization logic.

2. 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.

    <table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Item</p></th><th class="th"><p>Description</p></th></tr></thead><tbody><tr><td class="td"><p>For sitemap and robots.txt</p></td><td class="td"><p>Use <code class="code">SitemapMiddleware</code> or <code class="code">RobotsMiddleware</code> from <code class="code">@sitecore-content-sdk/nextjs/middleware</code></p></td></tr><tr><td class="td"><p>Editing APIs</p></td><td class="td"><p>Use <code class="code">EditingConfigMiddleware</code>, <code class="code">EditingRenderMiddleware</code>, or <code class="code">FEAASRenderMiddleware</code> from <code class="code">@sitecore-content-sdk/nextjs/editing</code></p></td></tr><tr><td class="td"><p>Healthcheck</p></td><td class="td"><p>Use the <code class="code">HealthcheckMiddleware</code> from <code class="code">@sitecore-content-sdk/nextjs/monitoring</code></p></td></tr></tbody></table>

3. Next.js 16 expects you to define allowed external image sources using `remotePatterns` instead of `images.domains`. Remove all entries of `images.domains` and use `remotePatterns` to allow Sitecore/media image URLs. You can refer the template app's `next.config.js|ts` file for more information.

> [!important]
> Please refer to the official [Next.js 16 upgrade guide](https://nextjs.org/docs/app/guides/upgrading/version-16) to update other parts of your application that's not specific to the Content SDK.

### Cloud SDK integration

The Content SDK has undergone a major architectural transformation to include functionality from the Cloud SDK. The Content SDK now includes tracking, events, and personalization.

To enable these changes:

1. In `Bootstrap.tsx`:
    - Find the CloudSDK initialization logic:

        ```csharp
        CloudSDK({
          sitecoreEdgeUrl: config.api.edge.edgeUrl,
          sitecoreEdgeContextId: config.api.edge.clientContextId,
          siteName: page.siteName || config.defaultSite,
          enableBrowserCookie: true,
          // Replace with the top level cookie domain of the website that is being integrated e.g ".example.com" and not "www.example.com"
          cookieDomain: window.location.hostname.replace(/^www\./, ''),
        })
          .addEvents()
          .initialize();
        ```

    - Replace it with the following:

        ```csharp
        initContentSdk({
          config: {
            contextId: config.api.edge.clientContextId,
            edgeUrl: config.api.edge.edgeUrl,
            siteName: page.siteName || config.defaultSite,
          },
          plugins: [
            analyticsPlugin({
              options: {
                enableCookie: true,
                cookieDomain: window.location.hostname.replace(/^www\./, ''),
              },
              adapter: analyticsBrowserAdapter(),
            }),
            eventsPlugin(),
          ],
        });
        ```

    - Remove the following imports:

        ```javascript
        import { CloudSDK } from '@sitecore-cloudsdk/core/browser';
        import { SitecorePageProps } from '@sitecore-content-sdk/nextjs';
        import '@sitecore-cloudsdk/events/browser';
        ```

    - Add the following imports:

        ```javascript
        import { SitecorePageProps, initContentSdk } from '@sitecore-content-sdk/nextjs';
        import { eventsPlugin } from '@sitecore-content-sdk/events';
        import { analyticsBrowserAdapter, analyticsPlugin } from '@sitecore-content-sdk/analytics-core';
        ```

2. In `CdpPageView.tsx`:
    - Find the following import:

        ```text
        import { pageView } from '@sitecore-cloudsdk/events/browser';
        ```

    - Replace it with the following:

        ```text
        import { pageView } from '@sitecore-content-sdk/events';
        ```

You might also have to make further changes to other files that contains older Cloud SDK logic based on your implementation. See [Initializing tracking, events, and personalization in the Content SDK](https://doc.sitecore.com/sai/en/developers/content-sdk/20/initializing-tracking,-events,-and-personalization-in-the-content-sdk.md "Initializing tracking, events, and personalization in the Content SDK") for more information.

### Refactor aligned with React 19 best practices

React logic in the Content SDK has been refactored to follow React 19 best practices. The following section outlines the breaking changes introduced by this refactor and provides examples of the new implementations.

1. The `@sitecore-content-sdk/react` package introduces the following updated types and signatures:
    - `useSitecore(options?: UseSitecoreOptions): SitecoreProviderState`
    - `SitecoreProviderState` now includes:
        - `page: Page`
        - `api?: SitecoreProviderProps['api']`
        - `setPage?: (value: Page) => void` (renamed from updatePage)
        - `componentMap: ComponentMap` (new)
        - `loadImportMap: () => Promise<ImportMapImport>` (new)
    - `PlaceholderProps` is expanded to explicitly list all supported properties:

        ```csharp
        export interface PlaceholderProps {
          name: string;
          rendering: ComponentRendering | RouteData;
          componentMap?: ComponentMap;
          page?: Page;
          fields?: { [name: string]: Field | Item | Item[] };
          params?: { [name: string]: string };
          disableSuspense?: boolean;
          errorComponent?: React.ComponentClass<ErrorComponentProps> | React.FC<ErrorComponentProps>;
          hiddenRenderingComponent?: React.ComponentClass | React.FC;
          missingComponentComponent?: React.ComponentClass | React.FC;
          componentLoadingMessage?: string;
          renderEmpty?: (components: React.ReactNode[]) => React.ReactNode;
          renderEach?: (component: React.ReactNode, index: number) => React.ReactNode;
          render?: (components: React.ReactNode[], data: ComponentRendering[], props: PlaceholderProps) => React.ReactNode;
          passThroughComponentProps?: { [key: string]: unknown };
        }
        ```

    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:

    - Review all imports and usages of `SitecoreProviderState` and `PlaceholderProps`.
    - If you relied on implicit properties, update your type annotations to the new explicit interface.
    - If you used `updatePage`, rename it to `setPage`.
    - If you previously inferred types from usage, consider importing the updated types from `@sitecore-content-sdk/react` to align with 2.0.

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

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

    To update your code:

    - Find implementations of a single placeholder:

        ```javascript
        import { withPlaceholder, PlaceholderProps } from '@sitecore-content-sdk/react';
        type HomeProps = PlaceholderProps;
        const Home: React.FC<HomeProps> = ({ pageContent }) => (
          <div className="home-mock">{pageContent}</div>
        );
        export default withPlaceholder('page-content')(Home);
        ```

    - Replace it with the following:

        ```csharp
        import { withPlaceholder } from '@sitecore-content-sdk/react';
        type HomeProps = {
          placeholders: Record<string, React.ReactNode>;
        };
        const Home: React.FC<HomeProps> = ({ placeholders }) => (
          <div className="home-mock">
            {placeholders['page-content']}
          </div>
        );
        export default withPlaceholder(Home);
        ```

        > [!note]
        > When rendering the wrapper on a server component in Next.js App Router while using `withAppPlaceholder`, you must still pass the `rendering`, `page`, and `componentMap` props:
        >
        > ```javascript
        > const WrappedHome = withAppPlaceholder(Home);
        > <SitecoreProvider page={page} componentMap={componentMap} api={api}>
        > <WrappedHome
        > rendering={page.layout.sitecore.route}
        > page={page}
        > componentMap={componentMap}
        > />
        > </SitecoreProvider>;
        > ```

    - If you rely on a multi-placeholder mapping as shown:

        ```csharp
        type HomeProps = PlaceholderProps & {
          subProp?: React.ReactElement;
        };
        const Home: React.FC<HomeProps> = ({ subProp, pageContent }) => (
          <div>
            <header>{subProp}</header>
            <main>{pageContent}</main>
          </div>
        );
        export default withPlaceholder(
          [
            { placeholder: 'page-header', prop: 'subProp' },
            'page-content',
          ]
        )(Home);
        ```

    - Convert it as shown:

        ```csharp
        type HomeProps = {
          placeholders: Record<string, React.ReactNode>;
        };
        const Home: React.FC<HomeProps> = ({ placeholders }) => (
          <div>
            <header>{placeholders['page-header']}</header>
            <main>{placeholders['page-content']}</main>
          </div>
        );
        export default withPlaceholder(Home);
        ```

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

    To update your code, find the current implementation:

    ```csharp
    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:

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

    > [!note]
    > If you continue using `withSitecore`, the `updatePage` prop it previously injected is now named `setPage`.

4. `Placeholder` and `AppPlaceholder` are stricter and now pass only the following props to the components rendered for a placeholder:
    - Context properties (`page`, `componentMap`)
    - `fields`, `params` and `rendering` data

        ```csharp
        fields: {
          [name: string]: Field<GenericFieldValue> | Item | Item[];
        };
        params: {
          [name: string]: string;
        };
        rendering: ComponentRendering;
        ```

    The `modifyComponentProps` callback is still available, but it should not be required for simple prop injection. For example, the following usage:

    ```csharp
    <AppPlaceholder
      name="main"
      rendering={route}
      componentMap={components}
      page={page}
      modifyComponentProps={(props) =>
        { ...props, extraDiv: true }
      }
    />
    ```

    Can be streamlined using `passThroughComponentProps` as shown:

    ```xml
    <AppPlaceholder
      name="main"
      rendering={route}
      componentMap={components}
      page={page}
      passThroughComponentProps={{ extraDiv: true }}
    />
    ```

5. 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](https://react.dev/reference/react/forwardRef) best practices.

> [!important]
> Please refer to the official [React 19 upgrade guide](https://react.dev/blog/2024/04/25/react-19-upgrade-guide) to update other parts of your application that's not specific to the Content SDK.

### Update Next.js template files

To update the Next.js template files:

1. In `sitecore.cli.config`:
    - Previously, all functions in the `build` array of the `defineCliConfig` options object accepted a `scConfig` property in their options object. This property is no longer required and is provided internally during build time. For example, the previous implementation for `writeImportMap` contained the `scConfig` property as shown:

        ```ts
        import scConfig from './sitecore.config';
        import { defineCliConfig } from '@sitecore-content-sdk/nextjs/config-cli';
        import {
          ...
          writeImportMap,
        } from '@sitecore-content-sdk/nextjs/tools';

        export default defineCliConfig({
          config: scConfig,
          build: {
            commands: [
              ...
              writeImportMap({
                scCofig: scConfig,
                paths: ['src/components'],
              }),
            ],
          },
          ...
        });
        ```

        The rest of the configuration remains the same after removing the property:

        ```ts
        import scConfig from './sitecore.config';
        import { defineCliConfig } from '@sitecore-content-sdk/nextjs/config-cli';
        import {
          ...
          writeImportMap,
        } from '@sitecore-content-sdk/nextjs/tools';

        export default defineCliConfig({
          config: scConfig,
          build: {
            commands: [
              ...
              writeImportMap({
                paths: ['src/components'],
              }),
            ],
          },
          ...
        });
        ```

2. The `renderEmptyPlaceholder` method from the `Placeholder` class has been removed.

    ```ts
    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.

    ```ts
    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();
      }
    }
    ```

3. 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:

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

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

    ```csharp
    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;
    ```

5. 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.
    - `NEXT_PUBLIC_SITECORE_EDGE_PLATFORM_HOSTNAME` - for Next.js projects so both server and client use the custom host.
    - `SITECORE_EDGE_PLATFORM_HOSTNAME` - non Next.js or server only

    > [!note]
    > The default value of `<https://edge-platform.sitecorecloud.io>` is used unless you use the new variables.

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

    ```text
    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.

    > [!note]
    > Newly scaffolded apps use `defineConfig({})` and get `edgeUrl` from the new environment variable automatically, so you might not have the `edgeUrl` section under `edge`.

6. A new configuration option, `rewriteMediaUrls` is available in `sitecore.config`.
    - When set to `true`, the SDK inspects media URLs in the layout that are pointing to the production Experience Edge host (`edge.sitecorecloud.io`), and rewrites those URLs to use your custom host defined in `SITECORE_EXPERIENCE_EDGE_HOSTNAME`. The rewrite only targets the production Experience Edge host.
    - You can also set its value to a function so that transformations occur depending on the function's logic. The function should match the following signature, where `s` is the image URL to be transformed and the return value is the transformed URL:

        `transformer(s: string) => string`

        The following example shows the default transformer function modified slightly:

        ```ts
        function rewriteEdgeHostInString(str: string): string {
          const customEdgeUrl = 'my-custom.com';
          const EDGE_HOST_PATTERN = new RegExp(
            `custom-matcher-here`,
            'gi'
          );
          return str.replace(EDGE_HOST_PATTERN, customEdgeUrl);
        }
        ```

7. 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:
    - Audit `<Placeholder>` usages where dynamic or lazy components are rendered.
    - Add `disableSuspense={false}` to any placeholder that depends on Suspense-based loading states.
8. This release also fixed an issue where the not-found page was accidentally forcing the entire route to use dynamic rendering instead of Static Site Generation (SSG). In Next.js, when you call `headers()` in a component, it forces that route to use dynamic rendering instead of static rendering. This means the page gets rendered on every request rather than being pre-generated at build time, which is much slower. The fix introduces a caching mechanism to avoid using `headers()`.

    To add it to your existing app:

    - Create a file called `layout.tsx` inside the `src/app/[site]/[locale]/[[...path]]` folder with the following:

        ```ts
        import { setCachedPageParams } from '@sitecore-content-sdk/nextjs';

        export default async function SiteLayout({
          children,
          params,
        }: {
          children: React.ReactNode;
          params: Promise<{ site: string; locale: string }>;
        }) {
          const { site, locale } = await params;

          // Update the cached page info with the current site and locale values.
          // This ensures the notFound page can access the correct site and locale information when rendered
          // without opting out of SSG by using functions like `headers()`.
          setCachedPageParams({ locale, site });

          return <>{children}</>;
        }
        ```

    - In your existing `/src/app/[site]/[locale]/[[..path]]/not-found.tsx` file, replace the existing contents with the following:

        ```ts
        import Link from 'next/link';
        import { ErrorPage, getCachedPageParams } from '@sitecore-content-sdk/nextjs';
        import client from 'lib/sitecore-client';
        import scConfig from 'sitecore.config';
        import Layout from 'src/Layout';
        import Providers from 'src/Providers';
        import { NextIntlClientProvider } from 'next-intl';

        export default async function NotFound() {
          const { site, locale } = getCachedPageParams();

          const page = await client.getErrorPage(ErrorPage.NotFound, {
            site: site || scConfig.defaultSite,
            locale: locale || scConfig.defaultLanguage,
          });

          if (page) {
            return (
              <NextIntlClientProvider>
                <Providers page={page}>
                  <Layout page={page} />
                </Providers>
              </NextIntlClientProvider>
            );
          }

          return (
            <div style={{ padding: 10 }}>
              <h1>Page not found</h1>
              <p>This page does not exist.</p>
              <Link href="/">Go to the Home page</Link>
            </div>
          );
        }
        ```

9. 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`.
    - The following submodules have been moved from `@sitecore-content-sdk/core` to `@sitecore-content-sdk/content`:

        <table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Submodule</p></th><th class="th"><p>Old path</p></th><th class="th"><p>New path</p></th></tr></thead><tbody><tr><td class="td"><p><code class="code">client</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/core/client</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/content/client</code></p></td></tr><tr><td class="td"><p><code class="code">codegen</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/core/codegen</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/content/codegen</code></p></td></tr><tr><td class="td"><p><code class="code">config-cli</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/core/config-cli</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/content/config-cli</code></p></td></tr><tr><td class="td"><p><code class="code">config</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/core/config</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/content/config</code></p></td></tr><tr><td class="td"><p><code class="code">editing</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/core/editing</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/content/editing</code></p></td></tr><tr><td class="td"><p><code class="code">i18n</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/core/i18n</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/content/i18n</code></p></td></tr><tr><td class="td"><p><code class="code">layout</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/core/layout</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/content/layout</code></p></td></tr><tr><td class="td"><p><code class="code">media</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/core/media</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/content/media</code></p></td></tr><tr><td class="td"><p><code class="code">personalize</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/core/personalize</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/content/personalize</code></p></td></tr><tr><td class="td"><p><code class="code">site</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/core/site</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/content/site</code></p></td></tr></tbody></table>

        Update all references to the old paths with the new ones.

    - All exports from the `utils` submodule are now available from the `tools` submodule. Update all references to the `@sitecore-content-sdk/core/utils` submodule and replace it with `@sitecore-content-sdk/core/tools`.
    - The following types and functions have been moved from `@sitecore-content-sdk/core` to `@sitecore-content-sdk/content`:

        <table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Item</p></th><th class="th"><p>Old path</p></th><th class="th"><p>New path</p></th></tr></thead><tbody><tr><td class="td"><p><code class="code">HTMLLink</code> type</p></td><td class="td"><p><code class="code">@sitecore-content-sdk/core</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/content</code></p></td></tr><tr><td class="td"><p><code class="code">StaticPath</code> type</p></td><td class="td"><p><code class="code">@sitecore-content-sdk/core</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/content</code></p></td></tr><tr><td class="td"><p><code class="code">defineConfig</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/core</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/content</code></p></td></tr><tr><td class="td"><p><code class="code">form</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/core</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/content</code></p></td></tr></tbody></table>

        Update all references to the old paths with the new ones.

    - The following tools have been moved from `@sitecore-content-sdk/core/tools` to `@sitecore-content-sdk/content/tools`:

        <table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Item</p></th><th class="th"><p>Old path</p></th><th class="th"><p>New path</p></th></tr></thead><tbody><tr><td class="td"><p><code class="code">generateSites</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/core/tools</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/content/tools</code></p></td></tr><tr><td class="td"><p><code class="code">GenerateSitesConfig</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/core/tools</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/content/tools</code></p></td></tr><tr><td class="td"><p><code class="code">GenerateMapFunction</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/core/tools</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/content/tools</code></p></td></tr><tr><td class="td"><p><code class="code">GenerateMapArgs</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/core/tools</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/content/tools</code></p></td></tr><tr><td class="td"><p><code class="code">extractFiles</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/core/tools</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/content/tools</code></p></td></tr><tr><td class="td"><p><code class="code">writeImportMap</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/core/tools</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/content/tools</code></p></td></tr><tr><td class="td"><p><code class="code">WriteImportMapArgs</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/core/tools</code></p></td><td class="td"><p><code class="code">@sitecore-content-sdk/content/tools</code></p></td></tr></tbody></table>

        Update all references to the old paths with the new ones.

    - The following utilities and types have been removed from `@sitecore-content-sdk/core/tools` as they are no longer relevant or unused:

        <table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Item</p></th><th class="th"><p>Description</p></th></tr></thead><tbody><tr><td class="td"><p><code class="code">generatePlugins</code></p></td><td class="td"><p>No longer relevant</p></td></tr><tr><td class="td"><p><code class="code">PluginDefinition</code></p></td><td class="td"><p>No longer relevant</p></td></tr><tr><td class="td"><p><code class="code">ModuleType</code></p></td><td class="td"><p>No longer relevant</p></td></tr><tr><td class="td"><p><code class="code">tryParseEnvValue</code></p></td><td class="td"><p>Unused utility</p></td></tr><tr><td class="td"><p><code class="code">isAbsoluteUrl</code></p></td><td class="td"><p>Unused utility</p></td></tr></tbody></table>

> [!important]
> The default SXA rewrite logic has been changed to align with Next.js best practices for locale and to support the optional **Shall language be preserved upon redirect?** checkbox introduced in the Redirect Rules section in SitecoreAI. For example, earlier, when `en` is set as the default locale, URLs that do not specify a locale (like `/my-page`) resolves to that default locale. With this change, the same rule results in a redirect without the default locale if no locale is present. To continue using it as before, you must enable the **Shall language be preserved upon redirect?**.

## 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/debug-logging-in-content-sdk-apps.html) 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.