• Make your WordPress Rest API queries easy with GraphQL and Gatsby
  • Requirements
  • WordPress
  • Install the Gatsby
    • Explore quickly what is installed
      • Folders
      • Files
    • Create a page with Gatsby
    • Link WordPress to Gatsby
  • Pull the content with GraphQL
    • Query all posts and pages
  • Display all posts to the front-end
    • What did we?
  • Bonus: Pull ACF, Menus and Widgets
    • ACF
    • Menus
  • Build a prodution version
  • Deploy to production with Surge
  • Credits

With the web ecosystem steadily moving towards JAMstacks, JavaScript framework and serverless apps, we created this tutorial to help you build a static WordPress website with GatsbyJS, GraphQL and ReactJS.

Each step of the tutorial will go through the basics and also includes extra details in case you want to dive deeper.

You can also checkout the "workshop-wordpress-gatsby-react" folder to see the final results of the tutorial.

Feel free to suggest with improvements and updates, and contribute to this training repository.

@WordPress #HeadlessCMS @GatsbyJS @GraphQL @ReactJS @SurgeSH

• Install Chrome

  You can use the browser of your choice to follow this workshop, but Chrome is the one I'm using.

• Install VSCode

  You can also use the IDE of your choice, but I recommend you to install VSCode. It's easy to use, works very well with JavaScript and a built-in terminal (that you will have to use).

• Install NodeJS and NPM

  NodeJS is not a framwork. It's a JavaScript runtime, a low-level server environment. It is closer to C than languages ​​interpreted as PHP, Ruby or Python. Choose the LTS (Long Terme Support) version.

• Install NPM

  NPM (Node Package Manager) makes it easy for JavaScript developers to share and reuse code, and makes it easy to update the code that you’re sharing, so you can build amazing things. It's distributed with Node.js, which means that when you download Node.js, you automatically get npm installed on your computer.

  To check if you have Node.js installed, run this command in your terminal:

  node -v

  To confirm that you have npm installed you can run this command in your terminal:

  npm -v

  Instead of using NPM, you can use Yarn as well.

• Install GIT

  Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. You will need to be able to generate website with Gatsby. :warning: If you are not able to install it, don't worry, there is a gatsby sarter available in this tutorial named gatsby-starter. Download it, then do the rest of the workshop inside this project.

nvm install 10.16.0
nvm alias default 10.16.0

You will not need to install a WordPress. You can use this url wcpboston.eelab.space.

Something very cool with Gatsby is that you can very easily change the WordPress to the one you want just by changing one line in your code.

Gatsby is a React-based, GraphQL powered, static site generator. What does that even mean? Well, it weaves together the best parts of React, webpack, react-router, GraphQL, and other front-end tools in to one very enjoyable developer experience. Don’t get hung up on the moniker "static site generator". That term has been around for a while, but Gatsby is far more like a modern front-end framework than a static site generator of old.

It uses powerful preconfiguration to build a website that uses only static files for incredibly fast page loads, service workers, code splitting, server-side rendering, intelligent image loading, asset optimization, and data prefetching.

You code and develop your site, Gatsby transforms it into a directory with a single HTML file and your static assets. This folder is uploaded to your favorite hosting provider, and voila.

In order to generate a Gatsby website, we will use Gatsby CLI. First, from the terminal, do:

npm install -g gatsby-cli

Then, to generate the website, go to your favorite location, then do:

gatsby new workshop-wordpress-gatsby-react

Then, move to this directory

cd workshop-wordpress-gatsby-react

Install dependencies:

npm install

And finally, to start the development server, do:

gatsby develop

And now, your website will be available to http://localhost:8000/.
⚠️ If it doesn't work, you probably have to rebuild npm by doing: npm rebuild.

• .cache/: This folder is an internal cache created automatically by Gatsby. The files inside this folder are not meant for modification. Should be added to the .gitignore file if not added already.
• node_modules/: All modules installed by the package.json file. This folder is ignored by git.
• public/: This folder is the build directory. It is also ignored by git.
• src/: Here is where the magic happens. You will find everything you need to build the website inside this folder. =>

