Upgrade Content SDK 1.2.0 Next.js apps to version 1.3.1

Version:

This guide covers the required changes you must make to your existing Content SDK 1.2.0 applications to take advantage of the new features and improvements in version 1.3.1. Content SDK 1.3.1 includes the general release of Next.js App Router and several other improvements and bug fixes. Note that version 1.3.0 was released and deprecated due to a critical vulnerability related to React Server Components.

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.9/22.10 app to a Content SDK 1.3.1 app instead of this topic.
Review the changelogs for 1.3.0 and 1.3.1. 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 must update dependencies.

To update your dependencies:

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

Update the Next.js template files in your existing app

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

Pages Router

To update the Next.js template files in your Content SDK Next.js Pages Router app, in your existing app's middleware.ts file:

Find the following:

if (!scConfig.api?.edge?.contextId) {
    return NextResponse.next();
  }

Replace it with the following:

if (!scConfig.api?.edge?.contextId && !scConfig.api?.local?.apiHost) {
    return NextResponse.next();
  }

Pass local configuration to the redirects middleware:

const redirects = new RedirectsMiddleware({
    /**
     * List of sites for site resolver to work with
     */
    sites,
    // this was present before:
    ...scConfig.api.edge,
    // this needs to be added:
    ...scConfig.api.local,
    ....
    ......

App Router

The editing config Router Handler has been updated to support component runtime information for compatibility with Sitecore Pages. Before this, the route handler only provided component names and metadata. Now, the Router Handler accepts an optional clientComponents parameter and returns additional information, including framework type and the client component list. This allows Pages to differentiate between server and client components, preventing invalid operations.

To update the Next.js template files in your Content SDK Next.js App Router app:

In your existing app's middleware.ts file:

Find the following:

if (!scConfig.api?.edge?.contextId) {
    return NextResponse.next();
  }

Replace it with the following:

if (!scConfig.api?.edge?.contextId && !scConfig.api?.local?.apiHost) {
    return NextResponse.next();
  }

Pass local configuration to the redirects middleware:

const redirects = new RedirectsMiddleware({
    /**
     * List of sites for site resolver to work with
     */
    sites,
    // this was present before:
    ...scConfig.api.edge,
    // this needs to be added:
    ...scConfig.api.local,
    ....
    ......

In your application's /api/editing/config/route.ts:

Add the following import:
import clientComponents from '.sitecore/component-map.client';

Pass clientComponents to the createEditingConfigRouteHandler:

export const { GET, OPTIONS } = createEditingConfigRouteHandler({
  components,
  clientComponents,
  metadata,
});

In src/Layout.tsx:

Remove the following import:
import { DesignLibraryLayout } from './DesignLibraryLayout';
Add the import for DesignLibraryApp to replace the earlier one for DesignLibraryLayout:
import { DesignLibraryApp } from "@sitecore-content-sdk/nextjs";
Remove the following usage of the DesignLibraryLayout:
{mode.isDesignLibrary ? ( <DesignLibraryLayout /> ) : (

Replace it with the following:

{mode.isDesignLibrary ? (
    route && (
      <DesignLibraryApp
        page={page}
        rendering={route}
        componentMap={componentMap}
        loadServerImportMap={() => import(".sitecore/import-map.server")}
      />
    )
  ) : (

Remove the DesignLibraryLayout.tsx file.

In src/Providers.tsx:

Pass the client import map inside SitecoreProvider so that it's available in context:

<SitecoreProvider
      api={scConfig.api}
      componentMap={components}
      page={page}
      loadImportMap={() => import('.sitecore/import-map.client')}
    >
      {children}
</SitecoreProvider>

In /src/app/api/editing/render/route.ts add POST to the exported handlers:
export const { GET, POST, OPTIONS } = createEditingRenderRouteHandlers({});

The middleware.ts file introduces a new callback function called extractGeoDataCb(). It runs on every request in the Edge middleware and provides geo location data that the PersonalizeMiddleware uses for personalization.

...  
  const personalize = new PersonalizeMiddleware({
    ...
    extractGeoDataCb: () => {
      return {
        city: 'Athens',
        country: 'Greece',
        region: 'Attica',
      };
    },
  });
...

It returns an object that contains the following properties:

city
country
region

You can implement the callback in the PersonalizeMiddleware configuration to extract or provide geo data on each request. Some of the common approaches include using a geo-IP service or extracting geolocation data from the request headers. You can also use static values like in the template middleware.ts file for testing.

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.

If you have suggestions for improving this article, let us know!