How to Get Gatsby to Work with Drupal: Building a Gatsby Site with a Decoupled Drupal Back-End

Just imagine: putting together the powerful UI creation tools of a static site generator — more of a modern front-end framework rather —  built for high speed, like Gatsby.js, with Drupal 8's content modeling and access system! Putting their powers together into a blazing-fast website! But how to get Gatsby to work with Drupal?

How do you build a plugin that fetches data from API-first Drupal? In short: a static, conveniently simple, yet robust Gatsby site powered by a powerful, decoupled Drupal back-end?

You've got the questions, we've got the answers...

And we've grouped all our answers to your questions regarding “API-first and decoupled Drupal in connection with Gatsby” in a straightforward 4-step tutorial. One on building a high-speed Gatsby website backed by a versatile headless Drupal CMS.

Shall we dig in?
 

1. But What Is Gatsby.js More Precisely?

The standard, rather rigid definition would be:

“It is a GraphQL-fueled, React-based static site generator.”

Now if the words “static site generator” just make you... cringe, here's a more nuanced definition for you:

“Gatsby's more of a modern front-end framework —  one pulling together the best parts of GraphQL, React, webpack, react-router — built with the developer experience in mind.”

In short: it's a static site that this “more than just a static site generator” helps you build, leveraging its out-of-the-box front-end tools. A website geared to reach fast page loads while pulling data from a decoupled Drupal CMS.

And there are 2 basic steps for getting started with Gatsby. You simply write your site's code structure and let Gatsby handle the rest:
 

1. turn it into a directory with a single HTML file
2. … along with all your static assets

2. 3 Reasons Why You'd Want to Use Gatsby

… instead of Jekyll, your webpack config or create-react-app.
 

a. Because of the richness of the Gatsby ecosystem

With rich documentation at hand and backed by an already large community of starters, you'll get your Gatsby site up and running in no time.
 

b. Because it leverages GraphQL' power to build its data layer.

And this is one of those heavy-weighting reasons for using Gatsby over other competing alternatives:

Gatsby's built to fetch data from... pretty much anywhere — your CMS of choice, Markdown, third-party APIs, Markdown — using “source” plugins. When creating its data layer, it relies on GraphQL, which builds an internal server of all this pulled data.

In short: when questioning yourself “how to get Gatsby to work with Drupal”, do keep in mind that in your future Gatsby & decoupled Drupal setup data gets queried from the same place, in the same way, via GraphQL.
 

c. Because it's built for high speed.

And this is one of Gatsby's hardest-to-resist-to advantages:

It's just... fast.

And that gets reflected in your final Gatsby & decoupled Drupal site while bubbling up to the user experience, as well.

Summing up, these are the 3 strongest reasons why you would be tempted to use Gatsby with Drupal CMS. 

I'm not going to engage in dynamic sites vs static sites debate now. The internet's already overcrowded with such comparisons.

I'll just end this “pledge” on using Gatsby with a non-debatable statement:

Since a static site generator pre-generates the pages of your website, scales of performance vs maintenance costs gets unbalanced. And guess which one's going up and which one down!
 

3. And Why Would Pair Gatsby with Drupal?

If there are strong reasons why you should be getting started with Gatsby, why is there any need to consider decoupled Drupal CMS for its back-end?

Because static site generators don't “care” much for the authoring experience. Content editors have to get themselves tangled up in Markdown for creating content.

True story!

And this is where powerful CMSs, such as Drupal, step in, “luring” you with their:

• WYSIWYG editors
• content types 
• content modeling capabilities
• access workflow capabilities

… to make your content team's lives easier!

And now your “How to get Gatsby to work with Drupal” dilemma turns into a new legitimate one:

How to make your Gatsby website cope with a decoupled Drupal setup without adding the “dread” of a database and web server to the equation? 2 elements that “pave the path” for performance and security issues...

Well, this is precisely what this “decoupling Drupal with Gatsby scenario means to avoid:

• you'll get to host your Drupal CMS in-house
• … and thus take full advantage of the robustness and versatility of a decoupled Drupal CMS back-end
• your Gatsby website will fetch data from its Drupal back-end and generate content “the static way” (which translates into “incredibility fast page loads”)
   

4. How to Get Gatsby to Work with Drupal More Precisely

Or simply put: how to pull data/content from Drupal into your Gatsby website?

Here's a straightforward tutorial in 4 steps on how to integrate Drupal with Gatsby:
 

4.1. First, Build Your Drupal Server 

Assuming that you have a Drupal 8 website installed, the very first step to take is to:
 

a. Create a new content type 

For this exercise, it's a blog — including all its blog posts — that we'll try to transfer from Drupal to Gatsby. So, we'll name our content-type: “Blog”.

