1. Sitecore JavaScript Services SDK (JSS)

Upgrade JSS 21.5 Next.js apps to version 21.6

Version:

The JavaScript Rendering SDKs (JSS) 21.6 consolidates client management for all GraphQL-based services and refactors some services and configurations.

This topic covers most of the changes you must make in your existing JSS 21.5 applications to take advantage of the new features.

Due to the nature of JavaScript and Next.js application development, this guide can not 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.5 application might use the following templates and add-ons:

  • nextjs 

  • nextjs-sxa 

  • nextjs-multisite 

Before you begin

  • Familiarize yourself with the changelog. If your application is heavily customized, you might need to refer to it for hints on what additional changes you need, which might not be covered in this topic.

This topic describes how to:

  • Update application dependencies in your existing app.

  • Update environment variables for your existing app.

  • Create a JSS 21.6 Next.js application.

  • Update the Next.js template files in your existing app.

  • Update SXA add-on files (if present).

  • Update the Multisite add-on files.

Update application dependencies in your existing app

For your existing application to work correctly and use new features, you need to update dependencies.

To update your dependencies:

  1. In your existing application's package.json file:

    • Update every @sitecore-jss package to use version ~21.6.0.

    • Update @types/react to ^18.2.22.

  2. Install the dependencies with the following command:

    npm install

Update environment variables for your existing app

The updated configuration scripts need some new environment variables.

To provide the new environment variables to your application, modify your .env file as follows:

  • Rename the JSS_APP_NAME environment variable to SITECORE_SITE_NAME. This is optional.

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

Create a JSS 21.6 Next.js application

To simplify the upgrade process as much as possible, you must first create a JSS 21.6 Next.js application. You will need to copy some files from the 21.6 app into your existing app.

To create a JSS 21.6 Next.js application:

  1. In a console, run the following command:

    npx create-sitecore-jss@^21.6.0 nextjs

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

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

  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 n to skip installing the XM Cloud add-on.

  6. Select the add-ons used by your existing application - nextjs-sxa and/or nextjs-multisite 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 replace files in your existing applications with corresponding files for the JSS 21.6 app, or modify your existing app files using the JSS 21.6 app files as a guide.

Update the Next.js template files as follows:

  1. Replace the /scripts/generate-config.ts file in your existing application with the 21.6 version.

  2. Replace the /src/lib/next-config/plugins/cors-header.js file in your existing application with the 21.6 version.

  3. Copy the the /src/lib/graphql-client-factory/ folder from the 21.6 app to your existing app.

  4. Copy the /src/lib/config.ts file from the 21.6 app to your existing app.

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

    • Add the following import statement:

      import clientFactory from 'lib/graphql-client-factory';

    • Locate the following GraphQLDictionaryService constructor options:

      {
  endpoint: config.graphQLEndpoint,
  apiKey: config.sitecoreApiKey,
  siteName,
  retries:
    (process.env.GRAPH_QL_SERVICE_RETRIES && 
     parseInt(process.env.GRAPH_QL_SERVICE_RETRIES, 10)) ||
    0,
}

    • Replace that code block with the following:

      {
  clientFactory,
  siteName,
  retries:
    (process.env.GRAPH_QL_SERVICE_RETRIES && 
     parseInt(process.env.GRAPH_QL_SERVICE_RETRIES, 10)) ||
    0,
}

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

    • Add the following import statement:

      import clientFactory from 'lib/graphql-client-factory';

    • Locate the following GraphQLLayoutService constructor options:

      {
  endpoint: config.graphQLEndpoint,
  apiKey: config.sitecoreApiKey,
  siteName,
  retries:
    (process.env.GRAPH_QL_SERVICE_RETRIES && 
     parseInt(process.env.GRAPH_QL_SERVICE_RETRIES, 10)) ||
    0,
}

    • Replace that code block with the following:

      {
  clientFactory,
  siteName,
  retries:
    (process.env.GRAPH_QL_SERVICE_RETRIES && 
     parseInt(process.env.GRAPH_QL_SERVICE_RETRIES, 10)) ||
    0,
}

  7. In the /src/pages/_app.tsx file, do the following:

    • Add the following import statement:

      import Bootstrap from 'src/Bootstrap';

    • Add the Bootstrap component to the app rendering function. For example:

        return (
    <>
      <Bootstrap {...pageProps} />
      <I18nProvider lngDict={dictionary} locale={pageProps.locale}>
        <Component {...rest} />
      </I18nProvider>
    </>
  );

  8. In the /next.config.js file, replace the remove the import of the getPublicUrl function and replace the function's call with jssConfig.publicUrl.

  9. Replace the rest of the files in the /scripts/config folder with the 21.6 versions.

  10. In the /src/Layout.tsx and the /src/Navigation.tsx files do the following:

    • Import the config object:

      import config from 'temp/config';

    • Instead of using the getPublicUrl function to generate the value of the publicUrl constant, replace it with the value from the config object:

      const publicUrl = config.publicUrl;

    • Remove the import { getPublicUrl } from '@sitecore-jss/sitecore-jss-nextjs/utils'; statement.

  11. Remove the /src/lib/page-props-factory/plugins/content-styles.ts file if present.

