Drupal will always hold a special place in my heart. The first website I ever built for someone else was a Drupal 6 site shortly after it was released. I’ve been around for countless Drupal Camps and Cons, major version upgrade pains, and I’ve always stuck around for the community. When I first heard of Gatsby I was skeptical at first as it seemed like just another static site generator. However, after spending time developing with the framework, I quickly realized Gatsby was so much more and could be used to build very dynamic sites that load almost instantly. I guess it was fitting that my first Gatsby site used Drupal as its CMS.
When I published the first development version of the Gatsby Drupal module I didn’t realize how that would change the path I would take with my career. I worked closely with the Gatsby team, improved the module, and eventually joined Gatsby as an engineer to focus on improving Gatsby’s integration with Drupal. Eventually, I moved into engineering management and continued to work on improving the site-building experience with Gatsby and Drupal. Throughout talking to countless customers building Gatsby sites with Drupal I have come up with a collection of tips and best practices that I’ve found useful when working on a Gatsby site powered by Drupal content.
JSON: API is the path of least resistance
The most common question I get is if the GraphQL module should be used. The simple answer is no! The more complicated answer is you should always default to using the JSON: API module unless you know what you are doing and have a really compelling reason to use the GraphQL module. A few years ago there were a few compelling reasons, lately, this isn’t really the case.
The reason that JSON: API is the correct path for most use cases is that it is where development started and where most of the effort and improvements have been over the past few years. If you want things like really fast incremental builds and an instant preview experience, you need JSON: API alongside the gatsby-source-drupal module. There are still a few very edge case reasons where the GraphQL module might make sense, however, with some improvements coming in the near future all of those reasons will be going away.
Now that I have convinced you that using Drupal’s JSON: API module is what you should be using I will tease that we have some far-future ideas where we might revisit this position!
Always use JSON:API Extras
I wouldn’t build a Gatsby Drupal site without using the JSON:API Extras module. By default JSON:API provides links to every possible entity type on your Drupal site. This is great as a no-configuration API, however, you probably don’t care about pulling in things like your Drupal admin settings into your Gatsby site. If you enable the JSON:API Extras module you can disable all of the entity types that you don’t want your Gatsby site to worry about. This will speed up your build times because gatsby-source-drupal traverses every link available in JSON:API.
Use the Gatsby Module! (Your Content Editors Will Thank You)
The Gatsby Drupal module was designed with content editors in mind. It integrates nicely with Gatsby Cloud and ensures that your content editors can preview their unpublished content before it goes live. It also enables incremental and cloud builds, which allow you to publish your content in seconds even on the largest Gatsby/Drupal sites.
For Faster Sourcing: Keep JSON:API public, Don’t Use Authentication in gatsby-source-drupal
Part of the Gatsby process is that it needs to pull down all of the data from Drupal’s JSON:API (at least the first time). This can be a time-consuming process. If you can keep your JSON:API public and not use authentication in gatsby-source-drupal, you will be able to take advantage of Drupal’s caching to speed up your sourcing. This can be especially important when developing locally as a cached JSON:API request is much faster than an uncached request! Sometimes you need to use authentication (possibly for viewing unpublished content for previews). In that case, you might still be able to keep your production builds without authentication. After all, the data that you are exposing in your Drupal site is likely being used on a public Gatsby site so the API should be okay to be public!
Use Fastbuilds for the Win
So we just made sourcing a little faster, but we can do more. The gatsby-source-drupal plugin has a Fastbuilds option that coincides with the Gatsby Drupal module. The way it works is that the Drupal module logs content that changes on the Drupal site and when Gatsby runs, it only syncs content that has changed since the last build. This means your local development builds can speed up dramatically. There is also a way to use this Fastbuilds feature for your incremental and preview builds which provides a much more reliable experience on Gatsby Cloud.
Use gatsby-source-drupal Plugin Options to Unlock Even More Performance Gains
There are some other gatsby-source-drupal plugin options that often fly under the radar and can help you with some tricky situations that might be slowing down your builds. A fairly common situation is when you are using Drupal’s theme engine for part of the site, but want to create a new section of the site powered by Gatsby. Often the plan is to move all of the site over to Gatsby over time. In this situation, your Drupal site might have a lot of content and media files that are not actually used on your Gatsby site. On top of that, you often have orphaned files that are no longer attached to any content but are still in your Drupal site. While you can use JSON:API extras to disable content you don’t care about in Gatsby, you can’t selectively disable downloading of media files that are not used. This means you get all of the files or none of the files!
There is a solution though! If you combine a few plugin options together, you can set it up so Gatsby will only download files that are connected to the content that you are using within Gatsby! The first step is to add file–file to the disallowedLinkTypes plugin option. From there, you need to specify each content type that you want to download in the filters plugin option. You also need to specify what additional fields you want to include. Let’s assume you only want articles from your Drupal site and you want the image field that has a field name of field_image. You would need to add this to the filters option:
filters: {
"node--article": "include=field_image"
}
This would not download or process any images by default and then would only download the image files that are attached to articles through field_image. This allows you to be very specific about the data that gets pulled into Gatsby.
Note: This trick can be used for things like shared paragraph components as well (an example is provided in the documentation link above)!
Image CDN for Drupal Sites is Coming Soon
Gatsby Cloud recently released Image CDN which improves the image processing pipeline for Gatsby sites. While it hasn’t been officially released for Drupal yet, it’s already being tested on live sites and will be released soon. This provides a number of great benefits for your Drupal site. Your production and preview builds will no longer need to go through downloading all your images from Drupal at build time. This will dramatically speed up builds on Gatsby Cloud. On top of that, it has the hidden benefit of making local development so much faster! Before, you would need to download every image that your Gatsby site uses locally before your development server starts up. For really large sites this means you might have to wait 5 or 10 minutes the first time you run your development server locally. Your subsequent builds can be cached with the Fastbuilds option, but during development, things change often and you need to start fresh frequently.
Even if you are not using Image CDN on your production site, if you use the new options that come with Image CDN (once it’s available for Drupal) you can completely bypass the need to download your media files locally during development. This will drastically speed up your development process!
Closing Thoughts
If you want to see what else I am up to, make sure to follow me on Twitter @smthomas3. If you want to chat more about Drupal, I’m codekarate in the Drupal Slack (most often found in the #gatsby channel).