1. Sitecore JavaScript Rendering SDKs (JSS) 21.6

Upgrade JSS 21.5 Next.js apps to version 21.6

Version:

The JavaScript Rendering SDKs (JSS) 21.6 brings new features and support for the Edge Context and the XM Cloud add-on for Next.js that simplifies integrating personalization features and other composable services and products. Furthermore, some functionality was consolidated into this new plugin, and we refactored some services and configurations to support the Edge Context and simplify configuration.

The update contains changes in 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.5 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.5 application included in the XM Cloud starter foundation uses the following templates and add-ons:

  • nextjs

  • nextjs-personalize

  • 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.

  • Read the documentation for the JSS XM Cloud add-on. It will help you understand the changes you must make when following this topic.

XM Cloud is now SitecoreAI

Some code examples, images, and UI labels may still use XM Cloud while engineering assets are being updated.

This topic describes how to:

  • Update environment variables for your existing app.

  • Update application dependencies in 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.

  • Migrate from the Personalize add-on to the XM Cloud add-on.

  • Update the Multisite add-on files.

  • Fix BYOC errors after upgrading.

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, you must modify your .env file as follows:

  1. Add the SITECORE_EDGE_CONTEXT_ID . The value is your Context ID. This is required to use the Sitecore Edge Platform.

  2. Rename the JSS_APP_NAME environment variable to SITECORE_SITE_NAME.

  3. Remove the following deprecated environment variables:

    • NEXT_PUBLIC_CDP_TARGET_URL

    • NEXT_PUBLIC_CDP_CLIENT_KEY

    • NEXT_PUBLIC_CDP_POINTOFSALE

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:

    XM Cloud is now SitecoreAI

    Some code examples, images, and UI labels may still use XM Cloud while engineering assets are being updated.

    1. If you don't use the XM Cloud/Personalize add-on, remove the following dependency:

      "@sitecore-feaas/clientside": "^0.5.5"

    2. If you do use the XM Cloud/Personalize add-on, remove the "@sitecore/engage": "^1.4.1" dependency and replace it with the following:

      "@sitecore-cloudsdk/events": "^0.1.3",
"@sitecore-feaas/clientside": "^0.5.12"

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

    4. Update the @sitecore/components package to version ~1.0.19. If not present, add it.

    5. Update @types/react to ^18.2.22.

  2. Install the dependencies with the following command:

    npm install

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 with the XM Cloud add-on. 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 with the XM Cloud add-on included:

XM Cloud is now SitecoreAI

Some code examples, images, and UI labels may still use XM Cloud while engineering assets are being updated.

  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, ./jss216, 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 the add-ons used by your existing application - nextjs-sxa and/or nextjs-multisite and press Enter.

    Note

    The nextjs-personalize plugin has been replaced by the XM Cloud add-on (nextjs-xmcloud), so you will not see it in the list of add-ons.

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.

To update the Next.js template files:

  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:

    1. Add the following import statement:

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

    2. Locate the following GraphQLDictionaryService constructor options:

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

    3. Replace that code block with the following:

      {
  clientFactory,
  siteName: config.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:

    1. Add the following import statement:

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

    2. Locate the following GraphQLLayoutService constructor options:

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

    3. Replace that code block with the following:

      {
  clientFactory,
  siteName: config.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:

    1. Add the following import statement:

      import Bootstrap from 'src/Bootstrap';

    2. 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 import of the getPublicUrl function and replace the function 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:

    1. Import the config object:

      import config from 'temp/config';

    2. Instead of generating it with the getPublicUrl function to generate the value of the publicUrl constant, replace it with the value from the config object:

      const publicUrl = config.publicUrl;

    3. Remove the following statement:

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

  11. Replace any remaining occurrences of the config property jssAppName with sitecoreSiteName.

Update SXA add-on files

To upgrade the SXA add-on:

  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:

    1. Add the following import statement:

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

    2. 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,
}

  3. In /src/pages/api/sitemap.ts, do the following:

    1. 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:

      // ...other code
  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('');
// ... other code

    2. Add the following import statement:

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

    3. Locate the sitemapXmlService initialization and replace it with the following:

      const sitemapXmlService = new GraphQLSitemapXmlService({
  clientFactory,
  siteName: site.name,
});

  4. In /src/pages/api/robots.ts, do the following:

    1. Locate the following import statement:

      import config from 'temp/config';

    2. Replace that statement with the following:

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

    3. Locate the robotsService initialization and replace it with the following:

      const robotsService = new GraphQLRobotsService({
  clientFactory,
  siteName: site.name,
});

  5. 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';
// ...other code
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,
  });
  // ... other code
}

