Editor integration using chromes

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

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.

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:

{
  "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:

{
  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:

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

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.

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:

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

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