Decoupled Drupal, Demystified

We’ve been thinking about decoupling a lot lately — no, not that thing Gwyneth Paltrow did a few years ago. We’re talking about decoupled Drupal: It’s a new way of building websites that requires some additional work but can help you future-proof your next site or redesign.

It’s not as scary as it sounds — and we’re here to help you understand it. We love to talk about the future of Drupal — we’ve also written some tips for developers using Drupal 8. In fact, several BSDers even attended Decoupled Drupal Days recently. But not everyone even knows what Drupal is, let alone “decoupled Drupal” — no matter how many times they’ve heard their developer colleagues talk about it.  

Here’s a quick primer on Drupal, decoupling, and how to know if these are things your organization needs.

What is Drupal? Wait, back up, what is a CMS?

Drupal is an extremely popular open-source content management system (CMS). A CMS is a software application (or suite of applications) that enables administrators to enter and maintain everything a website needs to display content: titles, bylines, body copy, graphics, thumbnail images, tagging, metadata, and more.

A traditional CMS both manages that database of content and metadata and generates the code that tells the end user’s web browser how to display it properly.

What is decoupled CMS?

A decoupled CMS (sometimes known as a “headless CMS”) manages the database of content but leaves formatting and displaying it to the user or to a separate piece (or pieces) of software. They are connected via an API, which is a fancy name for something that allows two pieces of software to talk to each other — which, as we’ll discuss more below, is particularly useful when you want to be able to format and display content in different places or on different devices.  

Here’s an analogy: Say you’re writing a book. You need to lay out the title and content of the book, and to structure the body into chapters with chapter titles, etc. When it comes time to publish the book, you want to be able to print it in both hardcover and paperback, and to make it available via Amazon Kindle. Maybe you want to make the table of contents or introduction available on your website. You don’t want to re-enter the content each time you need to make it available in a new format — you want the place where the content lives to distribute the data and let typesetters and websites format and display it as they see fit.

Now, apply that thinking to your website: Making your decisions about how to structure your content data separately from how it will be displayed to your audience gives you increased flexibility over the user experience. Decoupling isn’t specific to Drupal, but the latest version of Drupal made a content API a core feature of the CMS, which means that it is explicitly built to support a decoupled architecture in addition to traditional Drupal theming.

What’s the advantage of a decoupled CMS?

Decoupled Drupal is becoming increasingly common as new methods of content distribution continue to proliferate. Let’s say you publish an article to your website, but you also want that article accessible through your organization’s native iPhone app. Plus, you want to be able to take advantage of newer mobile-web publishing formats like Google AMP and a Facebook Instant Articles.

Decoupling can help you future-proof to a certain degree because it allows you to collect and organize your content once, without needing to change the back-end to support new channels. Each channel gets its own “front-end” without adding to the complexity of the CMS itself, which can bog down the content management process and make future development more difficult. When the next new “instant” publishing format rolls around, you’ll be ready to adapt quickly.

This trend also speaks to a core BSD belief: Creative should feel native to whatever device or platform on which it’s viewed by users.

What are some of the disadvantages of a decoupled CMS?

Decoupling may sound great, but it does present a few potential drawbacks:

Search Engine Optimization (SEO)

SEO can be less straightforward with decoupled architectures because search engines can’t read client-side-rendered content as well as server-side-rendered. E-commerce might also suffer from that, but we think of SEO as more of a front-line concern for content sites.

If you go with a decoupled site, you’ll need to do one of a couple of things: have Drupal serve up a basic content rendering which search engine crawlers can read, but which gets replaced by your desired front-end in the browser; or, introduce a server-side rendering layer, which moves most of the decoupled “front-end” to the server, simplifying what actually happens in the browser and making sure that crawlers can read your pages easily. Either approach preserves most of the benefits of decoupling but will require additional effort.

Increased complexity

When you rewrite your front-end from scratch, you’re giving up a lot of things baked into your CMS’s presentation layer by default (see “SEO” above). This may be self-explanatory, but a decoupled architecture also requires you to figure out how your front-end (or various distribution channels) interacts with your back-end CMS. That also means you need Drupal experts to configure your CMS and front-end developers with totally different skill sets (for example, Javascript) to create the actual end-user experience.

What are some helpful tools or documentation for decoupled Drupal?

We’ve got a few in mind. React for Drupal is a library of resources that helps you create nice front-end experiences for your Drupal-based content. Our friends at Acquia have even created a starter kit for React to get decoupled Drupal projects off the ground. You can also check out GraphQL, a query language that provides an elegant way of pulling content and data into your front-end. There are even a few customized Drupal distributions — preconfigured versions of the Drupal software — made to facilitate decoupling, like Contenta and Reservoir.

Do I need to use Decoupled Drupal for my next project?

As a rule of thumb, projects with more complex front-end requirements (complex distribution channels; interactive features; modules that need to maintain a state, like a shopping cart or “recently viewed” list) are good candidates for decoupling.

Another key consideration is distribution channels for your content. If you have an app or chatbot, or if you rely heavily on “instant page” formats like Google AMP or Facebook Instant Articles, you might want to decouple your CMS to avoid bundling all of that into the same bulky platform. Sites where there are dynamic relationships between articles (for example, if you’re making extensive use of a taxonomy through searching, filtering, and pagination) also tend to be better handled dynamically.

It’s also not necessarily all-or-nothing. “Progressive decoupling” allows you to leverage some of the benefits of decoupling for certain features of your site, such as search, while leaving the rest of your architecture intact.

All of this is just scratching the surface. There’s so much more about CMS architecture and Drupal to discuss. But decoupling isn’t going anywhere — it’s only becoming more popular as content formats and types of devices proliferate. We, for one, welcome the new decoupled paradigm.


If a decoupled CMS sounds right for your next project — or you just want to talk about website architectures with us —  let’s chat.