Skip to main content

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 the 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.

gatsby-config.js
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.

gatsby-config.js
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
}
},
]
}

Note: If your config varies from what it shown above, for instance, if you are hosting your WordPress instance on WordPress.com, please refer to the plugin docs for more information on how to setup other options required for your use case.

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 the gatsby-node.js from the plugin demo to get started. For the purpose of this guide, the code to construct posts works out of the box. It queries your local WordPress GraphQL schema for all Posts, iterates through each Post node and constructs a static page for each, based on the defined template.

For example, find an excerpt of the demo gatsby-node.js below.

gatsby-node.js
const path = require(`path`)
const slash = require(`slash`)
exports.createPages = async ({ graphql, actions }) => {
const { createPage } = actions
// query content for WordPress posts
const result = await graphql(`
query {
allWordpressPost {
edges {
node {
id
slug
}
}
}
}
`)
const postTemplate = path.resolve(`./src/templates/post.js`)
result.data.allWordpressPost.edges.forEach(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,
},
})
})
}

After fetching data from WordPress via the query, all posts are iterated over, calling createPage for each one.

A Gatsby page is defined as “a site page with a pathname, a template component, and an optional GraphQL query and Layout component.”

When you restart your server with the gatsby develop command, you’ll be able to navigate to the new pages created for each of your posts at their respective paths.

In the GraphiQL IDE at localhost:8000/__graphql you should now see queryable fields for allWordpressPosts in the docs or explorer sidebar.

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


Edit this page on GitHub
Docs
Tutorials
Plugins
Blog
Showcase