The JSS XM Cloud add-on for Next.js

Current version: 22.0

The XM Cloud add-on for JSS Next.js applications simplifies connecting a Next.js application to an XM Cloud environment and integrating other services and products in the Sitecore Composable Digital Experience stack. The simplified setup is achieved through the Context ID, a unified identifier that maps to all your configured resources, such as content, sites, files, forms, and integration settings.

The XM Cloud add-on is available in JSS version 21.6 and later. To upgrade to 21.6, follow the detailed upgrade guide.


XM Cloud generates and provides the Context ID when you create an environment through the CLI or the Deploy App.

The JSS XM Cloud add-on for Next.js:

  • Adds support for the Context through the App Context feature and generates the Edge GraphQL endpoint based on the default Sitecore Edge URL and the Context ID. For example, ${sitecoreEdgeUrl}/v1/content/api/graphql/v1?sitecoreContextId=${sitecoreEdgeContextId}.

  • Includes a Context-aware GraphQL Client Factory.

  • Supports the option to bring-your-own code components (BYOC).

  • Adds support for Sitecore XM Cloud Forms through BYOC functionality.

  • Includes support for tracking and analytics with the Cloud Development Kit, previously provided by the @sitecore/engage NPM package.

  • Supports Context-enabled Personalization. The nextjs-personalize add-on is obsolete from JSS version 21.6 onwards.

Environment variables

To configure the XM Cloud add-on, JSS uses two environment variables:

  • SITECORE_EDGE_CONTEXT_ID - the Context ID. Generated and provided by XM Cloud. This can be the value of the Live Context ID (which provides access to the published content) or the Preview Context ID (which also provides access to both the published and the unpublished content).

  • SITECORE_SITE_NAME - the name of your Sitecore site. If empty, it uses the config.appName property defined in the package.json file. When using the Next.js Multisite add-on, the variable's value represents the default/configured site.

The App Context

The App Context supports initializing the context information and the SDKs used in the application based on the Context ID.

This feature is available only in JSS applications using the nextjs-xmcloud add-on.

The App Context is defined in the src/lib/context/index.ts file.

The JSS Next.js application defines a custom app with the Bootstrap component to initialize the App Context.

The Bootstrap component is defined in the src/Bootstrap.tsx file. It prepares resources, such as sitecoreEdgeContextId and sitecoreSiteName, needed to interact with various application services and features. The component is an entry point for performing any initialization logic that needs to happen early in the application's lifecycle, including the App Context initialization.

The App Context is initialized only once and passed to various features and services, such as the Events package in the Cloud Development Kit and the BYOC Components.

The GraphQL Client Factory

The GraphQL Client Factory generates GraphQL clients aware of the XM Cloud Context ID and Sitecore Edge URL.

The factory is created in the src/lib/graphql-client-factory/index.ts file based on the JSS app configuration temp/config information using the factory creation function defined in the src/lib/graphql-client-factory/create.ts file.

The factory is exported and made available to any functionality or integration requiring a GraphQL client to know the Context ID.

Preconfigured elements in the XM Cloud add-on

A Next.js application with JSS XM Cloud add-on comes preconfigured with:

  • The Sitecore Cloud SDK Events package (@sitecore-cloudsdk/events/browser). The Events package replaces the @sitecore/engage package used in JSS versions older than 21.6. The Events SDK uses the Sitecore Edge URL and Context ID.

  • Middleware and services that are ready to use the Context ID, if defined, such as:

    • The Personalize Middleware.

    • The GraphQL Dictionary Service and the GraphQL Layout Service factories.

    • The GraphQL Sitemap Service.

    • BYOC functionality that is Context-aware. The App Context is already set in the BYOC configuration and available in BYOC Components.

Do you have some feedback for us?

If you have suggestions for improving this article,