Architecture and APIs for integrating JSS Next.js apps with Sitecore editors

Current version: 19.x

A Next.js application uses the Sitecore Headless Services HTTP rendering engine, Next.js API routes, and the Next.js Preview Mode to integrate with advanced Sitecore editors, such as the Experience Editor or Horizon.

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

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

In the diagram, APIs included with JSS for Next.js are highlighted with teal. Elements with other colors are part of the Next.js JSS sample application.

API routes

To integrate with Sitecore editors, the Next.js JSS sample application includes three Next.js API routes, 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 handling the storage and retrieval of data sent from the Sitecore editor using the middleware EditingDataMiddleware provided by JSS for Next.js.

  • 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 used to secure 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 are writing 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 that is needed to render a given Page Route. The request includes layout, dictionary, and language data, as well as the extra metadata necessary for rendering the editor and unsaved layout information. This data is referred to as editing data.

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

Maintaining editing data between requests

When deploying to Vercel, the Render API Route automatically becomes an isolated Serverless Function completely separate from the Page Route, removing the option of a simple storage solution for the editing data, such as a Node.js memory cache on the server.

The Sitecore Next.js SDK includes a cache implementation that solves the compatibility issue with Vercel Serverless Functions.

Next.js stores preview data in a cookie. The Next.js Preview Mode has a size limitation of 2KB for preview data and Sitecore editing data exceeds this limit. A custom storage solution for editing data solves this problem as well.

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.

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.

Do you have some feedback for us?

If you have suggestions for improving this article,