First Look at Sitecore Next.js Metadata Editing Mode
First Look at Sitecore Next.js Metadata Editing Mode
Introduction
On August 2024, Sitecore introduced a new version of JavaScript Services (JSS) – 22.1, one of the main features of which is a new editing mode called Metadata.
The new mode is much simpler and more effective than the previous approach called Chromes.
We already explained in our blog how the Chromes mode works and recommend reading this to understand the specifics of the old approach and, therefore, the advantages of the Metadata described further in the article.
The main architecture difference between the two approaches is that in the Metadata mode the responsibility for the page rendering is moved from the CM instance to the rendering host.
This gives us several benefits:
- The architecture of the editing process is much simpler (see the diagram below)
- The initial page rendering takes less time
- No need for ngrok tunneling and CORS exemptions
- Easier handling of relative paths in an application
- Simpler work with a local rendering host – no need to set up a local CM instance and quick substitution of the default rendering host in XM Cloud
The Metadata mode is designed to work only with the Pages editor and not supported by the Experience Editor yet. It is enabled by default in all Next.js applications that use JSS 22.1 (or higher versions).
You can find more details about the Metadata approach and benefits in this blog.
Next.js Preview Mode
In terms of Next.js, both editing modes rely on the Preview Mode. This feature requires an additional endpoint in the rendering host which will be responsible for “previewing” the site.
You can read more information about Next.js Preview Mode here.
To speed up site development, JSS provides this endpoint in the Next.js application templates out-of-the-box. The endpoint can be accessed via the route - /api/editing/render.
If you look at its implementation in the nextjs-xmcloud template, you will find it very simple.
It includes:
- A comment section which describes how both editing modes work
- A small request configuration for the Chromes mode
- A call of the EditingRenderMiddleware handler located in the sitecore-jss-nextjs library
// Bump body size limit (1mb by default) and disable response limit for Sitecore editor payloads
// See https://nextjs.org/docs/api-routes/request-helpers#custom-config
export const config = {
api: {
bodyParser: {
sizeLimit: '2mb',
},
responseLimit: false,
},
};
// Wire up the EditingRenderMiddleware handler
const handler = new EditingRenderMiddleware().getHandler();
export default handler;
The preview endpoint implementation in JSS 22.1
In addition to checking the allowed origins and the security token, this middleware determines which editing mode the Pages editor should use – Metadata or Chromes. The decision is straightforward and based on the HTTP method used to call the preview endpoint. If the endpoint is called with:
- GET method, the Pages uses the Metadata editing mode
- POST method, the Pages uses the Chromes editing mode
switch (req.method) {
case 'GET': {
const handler = new MetadataHandler({ resolvePageUrl: this.config?.resolvePageUrl });
await handler.render(req as MetadataNextApiRequest, res);
break;
}
case 'POST': {
const handler = new ChromesHandler(this.config);
await handler.render(req, res);
break;
}
default:
debug.editing('invalid method - sent %s expected GET/POST', req.method);
res.setHeader('Allow', 'GET, POST');
return res.status(405).json({
html: `<html><body>Invalid request method '${req.method}'</body></html>`,
});
}
Switch statement in EditingRenderMiddleware handler
Metadata mode
Let’s take a look at how the Metadata mode works.
The Metadata mode diagram
First, the Pages editor makes a GET request to the preview endpoint of the rendering host. The information passed via query parameters includes:
- The page data needed for fetching layout and dictionary data
- A secret token for security
- The path of the current page
An example of the preview endpoint call
As mentioned earlier, the EditingRenderMiddleware checks the HTTP method and verifies the secret token. After that, it calls one of the Next.js API methods – setPreviewData, which sets some cookies in the browser to turn on the Preview Mode. These cookies will contain the page information passed via the query parameters.
The Preview Mode cookies set by Next.js
Then, the middleware performs a 307 redirect to the page itself, including the preview mode cookies.
[[...path]].tsx receives the next request from XM Cloud Pages, checks the cookies and understands that Next.js is set to the Preview Mode.
Using the page data retrieved from the cookies, it makes a GraphQL call to the CM instance to fetch the layout and dictionary data. With this data, the rendering host generates the page markup and returns it to the Pages editor.
However, since this markup includes only the essential metadata for enabling Sitecore editing features, the Pages editor must make an additional asynchronous call to the layout service of the CM server (similar to what happens in the Chrome mode) and then rehydrates the markup with the data received in the background.
So comparing the Chromes and Metadata implementations, there are a number of differences:
| Chromes | Metadata | |
|---|---|---|
| Who calls the rendering host? | CM server | Pages editor |
| How is the preview endpoint called? | POST | GET |
| What does the transferred data contain? | Layout and Dictionary data | Page information (i.e. item ID, language, site, layout kind etc) |
| Is a data storage required? | Yes (disk-based cache) | No (cookies only) |
| How many calls the Pages perform? | Single | Multiple (async) |
Conclusion
As you have seen the newly introduced approach called Metadata has brought significant architectural changes to the editing mode.
Splitting the page rendering process into two asynchronous requests, one of which goes directly to the rendering host, can significantly reduce the initial rendering time of a page and, thereby improve the performance of the Pages editor. This improvement will be particularly noticeable for content editors as your site grows and contains more pages and components.
Another benefit of Metadata is no need of disk-based cache usage which allows us to get rid of the hosting dependencies. In the Chrome mode, the disk-based cache, by default, uses the operating system’s temporary directory. When hosting Next.js applications on platforms other than Vercel, the specifics of the temporary directory can cause cache-miss errors. To resolve this problem, you had to make additional changes in your application.
One of the shortcomings of the Metadata mode is that it only works in the XM Cloud Pages editor. This means you won’t be able to leverage the advantages of the new approach in on-premise environments that only use the Experience Editor.
Additionally, at this point, the new mode works only in Next.js applications. However, we hope that Sitecore has plans to integrate it with other front-end frameworks such as Angular, React and Vue.js.