How to Create a Headless Gatsby WordPress Site Using a Starter

Note: This post is part of Learning Decoupling Gatsby WordPress series. This learning post is still in active development and updated regularly.

Most WordPress users, like myself, have come across the terms like headless, decoupled or static WordPress sites. We have read blog posts that many developers have migrated from the WordPress to the static sites’ framework like Gatsby, Hugo, Jekyll, and others.

WordPress is the dominant in content management systems with over 38% of uses and is popular with most users except some developers. Some advanced developers feel that it’s convoluted, prone to attack by hackers, slow and non-modular, leaner alternatives like Gatsby frameworks are better suited modern technology to overcome such problems.

What is Headess WordPress?

The WordPress CMS has two parts, the front for content display and the back-end for content management. The term headless or decoupled means that retaining the back-end content management part of the WordPress to store the contents and use JS frameworks like GatsbyJs to render it to the front-end.

In addition to the WordPress CMS, GatsbyJs framework decouples other CMSes like Contentful, GraphCMS, NetlifyCMS, Prismic and others. In this walkthrough guide, we will focus on GatsbyJs generated headless WordPress sites.

Using GatsbyJS frame work, a WordPress site can decoupled with WPGraphQL, Gatsby Source WordPress and Gatsby Source WordPress Experimental plugins. Decoupling a WordPress site with WPGraphQL is covered by Henrik Wirth in this Dev.to guide. The Gatsby source WordPress plugin v3 is re-written using WPGatsby and is currently available as Gatsby Source WordPress Experimental plugin.

Gatsby Source WordPress Experimental Starter

Currently, there are two starters listed in the plugin documentation. The Gatsby-starter-wordpress-twenty-twenty is a complete ready to use starer with a demo site. At the time of this writing, the starter was tested up to gatsby-source-wordpress-experimental v1.3.6, WPGraphQL v0.12.1 and WPGatsby v0.4.16 plugins.

The other starter authored by Tylor Barnes (plugin author) is maintained up to date but it lacks a demo site and no ready to use tutorial for average users like myself. In my Google search I found only one brief tutorial by tutorial by codeytek academy but which is dated too, done with release 0.1.1 and the latest release is – v1.2.3.

Prerequisites

It’s assumed that the users of this guide have familiarity with the following:

Familiarity of React and JavaScript. Links to helpful getting started guides for React and JavaScript.
Basic understanding of Gatsby and how dynamic pages are created. Here is a link to an excellent step-by-step tutorial guide to learn Gatsby.
Familiarity with WordPress and a working installation. Here are guides to help get you started.

Objective

I have been working on this gatsby-source-wordpress V4 (alpha) starter to learn from and create a basic decoupled WordPress Gatsby site with some styling. In this walk through guide, I thought to share my experiences to other average WordPress users (like myself). This walk through guide is divided into the following three parts.

Learning series
Part 1: Site Set Up and Installation and (this post)
Part 2: Working with Global Layout and Site Header and Basic Styling
Part 3: Working with Posts and Pages

In this part 1 of the four-parts series, step-by-step procedures to install, clone the starter site and overview its file structures will be briefly discussed.

Site Setups and Installations

In this section we will install Gatsby WordPress starter and a endpoint data source WordPress site and do some setups.

Step 1: WordPress Installation

This could be an already existing site in a remote server. Even a local WordPress installation works fine. For this project, we will install a test WordPress site using the Twenty Twenty theme that ships with WordPress. For posts and page contents, we will import theme unit test data as described in this codex document.

For the site setup, first, lets create a page name Home and add some dummy content there. In the WordPress admin dashboard appearance > customize window, set home page display to a static page and select Home as homepage and under post pages select Blog page.

Screenshot showing homepage setup.

Step 2: Menu Setup

To display the WordPress menu items in the Gatsby site this fields should be verified as set in the WordPress instance. In the starter menu, wpMenu slug is set as “main-menu” so the name of our primary menu should be “MAIN MENU”. For example, if menu name is set as Primary Menu instead, then the slug field should be updated to “primary-menu” in the menu.js query.

Screenshot showing menu setting in the WordPress admin dashboard.

Step 3: Installing Dependent WPGraphQL and WPGatsby Plugins