Update SXA add-on files

To upgrade the SXA add-on (if present):

  1. Replace the /src/assets/sass folder with the 21.6 version.

  2. If you have not customized the /src/lib/middleware/plugins/redirects.ts file, replace it with the 21.6 version. Otherwise, modify it as follows:

    • Add the following import statement:

      import clientFactory from 'lib/graphql-client-factory';

    • Locate the following RedirectsMiddleware constructor options:

      {
  endpoint: config.graphQLEndpoint,
  apiKey: config.sitecoreApiKey,
  locales: ['en'],
  excludeRoute: () => false,
  disabled: () => process.env.NODE_ENV === 'development',
  siteResolver,
}

      Replace that code block with the following:

      {
  clientFactory,
  locales: ['en'],
  excludeRoute: () => false,
  disabled: () => process.env.NODE_ENV === 'development',
  siteResolver,siteName,
  retries:
    (process.env.GRAPH_QL_SERVICE_RETRIES && 
     parseInt(process.env.GRAPH_QL_SERVICE_RETRIES, 10)) ||
    0,
}

  3. If you have not customized the /src/pages/api/sitemap.ts route, replace it with the 21.6 version. Otherwise, remove the import statement for the getPublicUrl utility function and create two new constants for reqtHost and reqProtocol. Use them to build the page locator:

      const reqtHost = req.headers.host;
  const reqProtocol = req.headers['x-forwarded-proto'] || 'https';
  const SitemapLinks = sitemaps
    .map((item) => {
      const parseUrl = item.split('/');
      const lastSegment = parseUrl[parseUrl.length - 1];
      return `<sitemap>
        <loc>${reqProtocol}://${reqtHost}/${lastSegment}</loc>
      </sitemap>`;
    })
    .join('');

  4. If you have not customized the /src/pages/404.tsx and /src/pages/500.tsx files, replace them with the 21.6 version. Otherwise, in the getStaticProps function, import and use the GraphQL request client factory, instead of the endpoint and apiKey options for the GraphQLErrorPagesService instantiation:

    import clientFactory from 'lib/graphql-client-factory';

export const getStaticProps: GetStaticProps = async (context) => {
  // other code
  const errorPagesService = new GraphQLErrorPagesService({
    clientFactory,
    siteName: site.name,
    language: context.locale || config.defaultLanguage,
    retries:
      (process.env.GRAPH_QL_SERVICE_RETRIES &&
        parseInt(process.env.GRAPH_QL_SERVICE_RETRIES, 10)) ||
      0,
  });
}

Update the Multisite add-on files

To use the new GraphQL request client factory, you need to update the GraphQL Sitemap Service provided by the JSS Next.js Multisite add-on.

To update the Sitemap service:

  • If you have not customized the /src/lib/sitemap-fetcher/plugins/graphql-sitemap-service.ts file, replace it with the 21.6 version. Otherwise, do the following:

    • Add the following import statement:

      import clientFactory from 'lib/graphql-client-factory';

    • Replace the endpoint and apiKey options for the MultisiteGraphQLSitemapService instantiation with the client factory:

      this._graphqlSitemapService = new MultisiteGraphQLSitemapService({
  clientFactory,
  sites: [...new Set(siteResolver.sites.map((site: SiteInfo) => site.name))],
});
If you have suggestions for improving this article, let us know!