WPGraphQL: The hero the static-site stack needs

April 30, 2019
By Paul Grieselhuber
WPGraphQL: The hero the static-site stack needs
It’s not the hero we deserve…

The WP REST API was exciting back in 2016 for approximately 5 minutes, until you started using it. While it’s nice to be able to request raw data from WordPress, making the requisite nested queries to pull together a basic page with related posts had me lamenting the darkened soul of man.

Luckily, WPGraphQL has come along to get us querying WordPress using GraphQL like modern hominids, and restored my faith in mankind’s ability to overcome tediousness.

But WPGraphQL is about more than just freeing you from soul-crushing verbosity, it’s also useful for building websites and software.

So I suppose we should touch on that as well.

Emerging from the cave: The WordPress-via-API pattern reaches maturity

We have been building websites and apps using the WordPress REST API for 4 years now, and GraphQL on other projects since 2017. Only recently has there been the opportunity to “merge” the two (WordPress and GraphQL). The combination is an extremely welcome evolution.

By the way, if you need a more general primer on GraphQL, the WPGraphQL has put together a good walkthrough.

We have built websites and apps using several flavors of React front ends, from “vanilla” React to Gatsby and Next.js, and have become fond of saying that this stack (that is: a solid CMS, GraphQL and a React / similar front-end) is what they meant when they first said “website”, all those years ago.

The stack provides the best experience from end-to-end:

  • The developer gets the experience they have always wanted (whether they knew it or not)
  • The customer gets a responsive developer who can literally do anything they can imagine with ease
  • And the end-user gets insanely fast, static rendered HTML pages that still provide rich, interactive experiences

Which is why WPGraphQL plays such an important role in the modern web development stack: if you want to use this stack with WordPress, it’s simply a critical piece of your infrastructure.

While WPGraphQL is still a bit in its early days, it is already remarkably robust and full-featured. The team is knowledgeable, and as responsive of a free software / open source team as I have seen to feedback, issue & bug reports, and answering questions.

Why do we refer to it as the hero the “static-site stack” needs? I.e. why so broad or agnostic?

We perceive WPGraphQL’s value and relevance to be so broad because the chances are that you are probably using WordPress as your CMS. And if you aren’t, consider it.

While front-end templating with WordPress has the same charm as a stroll through an old west ghost town, it’s also nearly as engaging, robust and innovative.

However, WP Admin is great, and clients love using it. Plus, it’s not going anywhere.

For internal and personal projects, we actually moved away from WordPress for some time maybe 5-6 years ago. But, the evolving API brought us back, and for most sorts of projects (though definitely not all), it remains our go-to.

We envision that most large, robust sites will continue to use WordPress, and that as WPGraphQL becomes more popular, that even more developers will opt to use it for their projects. Even the too-cool-for-school avant-garde.

Any failings WordPress may have aside, it’s the most developed CMS in the world, and with a solid GraphQL API available, there’s simply no counterargument for most projects that fall within the general purview of “website”.

How full featured is WPGraphQL?

In our experience, there has been nothing that we have wanted to go that we cannot currently do as of the latest release. That doesn’t mean that nothing is missing, just that as we have used the software, it has progressed to the point where all the endpoints we need are covered.

This means posts, pages, comments, categories, tags, custom post types, settings, menus, plugins, everything.

Difference in development experience

Getting down to the nitty-gritty, let’s take a look at what it’s like to work with the REST API vs. WPGraphQL.

As mentioned earlier, we’ll use the example of pulling the data for a simple post, along with some posts from related tags or categories, perhaps the most common use case.

A basic content request via the REST API

I’ll spare you the code spam of making requests but it essentially looks like this:

  • Request the post, get back title, content, publish date, etc.
    • From the response, parse the URL + ID info for the featured image and tags and / or categories
      • Request the image endpoint, which will tell you where the images are
      • Request the tag and / or category endpoints. Let’s say the first 10.
        • Request the posts at those endpoints. That’s 10 API requests.
          • Request the images for each of those posts (10 more API requests! Each!)

And this is the simple version. In reality you end up handling edge cases like an old post having no image, etc., all stuff that the WPGraphQL model handles for you.

Oh, and don’t forget to do the same for the author and any attached metadata you want to get from the post!

A basic content request via WPGraphQL

Now let’s make the same request with WPGraphQL – only here we have already included the author and metadata:

query GET_POSTS {
  posts {
    edges {
      node {
        id
        title
        date
        someCustomMetaData # some custom meta data
        author {
        firstName
          lastName
          email
          avatar {
            url
          }
        }
        featuredImage {
          mediaDetails {
            sizes {
              sourceUrl
            }
          }
        }
        categories(first:10) {
          edges {
            node {
              name
              slug
              posts(first:10) {
                edges {
                  node {
                    id
                    title
                    date
                    featuredImage {
                      mediaDetails {
                        sizes {
                          sourceUrl
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
        tags(first:10) {
          edges {
            node {
              name
              slug
              posts(first:10) {
                edges {
                  node {
                    id
                    title
                    date
                    featuredImage {
                      mediaDetails {
                        sizes {
                          sourceUrl
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

For the record, that is one query with everything that we want. And it took about 30 seconds to write.

Which do you prefer? Which would you prefer to maintain? Which is going to give you more development agility and excitement to do more magic for your clients?

Even more powerful when you have more than one application consuming this data

Consider this case for a moment. Using the REST API you would have around double the code to maintain. Remember those edge cases from the REST API section above? Well, using the REST API every consumer is responsible for its own fetch / parse / round-trip logic.

Whereas with WPGraphQL does all the heavy lifting, you can simply pass the same query or something completely new without having to create any new wiring (ht WPGraphQL creator @jasonbahl).

Fasten your cape

If you are not using WPGraphQL to build static websites with WordPress, you soon will be. Do yourself a favor and start today.

It’s a web development superpower.

Paul Grieselhuber