• components/: they are the building blocks of any React app. It’s a JavaScript class or function that optionally accepts inputs i.e. properties(props) and returns a React element that describes how a section of the UI (User Interface) should appear.
• pages/: Files in this folder become pages automatically with paths based on their file name. Here is the full documentation.
• templates/: You don't have this folder at the beginning but it will contains templates for programmatically creating pages. Here is the full documentation

• gatsby-browser.js: This is where you put your custom JavaScript. You will have to use Gatsby browser API to make it works. Here is the documentation.
• gatsby-config.js: This is the main configuration file for a Gatsby site. This is where you can specify information about your site (metadata) like the site title and description, which Gatsby plugins you’d like to include, etc. Here is the full documentation.
• gatsby-node.js: This is where you will customize your path, create your page, your single page (files in template folder) … Here is the full documentation.
• gatsby-ssr.js: This file is where Gatsby expects to find any usage of the Gatsby server-side rendering APIs. We are not using it but here is the full documentation.
• package.json: This is where you will add all your modules and scripts that you need for you website.

Create a page with Gatsby is very simple, any React component defined in src/pages/*.js will automatically become a page.

For instance, let's create a page called posts.js and past the following code into it:

import React from "react"

export default (props) => {
  return (
    <h1>Posts page</h1>
  )
}

If the server is still running (otherwise, at the root project folder, run the following command from the terminal gatsby develop), you can now navigate to http://localhost:8000/posts/ and your new page will be accessible.

For that, we will have to install a new Gatsby plugin, gatsby-source-wordpress. It's very simple, open a new terminal window at the root the project and just do the installation by this simple command line: (The --save tag means that a new line with the plugin slug and his version will be added to the package.json file)

npm install --save gatsby-source-wordpress

Once you've installed the plugin, open gatsby-config.js and paste the following code in the plugins array, at ligne 30 (it's part for the documentation but with only what we need):

{
  resolve: "gatsby-source-wordpress",
  options: {
    /*
    * The base URL of the Wordpress site without the trailingslash and the protocol. This is required.
    * Example : 'gatsbyjsexamplewordpress.wordpress.com' or 'www.example-site.com'
    */
    baseUrl: "wcpboston.eelab.space", // or your custom WordPress url
    // The protocol. This can be http or https.
    protocol: "https",
    // Indicates whether the site is hosted on wordpress.com.
    // If false, then the assumption is made that the site is self hosted.
    // If true, then the plugin will source its content on wordpress.com using the JSON REST API V2.
    // If your site is hosted on wordpress.org, then set this to false.
    hostingWPCOM: false,
    // If useACF is true, then the source plugin will try to import the Wordpress ACF Plugin contents.
    // This feature is untested for sites hosted on Wordpress.com.
    // Defaults to true.
    auth: null,
    useACF: true, // Allows to pull ACF fields
    // Set verboseOutput to true to display a verbose output on `npm run develop` or `npm run build`
    // It can help you debug specific API Endpoints problems.
    verboseOutput: false,
    // Exclude specific routes using glob parameters
    // See: https://github.com/isaacs/minimatch
    // Example:  `["/*/*/comments", "/yoast/**"]` will exclude routes ending in `comments` and
    // all routes that begin with `yoast` from fetch.
    excludedRoutes: ["/*/*/comments", "/yoast/**"],
    // use a custom normalizer which is applied after the built-in ones.
    normalizer: function({ entities }) {
      return entities
    },
  },
},

We are now able to pull data into Gatsby from WordPress using the WordPress REST API. NOTE: Every time you modify this file, you will have to restart the server. Press control+c (ctrl+c for windows) to stop the server if it's still running, then:

gatsby develop

By default, WordPress don't add data from ACF, Menus, WPLM... in his REST-API so you will have to install a few plugins to your WordPress in order to be able to have those data available with GraphQL.

GraphQL is a query language (the QL part of its name). If you’re familiar with SQL, it works in a very similar way. Using a special syntax, you describe the data you want in your component and then that data is given to you.

Gatsby uses GraphQL to enable components to declare the data they need.

When you started the server, a second link was displayed in the terminal: http://localhost:8000/___graphql. This is where you can test you query or explore the types and properties of your GraphQL.

Let's learn how to query your data with GraphQL!

