Decoupling Drupal Without Losing Your Head — Part 1

What exactly are we trying to do here? And is there another way to do it?

Headless/decoupled Drupal has received a lot of buzz in the last year. But the rise of decoupled Drupal has also been met with due skepticism, as there are significant challenges. We’re not here to further that flame war; you can find the details elsewhere. In some specific cases, taking the decoupled approach can be worth the cost of dealing with those challenges. But in many — if not most — cases, that list of challenges outweighs the novelty of decapitation.

At Advomatic, we’ve been exploring how to achieve the same goals of decoupling, while avoiding that hefty list of challenges.

The direction that we’ve been heading is to use styleguide-driven development (SDD).

First, what do people typically mean by decoupled/headless Drupal?

In this approach, Drupal is used only as a place for administrators to manage content. The Drupal site does not actually display the content (at least, not to anonymous visitors). Instead the Drupal site makes the content available via an API. That API is used by the public-facing website, which is typically powered by a JavaScript framework like Angular.js, Ember.js, or React.js. This has many advantages, which we’ll discuss below, but this approach also comes with significant drawbacks, mainly around running two separate applications, but also a lack of contextual tools for administrators, fad JS frameworks, trouble finding skilled developers, little role for the “site builder,” and more.

Let’s also define what we mean by styleguide-driven development.

We’ll go into more details in the next article in this series, but for now, when we talk about styleguides, we are talking about a set of fully functional, reusable elements and components, built and themed outside of Drupal, using idealized markup. This includes all generic HTML elements, (headers, lists, blockquotes, etc.), native Drupal components (pagers, menus, alerts, etc.), and site-specific components (carousels, listings, features, etc.)

So what are the goals of decoupling? And can SDD accomplish them just as well?

Recently our colleagues over at Lullabot published an article describing the underlying goals of the decoupled approach. Some items on their list are related to APIs. Styleguide-driven development does nothing for your APIs. If you know that one of the primary content delivery methods for your project will be through an API, maybe decoupled Drupal is for you. If you don’t need to have an API, or if the API is going to be a second-class citizen, then decoupling could be a case of YAGNI.

I would argue that one of the goals in the Lullabot article — abstraction and constraints reduce individual responsibilities while promoting content reuse — while an important topic, actually has nothing to do with decoupling.

I’m adding another of my own, so that leaves us with this list of goals and how decoupling and SDD address each:

  • Less reliance on Drupal specialists

    Drupal has long been a market where it is difficult to attract top talent;  many people are already happy where they are. Because styleguides are built using the more broadly used tools of HTML/JavaScript/SASS (and maybe a styleguide tool like Storybook.js), we can leverage the skills of a broader variety of web professionals.  In contrast, headless/decoupled Drupal only replaces Drupal specialists with specialists of another type.

  • More self-contained upgrades

    Want to upgrade to Drupal 8 without a redesign, and only a minimal theme upgrade?  Want to revamp the look and feel with minimal changes to the back end? That’s now easier with both decoupling or styleguide-driven-development. Because the front end and back end are less tightly coupled, you can make a major overhaul to one with less impact on the other (compared to if both are a single system). We should note that at this point this is entirely theoretical. The movement is still too new¹ to see many (any?) examples of this in practice.  I anticipate that in reality stakeholders will almost always want to make changes to both at the same time.

  • Allowing front-end and back-end teams to work simultaneously

    This is where both decoupling and styleguide-driven development really shine.  In the olden days the back-end team would start building the website while the front-end team would be sitting on their hands waiting until there was something to work with.  Similarly at the end of a project the back-end team would finish up while the front-end team frantically pulled all-nighters to fix all the cross-browser bugs. In our next article of this series we’ll delve deeper into how a parallel workflow with styleguide-driven-development can look.

Ultimately, we believe that the styleguide-driven approach has the potential to meet the same goals as decoupled/headless CMS development, but it does so in a way that bypasses many of the challenges.  In the next post in this series we’ll get into the details of what exactly this looks like for a typical project.

In closing, let’s back up for a second and talk about how we should go about making decisions about which tools to use when building websites.

“Right tool for the job” – another abused one. The intention here is reasonable: who wants to use a tool that isn’t appropriate? But a rare perspective is that this can be detrimental when taken to the extreme. A carpenter doesn’t arm herself with every variation and size of hammer that is available, even though she may encounter hammering tasks that could be ideally handled by each one. Why? Because lugging around (and maintaining) a gazillion hammers incurs a cost. As such, decisions on this axis have trade-offs.
John Allspaw

It’s both too expensive to try and build everything with the same tool, or to learn a new tool for every project.  At the same time, some tools only work for a very narrow use-case, while some tools can be used for a broad range.  Are we hitting the limits of what we can do with small chunks of HTML, CSS, and (minimal) JS?  How far can we take the styleguide approach?  We see the future looking very bright, both in terms of where the web community at large is headed, and at Advomatic we have some ideas for how we can make components more reusable across Drupal projects (look for a future series of articles on this topic).


1. The idea of a decoupled website had some degree of popularity way back in the late 90s, but the flavour that we see now is different enough that it’s difficult to draw many meaningful comparisons.

Thanks to Amanda, Jack, Oliver, and Kim for collaborating with me on this.

Other posts you should check out

Looking for a central resource for all things decoupled?  Pantheon just launched an awesome resource for decoupled CMS.