I’m so excited to announce WPGraphQL 1.0!

If you’ve been using WPGraphQL for your side projects, but are waiting for the “stable” version, then this is it! You can use WPGraphQL in production with the confidence that it is secure, well documented, and supported full time and long term.

If you’re new to the WPGraphQL community, you may ask yourself, “But WordPress already has the REST API. What’s different about using WPGraphQL?”

Well, when you use WPGraphQL to turn your WordPress site into a GraphQL server, multiple resources can be fetched at the same time. And by design you get back the exact data you asked for, nothing more, nothing less. In addition to being easier to work with compared to the REST API, data loading with GraphQL is faster and more efficient. (Read more: “WPGraphQL vs. WP REST API“)

If you are upgrading to 1.0 or another version, see the release notes for information on breaking changes and preparing your site. If you are new, start at the homepage and follow our step-by-step docs.

In this post I want to talk about the journey to 1.0, why it took so long to get to 1.0, and a look at what’s next for WPGraphQL. But before diving into that, I want to also announce some other fun stuff that has also come to life along with this release.

WPGraphQL is now available on the WordPress.org repository
New WPGraphQL.com website
WPGraphQL Swag available on the Gatsby Swag Store

WPGraphQL on WordPress.org

The WordPress.org plugin repository has long been the default distribution mechanism for WordPress plugins. Prior to today, developers had to install WPGraphQL using Composer and installing from packagist, or by downloading from Github.

Now, users can install WPGraphQL directly from WordPress.org’s plugin directory.

We believe that distributing WPGraphQL on the WordPress.org plugin repository should make it easier for users to find and install and keep updated.

New WPGraphQL.com website

WPGraphQL.com has been re-built from the ground up.

Before today, WPGraphQL had 2 primary domains:

WPGraphQL.com, a “traditional” WordPress site using WordPress as the CMS and the theme layer
docs.wpgraphql.com, a Gatsby site using Markdown files in a Github repository for the content.

Now, instead of splitting some content in Markdown files on Github and some content in WordPress, WPGraphQL.com now uses WordPress as the CMS for all content, and and has a Gatsby front-end powered by the new Gatsby Source WordPress plugin, WPGatsby and of course WPGraphQL.

We’ll be releasing tutorials and videos in the coming weeks and months walking through how various parts of the site were created to provide inspiration for you to build great things with this stack as well, but for now you can draw inspiration from the repository this site is built from: https://github.com/wp-graphql/wpgraphql.com

WPGraphQL Swag

Now, possibly the most exciting thing about this whole announcement, is the fact that you can now get WPGraphQL Swag from the Gatsby swag store.

The Journey to 1.0

WPGraphQL was started in November 2016 (with no commit message ???? ) and has come a long way in that time.

Screenshot of the “Initial Commit” in Github

By the end of 2017 the codebase was pretty robust and provided a Schema to interact with many parts of WordPress. Posts, Pages, Custom Post Types, Tags, Categories, Custom Taxonomies, Comments and Nav Menus.

Qz.com was the first site to go to production with WPGraphQL, even before I was using it in production! A few years later and they are still running on WPGraphQL! You can learn more about the early days of their stack from this presentation from December 2017.

In early 2018, my team took WPGraphQL into production on a network of 54 large WordPress sites. WPGraphQL was used as a syndication engine for our network of newspapers. Unlike most GraphQL users, we didn’t initially have a JavaScript or native mobile UI that was using GraphQL, we had PHP WordPress servers syndicating content and GraphQL solved a lot of pain points we had been facing when using REST.

By the end of 2018, more than 100 sites were using WPGraphQL in some way.

Now, WPGraphQL seems to be running all over the place!

This is a non-comprehensive list of sites using WPGraphQL in production in some way:

According to Packagist.org as of June 30, 2020 there were nearly 50,000 installs of WPGraphQL in the wild, and as of November 2020 Packagist reports 71,573 installs.

In 2019 Credit Karma paid for a security audit on the plugin and all reported issues were resolved.

It’s safe to say, WPGraphQL is production ready!

So, why the wait for 1.0?

So, if WPGraphQL has been production ready for such a long time, why is is still not 1.0?

Breaking Changes & WordPress

The WordPress ecosystem has a strong commitment to backward compatibility. This means that once functionality is introduced to a WordPress plugin, it often sticks around forever.

With that in mind, before tagging WPGraphQL 1.0, I wanted so badly to be at a place with the codebase & Schema that I could no longer predict anymore breaking changes.

I wanted the GraphQL Schema to be “perfect” before tagging it 1.0, because I knew that whatever would be in the WPGraphQL Schema at 1.0 would need to remain in the Schema forever. The WordPress community is used to things working the same way “forever” and I wanted to play along.

Breaking Changes & WPGraphQL

The reality is that for software to get better, sometimes it needs to make breaking changes.

WPGraphQL will never be perfect, and it will need to occasionally break to make things better.

For example, when the GraphQL Specification updates to include Input Unions or Interfaces that can implement other Interfaces, WPGraphQL will need to break to keep up with the GraphQL Specification.

There would be no way to keep GraphQL as we know it today and take advantage of tomorrow’s GraphQL Spec without breaking.

WPGraphQL turning 1.0 isn’t a statement that there will never be breaking changes, instead it’s a statement of stability and long term support.

So, how will breaking changes be handled in a post-1.0 world?

Semantic Versioning

WPGraphQL has been following Semver practices for a few years. We will continue to follow Semver and let version numbers communicate meaning. The summary of Semver versioning is as follows:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards compatible manner, and
PATCH version when you make backwards compatible bug fixes.

You can read more about the details of Semver at semver.org

Seamless Upgrade Paths

When WPGraphQL needs to make breaking changes to the Schema, there are sometimes ways to make the changes and allow for seamless upgrade paths.

What that means, is that WPGraphQL can introduce a new feature while keeping the old feature. For example, let’s say the following (hypothetical) query were in the Schema and the author field returned the name of the Author:

{
  book {
    author
  }
}

Let’s say we realized that the Author should actually be a one-to-one connection to an object with edge space for relational context. We would want to change the schema to allow for the following query instead.

{
  book {
     author {
         node {
             name
          }
     }
  }
}

If WPGraphQL made this change, any consumer application would break.

So, what we can do is introduce the new feature like so:

{
   book {
     author
     authoredBy {
        node {
            name
        }
     }
   }
}

We could introduce the new feature as a new field name authoredBy which returns the data in the shape we want.

The end goal, however, is to have the author field return the author.node.name shape.

So, with both fields (author and authoredBy) co-existing on the server, consumer applications could make use of GraphQL Aliases and update their code from:

{
  book {
     author
  }
}

to:

{
   book {
      author: authoredBy { # Consumer uses an alias to prepare for the upcoming change to the author field
          node {
             name
          }
      }
   }
}

Once consumers have updated their code, the server could then update once more to flip the old field name to the new shape. So, the next release would have the following possible:

{
   book {
      author {
         node {
             name
          }
      }
      authoredBy {
        node {
            name
        }
     }
   }
}

So now, the old field author no longer returns the name directly, it now returns the new nested node/name shape. The client is using an alias to query the authoredBy field, so now the consumer should update their code from:

{
   book {
      author: authoredBy { # Consumer uses an alias to prepare for the upcoming change to the author field
          node {
             name
          }
      }
   }
}

to:

{
   book {
      author
          node {
             name
          }
      }
   }
}

Now, the consumer application is using the new shape of data and the old author field, and one more release would be able to remove the temporary authoredBy field that was used for seamless upgrades.