Basically, to query contents from WordPress, it would be very similar to:

{
  allWordpress${Manufacturer}${Endpoint} {
    edges {
      node {
        id
        // Put your fields here
      }
    }
  }
}

where ${Manufacturer} is the endpoint prefix and ${Endpoint} is the name of the endpoint from the WordPress URL:

https://wcpboston.eelab.space/wp-json/${Manufacturer}/v2/${Endpoint}

So, for instance, for all posts, url will be:

https://wcpboston.eelab.space/wp-json/wp/v2/posts

and the GraphQL will be:

{
  allWordpressPost {
    edges {
      node {
        id
        slug
        title
        content
      }
    }
  }
}

It's almost exactly the same for pages, except that the ${Endpoint} is different:

https://wcpboston.eelab.space/wp-json/wp/v2/pages

and the GraphQL will be:

{
  allWordpressPage {
    edges {
      node {
        id
        slug
        title
        content
        excerpt
        date
        modified
        status
      }
    }
  }
}

As you can see, the differences are the Query Type (allWordpressPost for posts and allWordpressPage for pages) and the fields in the node object. Doing that, you should have this result on the right:

If you don't know which properties are available in GraphQL, you can press Shift+Spacebar on mac or Ctrl+spacebar on Windows.

All of that is nice, but how are we implement that for the front-end. It's now ReactJS time!

Arguments are used to filter, limit, skip or sort your results from your query. There are applyed to the query type.

export const query = graphql`
  query {
    allWordpressPost(
      sort: {
        fields: [title]
        order: DESC
      }
    ) {
      edges {
        node {
          id
          title
          content
        }
      }
    }
  }
`

export const query = graphql`
  query {
    allWordpressPost(
      sort: {
        fields: [title, status]
        order: DESC
      }
    ) {
      edges {
        node {
          id
          title
          content
        }
      }
    }
  }
`

export const query = graphql`
  query {
    allWordpressPost(limit: 6) {
      edges {
        node {
          id
          title
          content
        }
      }
    }
  }
`

export const query = graphql`
  query {
    allWordpressPost(skip: 6) {
      edges {
        node {
          id
          title
          content
        }
      }
    }
  }
`

allWordpressPost(
  filter: {
    categories: {
      ...
    }
  }
) {
  edges {
    node {
      id
      title
      content
    }
  }
}

allWordpressPost(
  filter: {
    categories: {
      elemMatch: {
        ...
      }
    }
  }
) {
  edges {
    node {
      id
      title
      content
    }
  }
}

allWordpressPost(
  filter: {
    categories: {
      elemMatch: {
        name: {
          eq: "Boston"
        }
      }
    }
  }
) {
  edges {
    node {
      id
      title
      content
    }
  }
}

Instead of duplicating your query in multiple component, you can use fragments.

fragment FragmentName on TypeName {
  field1
  field2
}

fragment allPosts on wordpress__POSTConnection {
  edges {
    node {
      id
      title
      date
    }
  }
}

{
  allWordpressPost {
    ...allPosts
  }
}

import { graphql } from 'gatsby';

export const fragments = graphql`
  fragment allPosts on wordpress__POSTConnection {
    edges {
      node {
        id
        title
        content
        date(formatString: "dddd DD MMMM YYYY")
      }
    }
  }
`

export const query = graphql`
  query {
    allWordpressPost {
      edges {
        node {
          id
          title
          content
        }
      }
    }
  }
`

export const query = graphql`
  query {
    allWordpressPost {
      ...allPosts
    }
  }
`

export const query = graphql`
  query {
    firstQuery: allWordpressPost(limit: 6) {
      ...allPosts
    }
    secondQuery: allWordpressPost(skip: 6) {
      ...allPosts
    }
  }
`

Inside the post page that we created earlier posts.js, import and the Layout component to keep the header and footer, and wrap the h1 html tag with the new component:

import React from "react"
import Layout from "../components/layout"

export default (props) => {
  return (
    <Layout>
      <h1>Posts page</h1>
    </Layout>
  )
}

If you server is still running, it should have compiled.

If you go back to the website, you should be able to visit this page: http://localhost:8000/posts

