Upgrade Content SDK 1.1.0 Next.js apps to version 1.2.0

This guide covers the required changes you must make to your existing Content SDK 1.1.0 applications to take advantage of the new features and improvements in version 1.2.0. Content SDK 1.2 includes the beta release of Next.js App Router, new AI guidance files for improved development support, and several other improvements and bug fixes.

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 app to a Content SDK 1.1 app and then follow this topic.
Review 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 must update dependencies.

To update your dependencies:

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

Important

If you want to migrate from Pages Router to the newly released App Router, follow this guide.

Update the Next.js template files in your existing app

After updating your dependencies, you must synchronize files in your existing application. These steps are not mandatory for this upgrade but recommended for future releases.

To update the Next.js template files:

Replace the contents of sitecore.cli.config.ts with the following:

RequestResponse

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

export default defineCliConfig({
  config: scConfig,
  build: {
    commands: [
      generateMetadata(),
      generateSites(),
      extractFiles(),
      writeImportMap({
        paths: ['src/components'],
      }),
    ],
  },
  componentMap: {
    paths: ['src/components'],
    // Exclude content-sdk auxiliary components
    exclude: ['src/components/content-sdk/*'],
  },
});

The sitecore.cli.config.ts interface has been improved to simplify configuration management. The scConfig object, which had to be manually passed to every CLI command, can now be defined once in the CLI configuration file's new config property, which is then shared automatically across all commands.

Custom build commands can now receive scConfig via the command’s argument instead of a manual import or direct variable reference.

For example, consider the following sample build command:

RequestResponse

import { defineCliConfig } from '@sitecore-content-sdk/nextjs/config-cli';
import {
  generateSites,
  generateMetadata,
  extractFiles,
  writeImportMap,
} from '@sitecore-content-sdk/nextjs/tools';
import config from './sitecore.config';

const logger = (title: string) => {
  return async () => {
    console.log(title);
  };
};

export default defineCliConfig({
  build: {
    commands: [
      ...
      logger('This is my logger'),
    ],
  },
  ...
});

You can replace it with the following:

RequestResponse

import { defineCliConfig } from '@sitecore-content-sdk/nextjs/config-cli';
import { SitecoreConfig } from '@sitecore-content-sdk/nextjs/config';
import config from './sitecore.config';

const logger = (title: string) => {
  return async ({ scConfig }: { scConfig: SitecoreConfig }) => {
    console.log(title, scConfig.defaultSite);
  };
};

export default defineCliConfig({
  config,
  build: {
    commands: [
      ...
      logger('This is my logger'),
    ],
  },
  ...
});

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,