Building a Headless Next.js Site with Drupal 11 and Layout Builder

Building a modern, performant website often involves decoupling its frontend and backend to leverage specialized tools for each layer. In this type of site, we’ll discuss in this post, Drupal 11 can be a powerful headless content management system (CMS) that handles content and exposes data through JSON:API, while Next.js for Drupal can run the website’s frontend.

Hosted on Netlify, this architecture leverages the best of each technology to create a scalable solution. In our last post, we briefly discussed the Netlify module for Drupal, what it is for, and how it works. This piece outlines the steps for setting up a headless Next.js site using Drupal 11 with Layout Builder, including the Composer patches you’ll need and how to integrate Netlify for seamless builds and deployment.

We spent some time this summer making a proof of concept with Drupal 11 that demonstrates using Layout Builder as the page editor while Next.js hosted on Netlify renders the headless website. In the future, Experience Builder will supersede Layout Builder as a 2.0 version of it. However, that’s not ready yet, so we figured out how to make this configuration work in the meantime. Here’s how we did it.

Layout Builder

Drupal’s Layout Builder offers advantages for managing complex layouts and providing a better content editing experience than a typical form-based entry. When used in conjunction with a decoupled architecture, Layout Builder can complement JSON:API by offering content editors control over the structure and design of a page in a way that JSON:API cannot alone.

It would be great if an editor could use Layout Builder to arrange components on a page in a drag-and-drop fashion, so the result is rendered on a headless website. However, Layout Builder data is not exposed over JSON:API by Drupal (yet). With a few modifications, we can add Layout Builder data to JSON:API so it’s consumable by frontend technologies in a headless website scenario.

First, a few patches are required to make this happen, located in these issues:

• Harden the use of unserialize in InlineBlock via allowed classes
• Expose Layout Builder data to REST and JSON:API
• Unable to resolve path on node in other language than default

Also, you will need the contributed module JSON:API Layout Builder Include, with this patch:

• Rework module to work without a separate computed field

The reason these items are needed is rooted in the design of Layout Builder. The data storage can contain serialized PHP objects with too much data and aren’t readily available to display as JSON:API. Applying the above patches will make that happen (and make the data safe to output). We wound up rolling our own module internally based on JSON:API Layout Builder to include changes from that issue plus a little more around what we needed — but it will work fine for you otherwise.

For Layout Builder to work headless, we need the output to contain the following:

• The “type” of layout (one column, two columns, three columns, etc.)
• Any layout settings (CSS class names, attributes, or ad-hoc properties added by contributed modules)
• All the components within a given layout and their field data

This will inform the site’s frontend of the kind of layout to apply, its size, any special properties, and then of course its presentational components (content).

But why all this effort for Layout Builder? Because it allows editors that have a headless website to control and dictate the placement of elements on the page using native Drupal without being confined to “static,” concrete presentations. This presents a way to achieve two goals:

• Flexibility in creating layouts, columns, and components to meet marketing needs, without breaking the site or having to write any HTML, CSS, or JS or do code deployments.
• Lightning-fast headless website rendering to reach visitors faster than their competitor sites while harnessing all the power of Drupal behind the scenes.

While the site’s structured content types can provide consistent input and output, “landing page” type content with Layout Builder allows editors and marketers to add whatever they need to a page to convey its subject matter and calls to action.

When you add it all together, your JSON:API routes will now output Layout Builder information on API responses.

Below is a sample response from a content page served over JSON:API that includes the Layout Builder information.

In this example, someone placed a Hero in a one-column (full-width) layout and filled in the title, subtitle, and link fields.

This data can now be consumed to construct components on a headless website running a framework like Next.js, Nuxt, or a host of others. No theming was done in Drupal because it isn’t necessary in a headless scenario. We have all the information needed to build frontend layouts, containers, and components.

While verbose, it contains all the information about the components and layouts for a page in Drupal. We can trim this up and slim down the response, but this got us up and running.

Why JSON:API Over GraphQL?

JSON:API is included in Drupal core and provides a flexible and powerful framework for exposing content and configuration as structured JSON. This is advantageous for headless websites where Drupal s a backend that powers a separate frontend like Next.js.

JSON:API adheres to a clear and well-documented specification. Each piece of content, or entity, is accessible as a JSON document, with related entities represented as relationships. For example, a page node with attached images and taxonomy terms would present its relationships in a predictable and organized format.

GraphQL, while expressive and functional, requires more setup and orchestration to get going and lacks a consistently defined specification that JSON:API provides. We preferred to stick to what’s in Drupal core to keep things simple. The predictability and specification of JSON:API make it transferrable to projects no matter what platform they run on.

Netlify, Next.js for Drupal, and Cache Control

Next, we connected Next.js for Drupal hosted on Netlify to our Drupal application. Next.js for Drupal comes with an API layer for talking to Drupal from Next.js over JSON:API. This makes it easy for frontend developers familiar with Next.js (but maybe not so much Drupal) to jump in and construct a Next.js site rather quickly while pulling data and assets from Drupal over simple-to-use routes that return JSON.

Related resources (taxonomy, media, or other referenced entities) on content can be pulled using similar simple APIs in Next.js for Drupal that in many cases just require a resource type and its UUID, all of which are provided in the JSON:API response from Drupal for any content that’s requested.

The Next.js module comes with a plugin layer for revalidating (or re-generating) content on the Next.js headless site keeping things relatively synced whenever individual content is created or updated. However, sometimes, we need to regenerate the entire site due to global changes that touch every page.

For caching and on-demand rebuilds, we updated the Netlify module to handle this process automatically and added a way for site editors to regenerate the headless sites on-demand if something isn’t correct. You can read all about what we did for that companion module for Netlify.

Putting it all together, we have a way to retain the best of Drupal for CMS capabilities combined with the headless nature of a Next.js website.

Want to know more about how you can achieve this setup yourself? Reach out. Our team of Drupal experts would be happy to answer any questions you have.