Let's now display all posts title and his content! To do so, it's very simple. You first need to import graphql from gatsby at the top of your file:

import { graphql } from 'gatsby'

Then after your function, you just need to export a variable who contains the graphql query:

export const query = graphql`
  query {
    allWordpressPost {
      edges {
        node {
          id
          title
          content
        }
      }
    }
  }
`

And finally, you can update your function to display the content. Because GraphQL returns us an array, you will have to loop throught it:

export default (props) => {
  return (
    <Layout>
      <h1>Posts page</h1>
      {props.data.allWordpressPost.edges.map(post => {
        return (
          <div key={post.node.id}>
            <h2 dangerouslySetInnerHTML={{ __html: post.node.title }} />
            <div dangerouslySetInnerHTML={{ __html: post.node.content }} />
          </div>
        )
      })}
    </Layout>
  )
}

Querying with Graphql will returns us an object data (it's always data!). Inside this object, we have another object allWordpressPost (the one we specify from our query, it will be allWordpressPages if we want all pages for instance) and inside this one, we have another one edges who is basically an array of objects which contains all our data, that's why we are using the map() function to loop throught the array.

If you go back to the website, all posts form WordPress are displayed! But you've probably notice that something is not good, HTML is not striped. it's because by default, React escapes the HTML to prevent XSS (Cross-site scripting). So to render HTML, we have to add the following property to our HTML tag:

dangerouslySetInnerHTML={{ __html: ... }}

dangerouslySetInnerHTML is React's replacement for using innerHTML in the browerDOM.

So, your function should looks like that now:

{props.data.allWordpressPost.edges.map(post => {
  return (
    <div key={post.node.id}>
      <h2 dangerouslySetInnerHTML={{ __html: post.node.title }} />
      <div dangerouslySetInnerHTML={{ __html: post.node.content }} />
    </div>
  )
})}

And now, your content is rendered properly!

⚠️ IMPORTANT: Only pages or template pages can define GraphQL queries. If you want to use a GraphQL query inside a component, you will have to use a hook of StaticQuery called useStaticQuery, that allows components to retrieve data via GraphQL query (we will see later how yo use it).

If you want to create dynamic template, like single post, you will have to do a few more things.

import React from "react"
import Layout from "../components/layout"

export default (props) => {
  return (
    <Layout>
      <h1>Post template</h1>
    </Layout>
  )
}

const Promise = require('bluebird')
const path = require('path')

exports.createPages = ({ graphql, actions }) => {
  const { createPage } = actions
  return new Promise((resolve, reject) => {
    graphql(`
      {
        allWordpressPost {
          edges {
            node {
              id
              slug
            }
          }
        }
      }`
    ).then(result => {
      // Create posts pages.
      result.data.allWordpressPost.edges.forEach(({ node }) => {
        createPage({
          path: `/post/${node.slug}/`,
          component: path.resolve(`./src/templates/post.js`),
          context: {
            id: node.id,
          },
        })
      })
      resolve()
    })
  })
}

import { graphql, Link } from 'gatsby'

export const query = graphql`
  query {
    allWordpressPost {
      edges {
        node {
          slug
          id
          title
          content
        }
      }
    }
  }
`

<Link to={`post/${post.node.slug}`}>
  <h2 dangerouslySetInnerHTML={{ __html: post.node.title }} />
</Link>

export default (props) => {
  return (
    <Layout>
      <h1>Posts page</h1>
      {props.data.allWordpressPost.edges.map(post => {
        return (
          <div key={post.node.id}>
            <Link to={`post/${post.node.slug}`}>
              <h2 dangerouslySetInnerHTML={{ __html: post.node.title }} />
            </Link>
            <div dangerouslySetInnerHTML={{ __html: post.node.content }} />
          </div>
        )
      })}
    </Layout>
  )
}

import { graphql } from 'gatsby'

export const query = graphql`
  query {
    wordpressPost {
      title
      content
      featured_media {
        id
        source_url
        alt_text
      }
    }
  }
`

export default (props) => {
  const singlePost = props.data.wordpressPost;

  return (
    <Layout>
      <h1>{singlePost.title}</h1>
      <img  src={singlePost.featured_media.source_url}
            alt={singlePost.featured_media.alt_text}
      />
      <div dangerouslySetInnerHTML={{ __html: singlePost.content }} />
    </Layout>
  )
}

In order to apply Gutenberg block styles to your website, there is a few steps to follow.

You will have to first, set the useACF property to true from gatsby-source-wordpress settings in gatsby-config.js file, and secondly, have the plugin acf-to-rest-api installed in WordPress.

Then, restart your server (control+c or ctrl+c for windows, to stop it, then gatsby develop to start it).

Let's use the following example:

Each post has a link (htts://www.google.ca), this link is an Advanced Custom Field from WordPress.

In order to retrieve this field, from the all posts query, you just need to add a new field:

export const query = graphql`
  query {
    allWordpressPost {
      edges {
        node {
          id
          title
          content
          acf {
            field_url
          }
        }
      }
    }
  }
`

And now, update your render function to display this field:

<a target="_blank" rel="noopener noreferrer" href={post.node.acf.field_url}>
  {post.node.acf.field_url}
</a>

So, your function should looks like the following:

export default (props) => {
  return (
    <Layout>
      <h1>Posts page</h1>
      {props.data.allWordpressPost.edges.map(post => {
        return (
          <div key={post.node.id}>
            <h2 dangerouslySetInnerHTML={{ __html: post.node.title }} />
            <div dangerouslySetInnerHTML={{ __html: post.node.content }} />
            <a target="_blank" rel="noopener noreferrer" href="{post.node.acf.field_url}">
              {post.node.acf.field_url}
            </a>
          </div>
        )
      })}
    </Layout>
  )
}

You will have to add the plugin [wp-api-menus] to WordPress (https://wordpress.org/plugins/wp-api-menus/) which gives you the menus and menu locations endpoint to the REST-API (we already added this plugin to our WordPress in order to be available for you).

Then add your pages, links, etc into WordPress Menus, restart your server (don't forget to do it, otherwise, you won't be able to pull your data with GraphQL)

To query menus from the REST-API, the ${Manufacturer} is WpApiMenus and the ${Endpoint} is MenusItems. This is the query:

allWordpressWpApiMenusMenusItems {
  edges {
    node {
      items {
        title
        object_slug
      }
    }
  }
}

Gatsby already has a Layout component in src/components/, so it's a good place to add your menu query. Open the layout.js file, and inside useStaticQuery, past our menu query:

const data = useStaticQuery(graphql`
  query SiteTitleQuery {
    site {
      siteMetadata {
        title
      }
    }
    allWordpressWpApiMenusMenusItems {
      edges {
        node {
          items {
            title
            object_slug
          }
        }
      }
    }
  }
`)

NOTE: By default, file inside src/components folder cannot accept graphQL query, but Gatsby v2.1.0 introduces a hooks version of StaticQuery called useStaticQuery, a new API that allows components to retrieve data via GraphQL query. See the full documentation here.

We can finally render the menus with React:

<nav>
  <ul>
    {nav.edges[0].node.items.map((node, index) => {
      return (
        <li key={index}>
          <Link to={"/" + node.object_slug}>{node.title}</Link>
        </li>
      )
    })}
  </ul>
</nav>

To build a produciton version, Gatsby provide us a command who produce a directory of static HTML and JavaScript files (public folder) which you can deploy to a static site hosting service.

Simply do the following command gatsby build at the root of the project folder.

A few secondes later, Gatsby should have create a public folder. We will deploy this folder in the next step.

Surge is one of many "static site hosts" which make it possible to deploy Gatsby sites.

In order to be able to use it, follow the next steps:

1. Install Surge with the following command: npm install --global surge
2. Then, deploy your site: surge public/. If it's the firsts time, you will have to create an account (don't worry, it's free!). Enter your email, password, and press enter to confirm that the path to your public/ folder is correct.
3. Bonus: To ensure future deploys are sent to the same location, you can remember a domain. For instance, if your website was deployed to http://amazing-website.surge.sh/, run the following command: surge --domain amazing-website.surge.sh. The next time yo will run the surge command, it will deploy to the same domain.

Logos: WordPress, Gutenberg, Gatsbyjs, Graphql, Reactjs, Surge.sh