It will include 3 basic fields:

• title
• body
• image

Just navigate to Home>Administration>Structure>Content Types.
 

b. Turn Drupal into an API Server 

And there are 2 key modules that you'll need to install:
 

1. jsonapi_extras: for gaining more control over the API (to disable resources, to change the default endpoint, to enhance field output etc.)
2. jsonapi, which will turn your Drupal website into an API server (one having a default endpoint)
    

c. Grant Anonymous User Permission to Access the JSON API resource list

If you overlook this step, you'll end up with an “Error 406” message, which will just sabotage your whole “decoupling Drupal with Gatsby” mission.
 

d. Check How Your Drupal API Server Works 

You can do this by navigating to http://[your-site]/jsonapi logged in as an Anonymous user.

If the page that you'll get displays all the information regarding your API server, then you'll know you're on the right track.
 

4.2. Then, Create a New Gatsby Site

But before you jump to building your new static website, check whether you have npm and node installed on your PC. 

How? By entering “npm  -v” and “node  -v” into your terminal.

Next, you'll need to install Gatsby's CLI:
 

npm install --global gatsby-cli 

Then, just build and get your Gatsby site up and running.

Note: by default, it will be accessible at localhost:8000.

4.3. Decouple Drupal with Gatsby: Pulling Data from the API Server
 

a. Set up the (/blog) page

Solving your “How to get Gatsby to work with Drupal”  type of dilemma starts with... the creation of a new page on your Gatsby website.

And is as simple as... setting up a new JS file.

Note: all your Gatsby pages will get stored under /src/pages.

Now here are the basic steps to take:
 

1. create the blog.js in /src/pages
2. then add this code: import React from "react" const BlogPage = () => ( <div> <h1>Latest from our bog</h1> </div> ) export default BlogPage 
    

Voila! You've just created a new page at /blog.
 

b. Pull Content from the Drupal 8 site using GraphQL

The “gatsby-source-drupal” plugin, to be more specific.

It's this source plugin that will be “in charge” with all the data (images here included) pulling from decoupled Drupal back-end and pushing into your Gatsby site.

Note: do keep in mind that, in this case, the JSON API module plays a crucial role.

And here's how you install your “power” plugin:
 

// in your blog.gatsby folder npm install --save gatsby-source-drupal 

Next, just configure your newly installed plugin:
 

// In gatsby-config.js plugins: [ ... { resolve: 'gatsby-source-drupal', options: { baseUrl: 'https://goo.gl/Cc5Jd3 apiBase: 'jsonapi', // endpoint of Drupal server }, } ], 

Tada! Now your site should be functioning properly.

If... not quite, here are the causes of the 2 most common error messages that you could get:
 

• “405 error”, check whether the jsonapi_extras module is enabled
• “ 406 error”, have a closer look at the permission on your Drupal site
   

c. Configure GraphQL to Pull Specific Pieces of Content from Drupal

In other words: to query all the “blog” nodes from Drupal and request specific data from the API server.

Another strong reason for using Drupal CMS with Gatsby is that the latter provides an in-browser tool for testing GraphQL queries names, for writing and validating them. You can access it at localhost:[port]/___graphql, whereas in our particular case here at: localhost:8000/___graphql.

Now, as you're solving this “How to get Gatsby to work with Drupal” type of puzzle, just try to query all the blog nodes.

Next, navigate back to your blog.js file and run this query:
 

export const query = graphql` query allNodeBlog { allNodeBlog { edges { node { id title body { value format processed summary } } } } } ` 

Then, update your const BlogPage so that it should display the body, content, and title:

const BlogPage = ({data}) => ( <div> <h1>Latest from our blog</h1> { data.allNodeBlog.edges.map(({ node }) => ( <div> <h3>{ node.title }</h3> <div dangerouslySetInnerHTML={{ __html: node.body.value }} /> </div> ))} </div> ) 

Next, save your file and... “jump for joy” at the sight of the result:

All your blog posts, nicely displayed, pulled from Drupal and published on your Gatsby site!
 

4.4. Finally, Just Go Ahead and Publish Your New Gatsby Site

And here you are now, ready to carry out the last task of your “How to get Gatsby to work with Drupal” kind of “mission”. 

This final task is no more than a command that will get your Gatsby website running:

gatsby build 

Next, just run through your /public folder to see the “fruits of your work”.

At this point, all there's left for you to do is to copy/push content in /public to the server and... deploy your new website using Gatsby with Drupal CMS.

The END! This is how you do it: how you use Gatsby.js in a decoupled Drupal setup so you can benefit both from:

1. a modern static site generator's robustness and high performance, built with developer experience in mind 
2. a powerful CMS's content managing capabilities, built with the editorial experience in mind