How should you decouple Drupal?

With RESTful web services in Drupal 8 core, Drupal can function as an API-first back end serving browser applications, native applications on mobile devices, in-store displays, even in-flight entertainment systems (Lufthansa is doing so in Drupal 8!), and much more. When building a new website or web application in 2016, you may ask yourself: how should I decouple Drupal? Do I build my website with Drupal's built-in templating layer or do I use a JavaScript framework? Do I need Node.js?

There is a lot of hype around decoupled architectures, so before embarking on a project, it is important to make a balanced analysis. Your choice of architecture has implications on your budget, your team, time to launch, the flexibility for content creators, the ongoing maintenance of your website, and more. In this blog post, I'd like to share a flowchart that can help you decide when to use what technology.

Decoupled decision flowchart

This flowchart shows three things:

First, using coupled Drupal is a perfectly valid option for those who don't need extensive client-side rendering and state management. In this case, you would use Drupal's built-in Twig templating system rather than heavily relying on a JavaScript framework. You would use jQuery to take advantage of limited JavaScript where necessary. Also, with BigPipe in Drupal 8.1, certain use cases that typically needed asynchronous JavaScript can now be done in PHP without slowing down the page (i.e. communication with an external web service delaying the display of user-specific real-time data). The advantage of this approach is that content marketers are not blocked by front-end developers as they assemble their user experiences, thus shortening time to market and reducing investment in ongoing developer support.

Second, if you want all of the benefits of a JavaScript framework without completely bypassing Drupal's HTML generation and all that you get with it, I recommend using progressively decoupled Drupal. With progressive decoupling, you start with Drupal's HTML output, and then use a JavaScript framework to add client-side interactivity on the client side. One of the most visited sites in the world, The Weather Channel (100 million unique visitors per month), does precisely this with Angular 1 layered on top of Drupal 7. In this case, you can enjoy the benefits of having a “decoupled" team made up of both Drupal and JavaScript developers progressing at their own velocities. JavaScript developers can build richly interactive experiences while leaving content marketers free to assemble those experiences without needing a developer's involvement.

Third, whereas fully decoupled Drupal makes a lot of sense when building native applications, for most websites, the leap to fully decoupling is not strictly necessary, though a growing number of people prefer using JavaScript these days. Advantages include some level of independence on the underlying CMS, the ability to tap into a rich toolset around JavaScript (e.g. Babel, Webpack, etc.) and a community of JavaScript front-end professionals. But if you are using a universal JavaScript approach with Drupal, it's also important to consider the drawbacks: you need to ask yourself if you're ready to add more complexity to your technology stack and possibly forgo functionality provided by a more integrated content delivery system, such as layout and display management, user interface localization, and more. Losing that functionality can be costly, increase your dependence on a developer team, and hinder the end-to-end content assembly experience your marketing team expects, among other things.

It's worth noting that over time we are likely to see better integrations between Drupal and the different JavaScript frameworks (e.g. Drupal modules that export their configuration, and SDKs for different JavaScript frameworks that use that configuration on the client-side). When those integrations mature, I expect more people will move towards fully decoupled Drupal.

To be performant, fully decoupled websites using JavaScript employ Node.js on the server to improve initial performance, but in the case of Drupal this is not necessary, as Drupal can do the server-side pre-rendering for you. Many JavaScript developers opt to use Node.js for the convenience of shared rendering across server and client rather than for the specific things that Node.js excels in, like real-time push, concurrent connections, and bidirectional client-server communication. In other words, most Drupal websites don't need Node.js.

Decoupled delivery architectures

In practice, I believe many organizations want to use all of these content delivery options. In certain cases, you want to let your content management system render the experience so you can take full advantage of its features with minimal or no development effort (coupled architecture). But when you need to build a website that needs a much more interactive experience or that integrates with unique devices (i.e. on in-store touch screens), you should be able to use that same content management system's content API (decoupled architecture). Fortunately, Drupal allows you to use either. The beauty of choosing from the spectrum of fully decoupled Drupal, progressively decoupled Drupal, and coupled Drupal is that you can do what makes the most sense in each situation.

Special thanks to Preston So, Alex Bronstein and Wim Leers for their contributions to this blog post. We created at least 10 versions of this flowchart before settling on this one.


Anoop John (not verified):

Don't we have to also consider the aspect of maintenance and ongoing feature development? Fully decoupled is effectively two applications and feature development would require modifications in both applications and this could have an impact in the ongoing maintenance cost as well right?

One of the reasons cited by a client who wanted to move to the fully decoupled was that they would be able to have vanilla HTML/CSS/JS developers change the interface as and when needed without having to depend on a Drupal developer and HTML/CSS developers were easier to find than Drupal developers.

Anoop John (not verified):

Thanks Sean for sharing the link. That was almost like a small wiki with enough links to read for a week. Fabulous job in compiling, organizing and sharing the content for everybody.

Sean Smith (not verified):

Thanks John. I hope to stay up on this very important topic. I'm really excited to see (and help with) solutions emerge for headless D8. I plan to update this track every quarter or maybe even monthly as I have time, so check back sometime!

Once we give up on the silly notion that we have to put up with stateless connections are for web applications (and return to 90's era client-server sockets based apps...but in a browser)...then we'll finally be off to the races again!

dalin (not verified):

The challenges of Progressive Decoupling (small talent pool, increased complexity of the stack, spending time learning the toolset rather than bringing value to the project, etc.) can often be avoided by instead using Styleguide Driven Development:…

This approach allows you to keep all the goodness of Drupal (accessibility, a great form API, etc.) while still having the benefits of decoupled front-end/back-end teams, and a higher velocity than you could expect from Progressive Decoupling.

Matt Davis (not verified):

Very interesting article. This approach actually dovetails nicely with the TWC progressive decoupling model.

I'm curious if you've heard anything about the Kalastatic rapid prototyping model being developed by Kalamuna? I am in discussions with one of their architects exploring the possibility of making the component ingestion used by TWC's Presentation Framework work with their styleguide prototyping system as well.

Matt Davis (not verified):

The Weather Channel implementation of progressive decoupling is moving towards JavaScript framework agnosticism, as well, which I think is a key aspect of ensuring such an architecture can survive through the quickly-evolving javascript landscape of today.

The site already works today with either Angular 1 or Angular 2 being selected on a per-page-variant basis in Panels, but is being expanded to accommodate other frameworks as well. This will allow front end developers to innovate and experiment with new technologies as they appear.

Rob Koberg (not verified):

FWIW: Focus on the CMS and a fully decoupled delivery mechanism. That is what is missing from the market. Make it easy to publish static-like JSON content to things like an S3, Firebase or some custom DB that is used in an end-user facing site. Then think about semi-decoupled and coupled delivery, if you must. (Three separate "core" components/layers. Hopefully, that "architecture" can speed drupal's glacial development pace.) Think of drupal as a web-based CMS tool first and foremost that can feed a modern website rather than something used for the end-user facing website. It is excellent at being a CMS.

Darko Kantic (not verified):

There is another way to decouple, not just with JS frameworks, a HTML generators will generate static HTML version of your site, than for interactive part of the site you can use JS with AJAX and calls to RESTful services of your Drupal back end. Advantage of this architecture is that HTML version of the site is on the public, lightweight server, while your real site is on a different domain, but secured and only accessible to editors.

I wrote more on this in my blog…


Good point, Darko. You could even decouple using a PHP front-end. :)

Peter (not verified):

Thanks for this blog, very good architectural overview - your iterations were worth it!