Upgrade JSS 21.6.4 Next.js apps to version 21.7

Version: 21.7

The JavaScript Rendering SDKs (JSS) 21.7 uses Next.js 14, improved GraphQL retries, and the Site GraphQL query for retrieving site information.

The update involves changes to the environment variables, configuration objects, JSS packages, services, and dependencies.

This topic covers most of the changes you must make in your existing JSS 21.6.4 applications to take advantage of the new features. However, because of the nature of JavaScript and Next.js application development, this topic doesn't account for all the customization you might have in your existing application.

When performing the upgrade, consider the JSS templates and add-ons you used when creating your Next.js application. You can find them in your package.json file. For example, a JSS 21.6.4 application included in the XM Cloud starter foundation uses the following templates and add-ons:

  • nextjs 

  • nextjs-xmcloud 

  • nextjs-sxa 

  • nextjs-multisite 

Before you begin

This topic describes how to:

Update environment variables for your existing app

The GraphQL retry functionality is now enabled by default with three retries, while still allowing you to use default or custom retry strategies when fetching data from the Edge GraphQL endpoint.

To customize the global number of retries:

  • In the JSS application's .env file, update the value of the GRAPH_QL_SERVICE_RETRIES environment variable to the desired number or to 0 to disable retries.

You might need to restart the local application server for the environment variable changes to take effect.

Update application dependencies in your existing app

For your upgraded application to work correctly, you must also update dependencies.

To update your dependencies:

  1. In your existing application's package.json file, do the following:

    1. Update the Next.js version:

      RequestResponse
      "next": "^14.1.0",

    2. Update every @sitecore-jss package to version ~21.7.0.

    3. Update the package versions in devDependencies to the new versions, as follows:

      RequestResponse
      "@graphql-codegen/cli": "^5.0.0",
"@graphql-codegen/import-types-preset": "^3.0.0",
"@graphql-codegen/plugin-helpers": "^5.0.1",
"@graphql-codegen/typed-document-node": "^5.0.1",
"@graphql-codegen/typescript": "^4.0.1",
"@graphql-codegen/typescript-operations": "^4.0.1",
"@graphql-codegen/typescript-resolvers": "^4.0.1",
"@graphql-typed-document-node/core": "^3.2.0",

    4. If you don't use the XM Cloud add-on, remove the following dependencies:

      RequestResponse
      "@sitecore-feaas/clientside": "^0.5.5",
"@sitecore/components": "~1.0.19",

    5. If you use the XM Cloud add-on, update these packages to new versions, as follows:

      RequestResponse
      "@sitecore/components": "^1.1.10",
"@sitecore-cloudsdk/events": "^0.2.4",
"@sitecore-feaas/clientside": "^0.5.17"

  2. Install the dependencies with the following command:

    RequestResponse
    npm install

  3. Perform any Next.js specific upgrades using the Next.js 14 upgrade guide. If necessary, use the provided codemods to complete the Next.js upgrade.

    Important

    You will need to check that version 14 of Next.js has been installed, and adjust your installation if necessary. Version 15 is not compatible with JSS 21.7.

Create a JSS 21.7 Next.js application

To simplify the upgrade process as much as possible, you must first create a JSS 21.7 Next.js application with the XM Cloud add-on. You will need to copy some files from this app into your existing app.

To create a JSS 21.7 Next.js application with the XM Cloud add-on included:

  1. In a console, run the following command:

    RequestResponse
    npx create-sitecore-jss@^21.7.0 nextjs

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

  3. Enter the folder path for the JSS 21.7 Next.js app. For example, ./jss217, to create the app folder in your current working directory.

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

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

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

The script then installs the application dependencies.

Update the Next.js template files in your existing app

In this procedure, you will synchronize files in your existing applications with corresponding files for the JSS 21.7 app.

