Skip to main content
Hero Background Image

Decoupling Drupal is Easier Than You Think

August 26, 2020

The Mediacurrent team has been championing “Decoupled Drupal” for a number of years and believe that this approach is a good fit for many organizations. While we still build many Drupal sites the traditional way, we love the upside of decoupling with GatsbyJS! Gatsby compiles your site into static files, powered with React for amazing performance, security and scalability. 

The important thing to know is that if your site is already running Drupal 8 and you are considering a move to “decoupled,” you do not have to rebuild your site. In this article, we will cover the key ingredients to decoupling your Drupal 8 site as well as the steps needed to make the transition. We think you will find that this solution is completely manageable and should be a strong consideration for organizations planning a redesign.

First, the Ingredients!

JSON:API module

Drupal 8, and now Drupal 9 already have everything you need to make your site “decoupled.” The key ingredient from the Drupal side of things is the JSON:API module. This core module, when enabled, converts your content to a JSON:API format which can then be consumed by other applications, like GatsbyJS.


GatsbyJS has a robust plugin system for Drupal and many other systems that makes all of your content accessible to the application via GraphQL. This allows developers who know React (and there are many) to create an amazing React-powered application without actually knowing (or caring?) about how Drupal works. We will discuss steps for transitioning to decoupled in the next section, but know that turning on this one module, in a sense, immediately enables the backend portion of your new site.


GatsbyJS is an open source package available via Github as an npm package. The only thing you have to worry about is where you are going to host your application. The Drupal side of things can stay exactly where it’s hosted now (if desired), but the application people see in the browser will actually need to be hosted somewhere else in most cases. We like Netlify as a great fit for hosting the Gatsby frontend. Netlify acts as both a global CDN and can do the “compiling” of the Gatsby site that needs to happen every time a change is made. We should note that there are several additional hosting options and integrations available in addition to Netlify.

Build Hooks

The contributed module “Build Hooks” is something that is easy to configure with Netlify in order for Drupal to communicate to Netlify when content updates are made. This allows you to rebuild the site on-the-fly or with a push of a button, depending on how you want to trigger new builds. This is an optional module, as Gatsby Cloud offers similar functionality which we will discuss next.

Gatsby Cloud

The team that created GatsbyJS has a set of tools including live preview and incremental builds that make the integration of Drupal and Gatsby seamless. Gatsby Cloud does have a cost component, but often costs more than offset hosting costs saved on the Drupal host thanks to efficiencies that Gatsby brings to the table. The biggest feature that Cloud offers is the aforementioned incremental builds process which dramatically increases the speed to get content changes live on the website.

Gatsby module

The Gatsby module is another contributed module that helps glue the Drupal CMS to the Netlify frontend. This module provides an integrated preview that updates immediately when content is saved. For smaller sites you could actually just use Netlify as the “preview” site that gets embedded onto the page, if so desired.

Transitioning to Decoupled

Enabling modules

Once an organization decides to move to a decoupled solution, there are a couple routes we can take to make the transition. At a minimum you have the option to enable the modules required to make the backend “decoupled-ready.” As mentioned earlier, enabling the JSON:API module immediately makes content available as data to a frontend like GatsbyJS.

Content modeling

The next thing to review is how well does your organization’s current content structure fit a newly designed decoupled frontend. Considering the current site was not built for this new design, there could be significant changes required. For example, if you have Drupal Views embedded across the site, those will not be exported to the frontend. Those Views will be replaced by React components that perform the same functionality using React and GraphQL. Depending on the degree of changes that need to happen it could be beneficial to move a new install profile which we will discuss next.

Install profiles

For Drupal 8 sites, it may not be necessary to start over with a brand new codebase. One way to reuse a lot of the work that’s already been done while still creating a new space for a decoupled transition is to create a new install profile. The new install profile would live in the same space, with the same modules available to install. 

Mediacurrent took this approach with a recent client that is in the process of transitioning to full decoupled and has many properties managed by different platforms, including Drupal. We started building new sites with a custom install profile with an eye towards eventually transitioning all platforms over to this profile. This is one approach organizations might consider that provides an easier path from where they are now to a fully decoupled solution.

Wrapping it Up

In this article, we discussed why moving to a decoupled solution doesn’t necessarily require a full tear-down when you are already running a Drupal 8 website (or Drupal 9 for that matter). When your organization is considering a redesign the effort to move to a decoupled solution is going to likely be pretty comparable to the effort to theme your site in Drupal. 

The Team

One thing to consider is what is the skillset of your team. If you are adding new team members you are going to find that it’s actually easier to find React developers than Drupal frontend developers. However, If you already have an established team of developers that know Drupal well but not React, there could be more time required to move to a decoupled solution.

Mediacurrent has a great team of developers, strategists, designers and problem-solvers that can help you navigate decisions like where or not your organization should consider decoupled Drupal. Contact us today to learn more about your options and we will get to work!

Related Insights

  • Headshot
  • Headshot
  • Headshot