Sourcing from WordPress

This guide will walk you through the process of using Gatsby with WordPress Rest Api.

WordPress is a free and open-source content management system (CMS). Let’s say you have a site built with WordPress and you want to pull the existing data into your static Gatsby site. You can do that with gatsby-source-wordpress. Let’s begin!

Note: this guide uses the gatsby-starter-default to provide you with a knowledge necessary to start working with WordPress but if you get stuck at some point of the guide feel free to use this example to gain extra insights.

Setup

Quick start

This guide assumes that you have a Gatsby project set up. If you need to set up a project, head to the Quick Start guide, then come back.

gatsby-config.js

Essentially the Gatsby home base. The two things defined here initially (in the starter) are siteMetadata and plugins you can add to enable new functionalities on your site.

module.exports = {
  siteMetadata: {
    title: "Gatsby Default Starter",
  },
  plugins: ["gatsby-plugin-react-helmet"],
  ...
}

Plugin: gatsby-source-wordpress

Now that you have some understanding of project structure lets add fetching WordPress data functionality. There’s a plugin for that. gatsby-source-wordpress is Gatsby’s plugin for sourcing data from WordPress sites using the WordPress JSON REST API. You can install it by running the following command:

npm install gatsby-source-wordpress

Configuring the plugin

In gatsby-config.js, add your configuration options, including your WordPress site’s baseUrl, protocol, whether it’s hosted on wordpress.com or self-hosted, and whether it makes use of the Advanced Custom Fields (ACF) plugin.

module.exports = {
  ...
  plugins: [
    ...,
    {
      resolve: `gatsby-source-wordpress`,
      options: {
        // your wordpress source
        baseUrl: `wpexample.com`,
        protocol: `https`,
        // is it hosted on wordpress.com, or self-hosted?
        hostingWPCOM: false,
        // does your site use the Advanced Custom Fields Plugin?
        useACF: false
      }
    },
  ]
}

Using WordPress data

Once your source plugin is pulling data, you can construct your site pages by implementing the createPages API in gatsby-node.js. When this is called, your data has already been fetched and is available to query with GraphQL. Gatsby uses GraphQL at build time; Your source plugin (in this case, gatsby-source-wordpress) fetches your data, and Gatsby uses that data to ”automatically infer a GraphQL schema” that you can query against.

The createPages API exposes the graphql function:

The GraphQL function allows us to run arbitrary queries against the local WordPress GraphQL schema… like the site has a built-in database constructed from the fetched data that you can run queries against. (Source)

You can use gatsby-node.js file from the plugin demo to get started. For the purpose of this guide the code to construct ‘posts’ does what it needs to do out of the box (at least for the moment). It queries your local WordPress GraphQL schema for post data, then iterates through each post node to construct a static page for each, based on whatever template you define and feed it.

For example, below is the part of the demo gatsby-node.js file that iterates over all the WordPress post data.

const postTemplate = path.resolve(`./src/templates/post.js`)

_.each(result.data.allWordpressPost.edges, edge => {
  createPage({
    // will be the url for the page
    path: edge.node.slug,
    // specify the component template of your choice
    component: slash(postTemplate),
    // In the ^template's GraphQL query, 'id' will be available
    // as a GraphQL variable to query for this posts's data.
    context: {
      id: edge.node.id,
    },
  })
})

The docs define a Gatsby page as “a site page with a pathname, a template component, and optional graphql query and layout component.” See the docs on the createPage bound action creator and guide on creating and modifying pages for more detail.

Wrapping Up

This was a very basic example meant to help you understand how you can fetch data from WordPress and use it with Gatsby. As the guide mentioned already, if you got stuck, you can have a look at example repo, which is a working example created to support this guide.

Other resources

• Blog post on which this guide is based on
• Watch + Learn video tutorials
• Another blog post on using Gatsby with WordPress