We'll look at these plugins
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.
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).
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++.
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
- 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.
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:
- Drupal, Gatsby with TypeScript starter: (recommended if you know Typescript)
- Drupal and Gatsby JS Starter: (recommended as easiest)
Self Host with Docker for local:
- Based off Drupal and Gatsby JS Starter
- Uses Docker + Pygmy locally
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.
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.
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.