To update the Next.js template files:

  1. Copy the the /scripts/generate-metadata.ts file from the 21.7 app to your existing app.

  2. Copy the src/lib/next-config/plugins/component-props.js file from the 21.7 app to your existing app.

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

    1. Locate the retries option in the GraphQLDictionaryService constructor options:

      RequestResponse
        retries:
    (process.env.GRAPH_QL_SERVICE_RETRIES && 
     parseInt(process.env.GRAPH_QL_SERVICE_RETRIES, 10)) ||
    0,

    2. Replace that code block with the following:

      RequestResponse
        retries:
    (process.env.GRAPH_QL_SERVICE_RETRIES &&
     parseInt(process.env.GRAPH_QL_SERVICE_RETRIES, 10)) as number,

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

    1. Locate the retries option in the GraphQLLayoutService constructor options:

      RequestResponse
        retries:
    (process.env.GRAPH_QL_SERVICE_RETRIES && 
     parseInt(process.env.GRAPH_QL_SERVICE_RETRIES, 10)) ||
    0,

    2. Replace that code block with the following:

      RequestResponse
        retries:
    (process.env.GRAPH_QL_SERVICE_RETRIES &&
     parseInt(process.env.GRAPH_QL_SERVICE_RETRIES, 10)) as number,

  5. In /scripts/fetch-graphql-introspection-data.ts, do the following:

    1. Locate the following import statement:

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

    2. Replace that statement with the following:

      RequestResponse
      import { GraphQLRequestClient } from '@sitecore-jss/sitecore-jss-nextjs/graphql';

  6. Add the following import statement to /scripts/bootstrap.ts:

    RequestResponse
    import './generate-metadata';

Update the XM Cloud add-on

Updating the XM Cloud add-on requires you update some package dependencies, and replace or update some of the files in your existing application.

To update the XM Cloud add-on:

  1. Replace the /src/lib/page-props-factory/plugins/feaas-themes.ts file with the /src/lib/page-props-factory/plugins/component-themes.ts file from the 21.7 application.

  2. Replace the /src/lib/page-props-factory/plugins/content-styles.ts file with the 21.7 version.

  3. Copy the following files from the 21.7 application into your existing app:

    • /src/components/FEAASScripts.tsx 

    • /src/pages/api/editing/config.ts 

    • src/pages/api/editing/feaas/render.ts 

    • src/pages/feaas/render.tsx 

  4. In the /src/middleware.ts file, update the matcher pattern to include feaas-render.

  5. In the src/Scripts.tsx file:

    1. Import the FEEASScripts component:

      RequestResponse
      import FEAASScripts from 'components/FEAASScripts';

    2. Add the FEEASScripts component after existing components:

      RequestResponse
      <BYOC />
<CdpPageView />
<FEAASScripts />

Update SXA add-on

To upgrade the SXA add-on:

  1. Replace the following files with the 21.7 version:

    • src/assets/basic/_container.scss 

    • src/assets/sass/_app.scss 

  2. Update the /src/components/Image.tsx as follows:

    1. Import the CSSProperties type from the react package:

      RequestResponse
      import React, { CSSProperties } from 'react';

    2. Update the backgroundStyle constant definition to:

      RequestResponse
      const backgroundStyle = (props?.fields?.Image?.value?.src && {
  backgroundImage: `url('${props.fields.Image.value.src}')`,
}) as CSSProperties;

Update the Multisite add-on

XM Cloud deployments use the GraphQL Site query to fetch site information. This query takes the values valid for the environment when resolving available sites in a multisite environment.

The Multisite add-on has been updated to support the Site query.

To update the Multisite add-on:

  • In the /scripts/config/plugins/multisite.ts, update the GraphQLSiteInfoService constructor call options to include the useSiteQuery option with a true value:

    RequestResponse
    const siteInfoService = new GraphQLSiteInfoService({
  clientFactory: createGraphQLClientFactory(config),
  // enable site query for the service. Only works on XMCloud currently
  useSiteQuery: true,
});

Next steps

To finalize the upgrade process, make sure you resolve any errors and warnings you encounter. Enable debug logging for JSS specific issues to assist you if necessary.

We recommend you evaluate your needs in relation to GraphQL retries and use GraphQL request retry strategies as needed to mitigate rate limits in GraphQL endpoints.

Do you have some feedback for us?

If you have suggestions for improving this article,