The Netlify Module for Drupal
The combination of headless Drupal and modern hosting platforms has unlocked new levels of flexibility for hosting websites. By decoupling the front-end and back-end, a headless setup allows developers to use a content management system like Drupal purely for content creation while leveraging modern front-end frameworks for dynamic user experiences.
Netlify offers an ideal solution for hosting headless Drupal websites because it seamlessly integrates with this architecture, providing automated deployments, serverless backend functions, and a global CDN to ensure that your headless site is not only fast and reliable but also easy to manage and scale.
This year Velir has worked with Drupal 10 to enable headless website development. We’ve used Layout Builder and JSON:API to expose content and data services in Drupal consumed by Next.js and hosted by Netlify.
With this setup, we encountered an issue with HTTP response caching in Next.js that prevented our headless website on Netlify from reflecting updates without a build deployment in Netlify. In this post, we’ll explain how we solved these issues in Drupal.
How Netlify and Next.js Work
Next.js is a React framework that helps developers build web applications. Next.js for Drupal is a framework for quickly integrating Drupal content into Next.js via JSON:API or GraphQL. When the front-end code (the headless part) is updated and committed, Netlify will pull that code, rebuild the website, and redeploy the site for visitors.
Under the hood, most core services only pay attention to changes to direct content APIs, such as updating a component or piece of text on a page being viewed. We’ve spent time creating global configurations and options in Drupal to power a headless site that goes beyond standard content. This can include a website logo, footer logos, branding colors, or other content elements that appear on every page.
We noticed that when those values changed, the headless website on Netlify didn’t reflect those changes everywhere it should. After some debugging, we validated that the API routes in Drupal returned the correct information with the correct caching headers and contexts applied. Upon further reading, we traced it back to a problem with Next.js 13 and how it caches data.
Next.js 13 aggressively caches data, both on the server and on the client. This can lead to stale data. There is no way to opt out of the client-side router cache in Next.
This means that regardless of the data source saying, “This content is new, dump your cache and take this version,” Next.js version 13 is permanently holding onto the content. This issue is reportedly fixed in Next.js 15, but we cannot update it yet, so we spent time finding a reasonable alternative.
The Netlify Module for Drupal
The one way to guarantee our website would reflect global changes was to log into Netlify and trigger a deployment. The fastest path through this issue was developing a way to run a deployment in Netlify remotely from Drupal, whenever configuration or content was updated for authors and developers. Fortunately, Netlify can create a “webhook,” or a URL you can hit to instruct it to rebuild the headless website.
In Drupal, there is an Event we can subscribe to whenever a configuration object is saved. By subscribing (listening) when that Event is fired, we could quickly wrap a service that triggered Netlify to rebuild the headless website. We also created our own custom Event to fire whenever content was saved to do the same action. This ensured any changes would be reflected on the website as soon as possible.
We also went a little further. Sometimes you may want granular control over what triggers this action since not all content or configuration is related to the headless website. Options will exist that allow you to specify which types of content will trigger a deployment, and aren’t limited to just Nodes.
Additionally, we added a button in the caching area in Drupal so you can trigger a deployment on-demand without saving anything at all.
In a future release, we’re working to incorporate an automated job that will ensure Netlify builds at regular intervals to prevent stale data from appearing to users.
This will enable a Drupal site that uses Layout Builder to arrange components and layouts and render that data in a headless website like Next.js or Vue. We’ll detail how we exposed Layout Builder data over JSON:API in an upcoming blog post.
Want to try out this solution? We contributed it to version 2.x of the Netlify module for Drupal.
Need help getting started or understanding more about how it works? Reach out. Our team of Drupal experts would be happy to assist you.
Get the Drupal 10 Development Cookbook
Drupal just released version 11, but if you’re not ready to upgrade yet, you should make the most of the current version by picking up a copy of the “Drupal 10 Development Cookbook.”
The "Drupal 10 Development Cookbook" is co-authored by Matt Glaman and me, Kevin Quillen. We cover a wide variety of topics with hands-on examples so you can get up and running with Drupal 10 in no time. These topics include running Drupal locally with Docker-based tools, content modeling, creating custom modules, how to do automated testing, and migrating data into Drupal from various data sources. The book will help you understand how to develop and build modules just like the ones we talk about often at Velir.