To expose WordPress endpoint data to the Gatsby site, the starter requires two dependent plugins that are found in the wordpress/plugins folder of the starter. Because these plugins are not backward compatible, make sure to install the compatible versions by included in the wordpress/plugin folder of the starter.

Screenshot showing installed plugins in the WordPress data source.

Additionally, install another optional but super handy WPGraphiQL (note the “i” in the name) optional plugin as well which creates an interface for testing GraphQL queries directly in the WordPress dashboard. After plugin activation the GraphiQL API is displayed in the WordPress dashboard.

More details on various ways of interacting with WPGraphQL through WPGraphiQL is described in the WPGraphQL documentation.

Step 3: Installing Gatsby WordPress Starter

Now, lets install the starter using the GitHub Installation and Getting Started guide.

#! install starter
gatsby new gatsby-wpv4-demo https://github.com/TylerBarnes/using-
   gatsby-source-wordpress-experimental

Step 4: Updating the gatsby-config.js file of the starter

The source WordPress instance URL, created in the previous step should be updated in the gatsby-config.js file of the starter to point to the WordPress instance GraphQL url.

// plugin configuration
module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-wordpress-experimental`,
      options: {
        url:
          process.env.WPGRAPHQL_URL ||
          `http://localhost/gatsby-wpv4/graphql`,
        verbose: true,
        develop: {
          hardCacheMediaFiles: true,
        },
        debug: {
          graphql: {
            writeQueriesToDisk: true,
          },
         ...
         ...
        },
  ],
}

Now the full URL of our install will be http//localhost/gatsby-wpv4-demo/___graphql

Step 5: Update the Menu Slug to View Menu Items

In the starter menu, wpMenu slug is set as “main-menu“. To display the menu items this fields should be verified as set in the WordPress instance. For example, if menu is set as Primary Menu, then the slug field should updated to “primary-menu” in the menu.js query.

Step 5: View the Site in a Browser

Run gatsby develop and visit the site in the browser at http://localhost:8000. If there were no mistakes, the following should display in the browser.

Screenshot showing starter demo Gatsby site.

Exploring Structure of the Starter

The top level files & directories of the starter as shown in the project folder:

#! top level file & directory of the starter
.
├── WordPress/Plugin
├── node_modules
├── src
├── .env.GATSBY_CONCURRENT_DOWNLOAD
├── .gitattribures
├── .gitignore
├── .prettierrc
├── LICENSE
├── README.md
├── gatsby-config.js
├── gatsby-node.js
├── package.json
└── yarn.lock

The file & directory structure of the /src sub-directory looks as shown below:

#! /SRC - folder structure
├── src
 │   └── assets
 │         └── images
 │         └── svg
 │         └── style.css
 │   └── components
 │         └── template-parts
 │               └── blog-post.js
 │             └── header.js
 │             └── layout.js
 │             └── menu.js
 │   └── pages
 │          └── 404.js
 │   └── templates
 │         └── single
 │               └── page.js
 │               └── post.js
 │         └── index.js
 │   └── utils
 │         └── get-url-path.js
 ├── fragments.js

A brief description of files & directories of the /src sub-directory folder, which contains all the code related to the front-end of the site (eg., header, footer, page template, etc.).

/assets: contains two folders (images and svg) and style.css file.

/components: contains a template-parts folder with a blog-post.js file inside and three files – headers.js, layout.js and menu.js

/pages: contains a 404.js file

/templates: contains a single folder with two files (post.js and page.js) inside and a index.js file.

/utls: contains a single get-url-path.js file

fragments.js: contains a image fragment.

These files and directories are similar to most Gatsby projects, indeed they are crated using gatsby-cli. Additional information: Gatsby Project Structure

Wrapping Up

in this part of the tutorial, to install and setup WordPress and Gatsby Source WordPress starter along with the starter file structure were discussed. In the next part, we will start working with global layout, modifying site header and laying ground work for styling will be discussed.

NEXT: Working with Global Layout and Site Header and Basic Styling

Useful Resources

While preparing this post, I have referred the following references extensively. Please refer to original posts for more detailed information.

Installation & Getting Started Guide | GitHub
Creating a new site from scratch | GitHub