Editor integration using metadata

The Next.js JSS sample application includes three Next.js API routes that facilitate the integration with Sitecore content and layout editors, as follows:

The JSS editing secret is a token for securing the Sitecore editor endpoints exposed by the JSS Next.js apps through the Render API Route.

You must set the JSS editing secret both client-side and server-side.

The middleware EditingRenderMiddleware automatically validates the token. If validation fails, it returns a response with the HTTP status code 401.

Preview mode is a built-in feature of Next.js meant for CMS use cases where you write draft content (such asin XM Cloud Pages, and you want to render pages with this content at request time, bypassing any static generation.

Integrating Next.js JSS apps with Sitecore editors relies on this feature.

The EditingRenderMiddleware middleware enables Next.js preview mode, which creates specific cookies on the Render API route responses and passes them along to the subsequent page route request.

The page props factory, responsible for preparing all the data needed to render the page, checks whether the current route is in preview mode; if it is, the page route request is an editing request and can use the preview data to fetch editing data using the GraphQLEditingService.

A GET request made by XM Cloud Pages to the render API route contains the required query string parameters to render a given page route.

The page props factory uses those query string parameters to fetch editing data using the GraphQLEditingService. The editing data contains the layout data and dictionary data necessary for rendering the page.

The page props factory uses the editing data to populate the page props.

The following represents an example GET request to the editing render endpoint when using metadata-based integration:

/api/editing/render?secret={EDITING_SECRET}&sc_site=nextjs-app&sc_itemid=54C8E9B5-0B2C-5363-8FA6-D32A3A302F51&sc_lang=en&route=/&mode=edit&sc_version=latest&sc_variant={VARIANT_ID}&sc_layoutKind=shared

sc_layoutKind is an enum with a default value of final, but it can be set to shared instead if needed.

The sc_version, sc_variant, and sc_layoutKind parameters are all optional.

You can find the relevant APIs for Sitecore editor integration in the @sitecore-jss/sitecore-jss-nextjs NPM package in the editing submodule.

To use any of these, import them into your code file. For example:

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

import { EditMode } from '@sitecore-jss/sitecore-jss-nextjs';
const handler = new EditingConfigMiddleware({
  ...
  pagesEditMode: EditMode.Chromes,
}).getHandler();

If you're using an editing host provided by XM Cloud, the SITECORE_CONTEXT_ID environment variable is initially set to the preview value of the Sitecore context ID.

The way to configure an external editing host depends on your use case: