---
title: "Editor integration using metadata"
slug: "editor-integration-using-metadata"
abstract: "Overview of the architecture and APIs for integrating Content SDK Next.js Pages Router apps with the Page builder using metadata."
---
# Editor integration using metadata

This topic describes the metadata-based integration of Next.js Pages Router applications with the SitecoreAI Page builder. The Page builder uses the metadata provided by the layout service for placeholders, renderings, and fields to identify them and enable visual editing directly in the browser. This relies on the [Sitecore Headless Services HTTP rendering engine](https://doc.sitecore.com/xp/en/developers/hd/22/sitecore-headless-development/http-rendering-engine.html), [Next.js API routes](https://nextjs.org/docs/pages/building-your-application/routing/api-routes), and the [Next.js Preview Mode](https://nextjs.org/docs/pages/guides/preview-mode).

The following diagram illustrates the architecture of integrating a Content SDK Next.js Pages Router app with the Page builder:

![The architecture of integrating a Content SDK Next.js Pages Router app with the SitecoreAI Page builder using metadata](https://doc.sitecore.com/api/markdown-image/sai/en/developers/content-sdk/20/images/editor-integration-using-metadata.png)

> [!note]
> The diagram highlights APIs included with Content SDK for Next.js in teal. Elements with other colors are part of the Next.js Content SDK sample application.

If you want to test components without affecting published sites or other users on the same environment, you can connect your [local host directly to Pages](https://doc.sitecore.com/xmc/en/developers/xm-cloud/en/connect-your-local-host-to-pages.html).

> [!important]
> Certain header configurations restrict the loading of `iframes` that can prevent metadata integration from working. For example:
>
> -   Setting the `X-Frame-Options` header to `"SAMEORIGIN"`.
>
> -   Setting the `Content-Security-Policy` header to `"frame-ancestors 'self'"`.
>
>
> To avoid this issue, ensure your response headers allow the Pages domain to load the response inside an iframe, either by adjusting these settings or adding exceptions as needed.

## API routes

The Next.js Content SDK 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 `GET` requests using logic encapsulated in the middleware `EditingRenderMiddleware` provided by Content SDK for Next.js. Use this route as the value for the Content SDK app configuration option `serverSideRenderingEngineEndpointUrl`.
- The Config API route defined in the file `<src>/pages/api/editing/config.ts` handles `GET` requests using logic encapsulated in the middleware `EditingConfigMiddleware` provided by Content SDK for Next.js.
- The Page route, which is the main [Next.js optional catch-all route](https://doc.sitecore.com/sai/en/developers/content-sdk/20/route-handling-and-data-fetching-in-content-sdk-apps.html "Route handling and data fetching in Content SDK apps") defined in `<src>/pages/[[...path]].tsx`, renders all Sitecore page routes.

## Sitecore editing secret

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

The middleware `EditingRenderMiddleware` automatically validates the token. If validation fails, it returns 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 SitecoreAI Page builder), and you want to render pages with this content at request time, bypassing any static generation.

Integrating Next.js Content SDK 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 data is requested within the catch-all route and depends on whether the current route is in preview mode. In such cases, the appropriate `SitecoreClient` method should be used, depending on the application mode: `getPreview` or `getDesignLibraryData`.

## Understanding data editing in Content SDK Next.js

A `GET` request made by the SitecoreAI Page builder to the render API route contains the required query string parameters to render a given page route.

The `SitecoreClient` uses those query string parameters to fetch editing data. The editing data contains the layout data necessary for rendering the page.

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

```text
/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.

## APIs

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

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

```ts
import { EditingRenderMiddleware } from '@sitecore-content-sdk/nextjs/editing';
```

### EditingRenderMiddleware

`EditingRenderMiddleware` is a middleware handler for the editing Render API route. It does the following:

- Validates the Sitecore editing secret.
- Extracts the required query string parameters from the request URL.
- Enables Next.js preview mode, passing the parameters to the preview data.
- Sends an internal request to the editing host’s catch-all route to fetch the page.
- Returns the rendered page markup as the response.

### EditingConfigMiddleware

`EditingConfigMiddleware` is a middleware handler for the editing Config API route. It does the following:

- Validates the Sitecore editing secret.
- Provides a required configuration (application metadata) to determine feature compatibility and configuration.