Migrate from the Personalize add-on to the XM Cloud add-on

The XM Cloud add-on (nextjs-xmcloud) adds support for the unified Context to JSS Next.js apps, enabling simplified configuration.

Furthermore, the XM Cloud add-on replaces the deprecated Personalize add-on (nextjs-personalize). This is only relevant in dependencies, as the files added to your application by the old add-on still exist, but they must be updated to use new environment variables and the GraphQL request client factory.

XM Cloud is now SitecoreAI

Some code examples, images, and UI labels may still use XM Cloud while engineering assets are being updated.

To use the new simplified configuration and correctly implement Personalization features, you need to make the following changes:

  1. Copy the following from the JSS 21.6 Next.js application into your existing application:

    • The /scripts/config/plugins/edge-platform.ts file.

    • The /src/lib/context folder.

    • The /src/byoc folder.

    • The /src/Bootstrap.tsx file.

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

    1. Import the bootstrapped config object and the GraphQL request client factory:

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

    2. In the edgeConfig object, replace the endpoint and apiKey properties with the imported clientFactory:

      edgeConfig: {
   clientFactory,
   timeout:
      (process.env.PERSONALIZE_MIDDLEWARE_EDGE_TIMEOUT &&
         parseInt(process.env.PERSONALIZE_MIDDLEWARE_EDGE_TIMEOUT)) ||
      400,
   scope: process.env.NEXT_PUBLIC_PERSONALIZE_SCOPE,
},

    3. In the cdpConfig object, replace the endpoint and clientKey properties with sitecoreEdgeUrl and sitecoreEdgeContextId:

      cdpConfig: {
 sitecoreEdgeUrl: config.sitecoreEdgeUrl,
 sitecoreEdgeContextId: config.sitecoreEdgeContextId,
 timeout:
   (process.env.PERSONALIZE_MIDDLEWARE_CDP_TIMEOUT &&
      parseInt(process.env.PERSONALIZE_MIDDLEWARE_CDP_TIMEOUT)) ||
    400,
}

  3. If you have not customized the /src/components/CdpPageView.tsx, replace it with the 21.6 version. Otherwise, make the following changes:

    1. Remove the SiteInfo, PosResolver, init, and siteResolver imports.

    2. Import the Context instance:

      import { context } from 'lib/context';

    3. Replace the createPageView asynchronous function with:

      context.getSDK('Events')?.then((Events) =>
   Events.pageView({
      channel: 'WEB',
      currency: 'USD',
      page: route.name,
      pageVariantId,
      language,
   })
).catch((e) => console.debug(e));

  4. In the /src/Scripts.tsx file, import and use the BYOC component:

    import BYOC from 'src/byoc';
import CdpPageView from 'components/CdpPageView';

const Scripts = (): JSX.Element => {
  return (
    <>
      <BYOC />
      <CdpPageView />
    </>
  );
};

export default Scripts;

If you are not using the nextjs-sxa add-on, copy the following files from the 21.6 application to your existing application:

  • /scripts/scaffold-component/plugins/byoc.ts

  • /scripts/scaffold-component/plugins/next-steps-byoc.ts

  • /scripts/templates/byoc-component-src.ts

These files are already present if you use the nextjs-sxa add-on.

Update the Multisite add-on files

To use the new GraphQL request client factory, you must 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))],
});

Fix BYOC errors after upgrading

After upgrading, you might experience errors or unexpected behaviors. Here are some problems you might encounter and tips for how to solve them.

External (BYOC) component registration errors

If you’re using External (BYOC) Components in your app, you might encounter This component was not registered. errors.

You can get these errors in two situations:

  • If your BYOC components are not imported in /src/byoc/index.client.ts or /src/byoc/index.hybrid.ts.

  • If you don't have the /src/lib/next-config/plugins/feaas.js plugin in your application. This plugin ensures the FEEAS SDK uses Commonjs on the server, and prevents double registration of BYOC components such as client-side and server-side.

To resolve these errors:

  • Ensure that your components are imported in either /src/byoc/index.client.ts or /src/byoc/index.hybrid.ts, depending on the context where they run.

  • Copy the /src/lib/next-config/plugins/feaas.js file from the 21.6 application you created at the start of the upgrade work.

External (BYOC) components do not work

If BYOC components don't work, ensure the <BYOC/> component is imported and rendered in either of these files:

  • /src/Scripts.tsx

  • src/Layout.tsx

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