👩🏽‍🍳 Bake a decoupled starter Gatsby 🥧 pie with Drupal filling

We'll look at these plugins

1. Gatsby-Source-Drupal

2. Gatsby-GraphQL-Toolkit

3. Gatsby-Source-GraphQL (and, why not this one)

With the various Gatsby source plugins, one needs to consider the pros and cons of each recipe.

    We'll discuss benefits and caveats such as caching and scaling sites that use many Paragraphs types with nested content. We won’t do step by step install instructions, as those are in the various repos, but we will point you in the right direction.

    Let’s just prepare ourselves. Decoupling Drupal is exciting and at the same time, a daunting task. When we remove the Drupal frontend, we need to handle and recreate basically everything. So we need to plan this out as we no longer have Drupal forms or validation, nice friendly public/private file URLs or authentication (if you need to have users logged in to edit their profiles etc).



    You also need to consider how you’ll host the Drupal backend and then how you will build and host the frontend. 

    Lastly, you’ll need to set up a fast “live” preview of content changes for editors. 

    We are not going to talk about the logged in Admin theme UI in this blog post. See this Admin UI Javascript initiative for more. 

    Remember, Gatsby is a static site generator ++. In Drupal, when you edit and save a node, it is generally visible immediately to the public (perhaps not as quick if there is serious caching going on) but you know what I mean. 

    With decoupled Drupal, when a node is edited, we need to tell the build system about the change, this then runs a new build, which pulls in all or only new content (see incremental builds) into Gatsby’s GraphQL node store, from a source (in this case Drupal JSON:API or GraphQL endpoint).

    Read more:

    Gatsby then renders each page’s HTML. Once all the pages have been generated, these files are uploaded to a host and that build version is made live automatically or manually. Depending on the method and ingredients you use, this can take a few minutes or a lot more minutes++.

    An image of a longer build and deploy time

    So you need to consider this in your decisions and processes. For you, the site’s speed may be more important for visitors than the backend editorial experience, as in the time it takes for the editors to preview new changes and see them go live.

    Services services everywhere


    We’ve used various combinations and can recommend either going the full Gatsby Cloud route for building and/or hosting, or self-hosting the build on Lagoon (via amazee.io) and then uploading the build to Netlify (which you can also do from Gatsby Cloud). There are many more options, so it's recommended to do some research to find out which will work best for your needs and budget.

    Some obvious wins are that Gatsby is super fast and it's very secure as it's a “static” site. Combine this with Fastly CDN and you’ve got lightning!

    Developing with Gatsby/React with GraphQL is also a great developer experience. If the maintenance team is doing backend updates or the backend server is restarted for some reason, the frontend is not affected by it during the maintenance period (unless you're doing realtime isomorphic fetching of data from said Drupal server).


    With that out the way, let’s get started by looking at the ingredients:

    • Latest Drupal Version
    • Latest Gatsby Version


    1. Gatsby-Source-Drupal

    • Will require Gatsby Integration on the Drupal side.
    • This project enhances the experience of your Drupal content editors for Gatsby sites using Drupal as a data source. This module provides Gatsby live preview capabilities using your Gatsby Cloud Preview account or on your locally running Gatsby development server.
    • Read instructions to set this up. Further modules mentioned here enhance the experience.
    • You’ll need JSON:API enabled

    2. Gatsby-GraphQL-Toolkit (more for the developer)

    • Will require Drupal GraphQL version 4 (allows for custom Schema definition) or version 3 which exposes all content types and fields (but isn’t as fully featured as version 4).
    • At Amazee Labs, we use this in our “Silverback” tech stack where we’ve made a customised set of source plugins and a custom Gatsby module with all the bells and whistles. 
      if you'd like us to help you use this!

    3. Don’t use Gatsby-Source-GraphQL (deprecated)

    • TL:DR - Historically Gatsby suggested the gatsby-source-graphql plugin to consume data from remote GraphQL APIs. 
    • This plugin is easy to use, but it has a significant problem: it doesn't adhere to the original Gatsby architecture, which makes data caching impossible. As a result, it doesn't scale well, and can't work with Gatsby Preview or Incremental Builds by design (more technical details).
    • Also, with gatsby-source-graphql you can't leverage the power of Gatsby transformer plugins like gatsby-transformer-remark or gatsby-transformer-sharp (and it's hard to use with gatsby-image as a consequence).
    • Source:  https://github.com/gatsbyjs/gatsby-graphql-toolkit#why-not-gatsby-source-graphql


    Quickstart with these nifty “Starter repos” from Gatsby:

    Hosting on Patheon and Lando locally:

    Self Host with Docker for local:

    Each repo has a set of instructions, with additional options.

    What you’ll end up with, with the above demo, is a Drupal 9 site running and a basic Gatsby homepage with 2 or 3 other content pages. The original authors used various content types to show you how to pull the data with GraphQL queries into Gatsby from Drupal.

    Now some thoughts


    In my experience, I’ve used the Paragraphs module a lot in previous sites. This can be a great content editor experience, but can get tricky when you have many Paragraphs types and nested paragraphs. What we’ve seen happen is that when Gatsby pulls in the data to its own GraphQL store during build time, if a page has loads of nested paragraph contents the build process can timeout when Drupal is responding to the extra long query with JSON:API or even GraphQL. This can lead to extra long build times or several build failures, which is not ideal. There are some workarounds and environment variables you can set, but generally you’ll want to be cautious. 

    We’ve successfully been using the Drupal Gutenberg editor which allows rich, multimedia, drag and drop type editing, right inside the WYSIWYG editor. When this is pulled from Drupal to Gatsby it is just a single short query with a chunk of HTML in response, rather than a large nested query and loads of data.

    Serving Files and SEO:

    You’re going to want to think through your hosting strategy around serving files. As your Gatsby site will be on a domain like www.yoursite.com and Drupal on a subdomain like content.yoursite.com with your public “Drupal based” files on content.yoursite.com/sites/default/files or a CDN / proxy, you may need to think of the SEO impact. There are many opinions on this, but it's generally agreed that you could potentially lose trust if the files are served from a different domain (sub-domains are seen as a different entity). You can set up some redirects to mitigate this.

    At the same time, make sure your WYSIWYG content links are not set to the Drupal site, but rather set relatively so that when they’re displayed on Gatsby they are using the Gatsby site’s URL. 

    Checkout Adding SEO components and Adding page metadata for info on adding meta tags to your site and some more plugins that help with this.

    Different ways to bake this pie

    For further reading and different ways to bake this pie read on.

    At Amazee Labs, within our Silverback project, we use a custom source plugin made possible with gatsby-graphql-toolkit and a custom Drupal GraphQL schema which allows us more control of the data that is requested and its shape. Within this, we also can set and monitor builds, previews and make overall improvements for a streamlined process. 

    If you’d like to learn more about this or have us implement this in your project, give us a call or send us a message.

    I’d quickly like to mention the workshop spoken about in our Gatsby Conf 2022 Recap, called Decoupling Drupal Using Gatsby: A Crash Course by Jesus Manuel Olivas. We used stock standard Gatsby source plugins and example Gatsby code supplied here and full workshop video

    To end off, Gatsby just had a great webinar called “The path from Drupal to Drupal+Gatsby”. See the video here. Gatsby also just added a blog post on this subject.

    I hope that was a tasty pie and that the recipe worked for you!

    Amazee Silverback Tech Stack

    At Amazee Labs, we have an open-source tech stack that allows us to build the best web solutions for a wide range of projects and industries. This innovative approach to combining cutting-edge technologies means we provide you with top-quality interface solutions that drive business goals.

    Stay in the Loop

    We will use the personal data you are sharing with us solely for the purpose of sending you our newsletter. See more here: Data Privacy.


    Let us know how we can help you.