Editor integration using chromes

Version: 22.x

A Next.js application can be integrated with advanced Sitecore editors (such as the Experience Editor or Pages) using the Sitecore Headless Services HTTP rendering engine, Next.js API routes, and the Next.js Preview Mode. This method uses chromes, and until JSS 22.1 was the only way to integrate with editors.

Tip

If you're using JSS 22.1 or later and you only want to integrate with XM Cloud Pages, we recommend you use the newer metadata integration method instead of the one described here. That newer method provides a range of benefits including a significantly simpler configuration. If you want to integrate with Sitecore Experience Editor, you have to use chromes.

Chromes is the term used by Sitecore to describe invisible HTML elements that are produced by the layout service and used to wrap layout elements, allowing those elements to be edited with visual editors.

The following diagram illustrates the architecture of integrating a Next.js JSS app with advanced Sitecore editors using chromes. The diagram uses Sitecore Experience Editor as an example, but the architecture is similar for Pages integration.

The architecture of integrating a Next.js JSS app with advanced Sitecore editors using chromes
Note

The diagram highlights APIs included with JSS for Next.js in teal. Elements with other colors are part of the Next.js JSS sample application.

API routes

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 Render API Route defined in the file <src>/pages/api/editing/render.ts handles POST requests from the Sitecore editor, using logic encapsulated in the middleware EditingRenderMiddleware provided by JSS for Next.js. Use this route as the value for the JSS app configuration option serverSideRenderingEngineEndpointUrl.

  • The Data API Route defined in <src>/pages/api/editing/data/[key].ts is a dynamic Next.js API route responsible for storing and retrieving data sent from the Sitecore editor using the middleware EditingDataMiddleware provided by the Next.js SDK. The application uses this route only if using the ServerlessEditingDataService.

  • The Page Route, the main Next.js optional catch-all route, defined in <src>/pages/[[...path]].tsx, renders all Sitecore page routes.

JSS Editing Secret

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 and the Data API Route.

You must set the JSS Editing Secret client-side and server-side.

The middlewares EditingRenderMiddleware and EditingDataMiddleware automatically validate the token. If validation fails, they return a response with the HTTP status code 401.

Next.js Preview Mode

Preview Mode is a built-in feature of Next.js meant for CMS use cases where you write draft content (such as the Sitecore Experience Editor), and you want to render pages with this content at request time, bypassing any static generation.

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

The EditingRenderMiddleware middleware enables Next.js Preview Mode. Next.js Preview Mode 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 if the current route is in Preview Mode. If it determines that the page is in preview mode, the page route request is an editing request and can use the preview/editing data.

Understanding data editing in JSS Next.js

The POST request made by a Sitecore editor to the render API route contains everything required to render a given page route. The request includes editing data.

Editing data contains layout, dictionary, and language data, the metadata necessary for rendering the editor, and unsaved layout information.

The Page Props Factory uses the editing data to populate the page props, as opposed to fetching them individually when not in editing mode.

The following represents an example payload sent with a POST request to the editing endpoint when using chromes-based integration:

RequestResponse
{
  "id": "nextjs-app",
  "args": [
    "/?sc_mode=edit&sc_itemid=%7b54C8E9B5-0B2C-5363-8FA6-D32A3A302F51%7d&sc_lang=en&sc_version=1&sc_site=nextjs-app",
    sitecoreContext,
    dictionary,
  ],
  "functionName": "renderView",
  "jssEditingSecret": "jssEditingSecret",
  "moduleName": "server.bundle",
}

In this example, sitecoreContext is a stringified version of the following:

RequestResponse
{
  sitecore: {
    context: {
      pageEditing: true,
      site: {
        name: "nextjs-app",
      },
      pageState: "edit",
      editMode: "chromes",
      ...
    },
    route: {
      name: "home",
      displayName: "home",
      fields: {
        ...
      },
      databaseName: "master",
      ...
    },
  },
}

Also in this example, dictionary is a stringified version of this:

RequestResponse
{
  language: "en",
  dictionary: {
    Documentation: "Documentation",
    GraphQL: "GraphQL",
    Styleguide: "Styleguide",
    "styleguide-sample":
      "This is a dictionary entry in English as a demonstration",
  },
}

Maintaining editing data between requests

Because Next.js compiles API routes as Serverless Functions, separate from page routes, the framework removes the option of a simple storage solution for the editing data, such as a Node.js memory cache on the server.

Furthermore, Next.js stores preview data in a cookie. The Next.js Preview Mode has a size limitation for preview data, and Sitecore editing data exceeds this limit.

To maintain editing data between requests and remove the preview data size limitation, the Next.js SDK uses a disk-based cache implementation regardless of whether the application is deployed in a self-hosted or serverless deployment architecture.

APIs

You can find the relevant APIs for Sitecore editor integration, except the EditingDataService, in the @sitecore-jss/sitecore-jss-nextjs NPM package in the middleware sub-module.

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

RequestResponse
import { EditingRenderMiddleware } from '@sitecore-jss/sitecore-jss-nextjs/middleware';
import { editingDataService } from '@sitecore-jss/sitecore-jss-nextjs';

EditingRenderMiddleware

The EditingRenderMiddleware is a middleware/handler for the editing Render API Route. The middleware:

  • Validates the JSS Editing Secret.

  • Extracts editing data from the POST request payload and stashes it with the help of the EditingDataService that returns a key for retrieval.

  • Enables Next.js Preview Mode, passing the stashed editing data key as preview data.

  • Invokes the Page Route request, passing along the Preview Mode cookies.

  • Returns the rendered page HTML to the Sitecore editor in the expected JSON format.

  • Allows you to override protocols for HTTP requests when not hosting the JSS Next.js application on Vercel.

EditingConfigMiddleware

EditingConfigMiddleware is a middleware handler for the editing Config API Route. The middleware:

  • Validates the JSS editing secret.

  • Provides a required configuration (application metadata) for XM Cloud Pages to determine feature compatibility and configuration.

This middleware supports the pagesEditMode option, which allows you to specify the editing mode used by Pages. It is set to metadata by default, but if you aren't ready to use the new metadata integration, you can continue using the existing chromes editing integration for Pages by setting pagesEditMode to EditMode.Chromes as follows:

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

EditingDataService

The EditingDataService is the service responsible for maintaining Sitecore editor data (editing data) between requests.

You typically use the editingDataService service, an EditingDataService singleton with default values.

EditingDataMiddleware

The EditingDataMiddleware is a middleware/handler for the editing Data API Route.

The EditingDataMiddleware:

  • Validates the JSS Editing Secret.

  • Sets (HTTP PUT request) or gets (HTTP GET request) editing data through the EditingDataCache.

EditingDataCache

The EditingDataCache is an interface that defines an editing data cache implementation.

EditingDataDiskCache

The EditingDataDiskCache is a disk-based EditingDataCache implementation (default). It is necessary for hosting on Vercel using Serverless Functions.

When hosting the Next.js application on platforms other than Vercel, the instability of the temporary directory used by the editing data cache can cause cache-miss errors. To resolve the errors, override the default directory used by the disk-based editing cache implementation.

Do you have some feedback for us?

If you have suggestions for improving this article,