Building a Gatsby Decoupled Drupal Site

New web technologies seem to always come out of no where, and the headless website was exactly that for me. I got the chance to go to DrupalCon Seattle, and while I saw plenty of the expected panels on the complicated parts of Drupal, something else stood out: headless and static generators. When you're in the deep end supporting and building Drupal sites for clients, you don't get to experiment. You build the site you were paid to build. So I want to share the thoughts of what I found most fascinating during the build of the site you're on, while relating it back to traditional full-stack Drupal builds.

Going Simple

I settled on doing my portfolio since I've never really built one before, even though I recommend building a portfolio to every CompSci graduate. Such a site didn't need to be built with a CMS, but this is about showing off on all aspects. Can't hold back on using the new technologies, I'm now my own client setting my own requirements.

I copied my typical Drupal 8 composer template and installed it on my personal server, and started on the content. I wanted to settle on super simple content types, powered by body fields written in markdown. This was a huge benefit of headless in my eyes, being able to cut out CKEditor formatting and being able to write in Markdown. There was so little configuration I felt like I was missing something very important. But no, a headless Drupal instance is very easy to setup, all while being very snappy and intuitive editing.

Hello Again, React

I've worked with React before but it was with basic components that were just additional UI to an already existing site, never a whole site. But just as I remembered, React is very intuitive to develop for, it's no surprise it became as popular as it did. Gatsby also follows very simple and powerful ideas for site building using GraphQL.

When pages are as simple as:

import React from "react"
import { Link } from "gatsby"

import Layout from "../components/layout/layout"
import SEO from "../components/utils/seo"

const NewPage = () => (
    <div className={"container form-submission-page"}>
      <SEO title="New Page" />
      <h1 className={"title"}>New Page</h1>

      <Link className="button button--cta inversed" to={"/"}>Return Home</Link>

export default NewPage;

I found myself making the prototype faster than fiddling around with Drupal's display settings. That's high praise since I've been using Drupal since I was in middle school, almost 10 years! Of course this takes a lot of control away from a Drupal admin, but it's in places that rarely get used after a site is built, like block layouts. I don't remember the last time I ever modified my block layout substantially post-launch of a website. In addition to that, settings like blocks are tracked in config and require developer intervention regardless. Putting those concepts into JS makes sense from that perspective.


In Drupal, one of the most powerful things you could possibly use is Views. It allows us to build a variety of entity listings with all their crazy relationships. For Gatsby we can use something called GraphQL to build pages where we'd use Views. So for my projects page instead of creating a view, I wrote the following query

  query ProjectsPageQuery {
    allNodeProject (
      sort: {
        fields: field_date
        order: DESC
    ) {
      edges {
        node {
          field_link {
          body {
          relationships {
            field_technologies {
            field_logo {
              localFile {
                childImageSharp {
                  fluid(maxWidth: 512, maxHeight: 512) {

This stack of braces ends up describing the fields and relationships I want to build my query, and then use them in my React component. Very similar to how I would build my Views pages in Drupal. While these are things you would see on any Gatsby recap, I just found it insanely interesting in how most of what I found neat with Views can be done just with this query language. It's insanely powerful without needing to do multiple REST calls per relationship or crazy SQL joins.


Finally there always comes a time to push a site live. When talking with the Gatsby folks at DrupalCon, I found that most people used a service called Netlify. While giving a few restrictions on what their platform could do, it is a very neat host that does get Gatsby public and fast for free. I appreciated this as I was able to push things live quickly to get opinions from trusted individuals on how the build was coming along. This is of course nothing I couldn't do with other Drupal host, but it was good to know that the option and ecosystem was there. Though using Heroku, or even just posting to GitHub pages using a CI wouldn't be difficult.

As a closing thought, a Drupal module that I would like to build though would be to give a editor more control and feedback from a publish, right now the best option is to use webhooks, and I'm not a fan of how little feedback it gives the user about their site, but it's a small price to pay for how fast your site ends up being compared to full-stack Drupal.