Upgrade JSS 22.0.0 Next.js apps to version 22.1

In your existing application's package.json file:

Install the dependencies with the following command:

npm install

We highly recommend you install version 0.32.6 of the sharp image processing library using the following command. This is to improve memory usage of the image optimization feature:

npm i [email protected]

In a console, run the following command:

npx [email protected] nextjs

If prompted to install the [email protected] package, answer y.

Enter the folder path for the JSS 22.1 Next.js app. For example, enter ./jss221, to create the app folder in your current working directory.

Follow the remaining prompts, selecting the same options for data fetching (GraphQL or REST) and prerendering (SSG or SSR) as in your existing application.

When asked if you are building for Sitecore XM Cloud, answer y to install the XM Cloud add-on.

Select other add-ons used by your existing application and press Enter.

If you have not customized the scripts/generate-config.ts file, replace it with the 22.1 version. Otherwise, modify your file as follows:

Here's an example of the updated assignment suitable for JSS 22.1:

configText += `config.${prop} = process.env.${constantCase(prop)} || '${config[prop]?.trim()}';\n`;

If you have not customized the lib/next-config/plugins/cors-header plugin, replace it with the 22.1 version. Otherwise, modify your file as follows:

Because ComponentConsumerProps has been removed, if you have any import statements that reference it, update them all to use WithSitecoreContextProps instead.

Because the resolvePageUrl function now accepts an object, and because serverUrl is now optional, the latter is omitted if the metadata edit mode for Pages is enabled. If you've customized the pages/api/editing/render.ts file and you currently pass the resolvePageUrl function into EditingRenderMiddleware, modify your file as follows:

If your app contains any references to the now-deprecated EditingComponentPlaceholder or the RenderingType enum, such as the following example in [[...path]].tsx, delete them:

import Layout from 'src/Layout';
import { RenderingType, EditingComponentPlaceholder } from '@sitecore-jss/sitecore-jss-nextjs';
...
const isComponentRendering =
  layoutData.sitecore.context.renderingType === RenderingType.Component;
...
{isComponentRendering ? (
  <EditingComponentPlaceholder rendering={layoutData.sitecore.route} />
) : (
  <Layout layoutData={layoutData} headLinks={headLinks} />
)}

If you use the next/image component (instead of built-in JSS components such as Image, Banner, and so on) to render Sitecore images, we recommend you configure it to conditionally disable Next.js image optimization in edit and preview modes.

The following example describes one way you can implement conditional optimization, involving fetching the page state and using it to dynamically initialize a prop named unoptimized:

If you have not customized the /src/Scripts.tsx file, replace it with the 22.1 version. Otherwise, modify it as follows:

Here's an example of the updated file suitable for JSS 22.1:

import { EditingScripts } from '@sitecore-jss/sitecore-jss-nextjs';

const Scripts = (): JSX.Element | null => (
  <>
    <EditingScripts />
    ...
  </>
);

If you have not customized the /src/lib/dictionary-service-factory.ts file, replace it with the 22.1 version. Otherwise, modify it as follows:

Here's an example of the updated initialization suitable for JSS 22.1:

new GraphQLDictionaryService({
  siteName,
  clientFactory,            
  ...
  useSiteQuery: true,
})

If you have not customized the /lib/page-props-factory/plugins/personalize.ts file, replace it with the 22.1 version. Otherwise, modify it as follows:

If you have not customized the /lib/page-props-factory/plugins/preview-mode.ts file, replace it with the 22.1 version. Otherwise, modify it as follows:

If you have not customized the lib/middleware/plugins/personalize.ts file, replace it with the 22.1 version. Otherwise, modify it as follows:

Here's an example of the updated constructor signature suitable for JSS 22.1:

this.personalizeMiddleware = new PersonalizeMiddleware({
  ...
  edgeConfig: {
    ...
  },
  scope: process.env.NEXT_PUBLIC_PERSONALIZE_SCOPE,
});

(Optional) Specify the edit mode used for Pages. If not specified, this is set to EditMode.Metadata by default.

To specify the edit mode, make the following changes to your \src\pages\api\editing\config.ts file:

Here's an example of the updated definition specifically using metadata, suitable for JSS 22.1:

const handler = new EditingConfigMiddleware({
  ...
  pagesEditMode: EditMode.Metadata,
}).getHandler();

Copy the lib/graphql-editing-service.ts file from your new 22.1 app into your existing app.

If you have not customized the lib/page-props-factory/plugins/preview-mode.ts file, replace it with the 22.1 version. Otherwise, modify it as follows:

For metadata-based editing in Pages, the field.editable property has been superseded by field.metadata. If you have any custom field components that refer to field.editable, you need to rework your custom code to replace those references.