GraphQL originated at Facebook as a way for client applications to fetch data from many sources without needing to know all the endpoints required to acquire the data. GraphQL allows you to specify what you need without needing to know how to produce it. Facebook’s original goal with GraphQL was to address performance challenges on mobile.
WP-GraphQL is a WordPress plugin that provides a GraphQL schema and API for WordPress sites. When implemented properly, WP-GraphQL provides the potential to improve responsiveness for a number of WordPress use cases—like using it as the backend for mobile applications or as a headless CMS.
If your WordPress site only makes use of standard data types like post, category, tag, and image, you can probably stop reading now. The out-of-the-box REST API included with WordPress will likely give you all the performance you need for displaying content on your site.
If you enrich your site with a significant number of custom fields or display content in non-standard experiences, there are potential benefits to using WP-GraphQL.
Highly complex websites with massive amounts of data or websites with users who expect near real-time updates to on-page content are the most likely to benefit. Below are some specific examples where WP-GraphQL shines, followed by some reasons you may want to consider another technology solution
Pros of using WP-GraphQL
WP-GraphQL adds GraphQL support for teams already using it elsewhere
If your team is already using GraphQL for other applications in your organization, WP-GraphQL unlocks the ability to use GraphQL with WordPress. For teams with strong GraphQL experience, this provides a familiar way to structure data. For developer teams with the capacity to support additional custom development, it also makes it possible to use WordPress data in combination with other data sources.
WP-GraphQL simplifies requesting the specific data you need
Imagine being in charge of the sports section of a Chicago area news site. You keep an archive of every Chicago Cubs player, including their daily batting line from each game, in custom fields in WordPress. This way, you could reference them anytime the player comes up in the daily column about the team. WP-GraphQL gives you granular control over requesting and displaying cumulative stats for the time period from the day the columns appear back to the beginning of the season.
Using the standard WordPress REST API would require a call for each of the statistics you want to reference in the column, including data from past years. Depending on how long the player’s career is, that could be quite a few unnecessary values returned. With WP-GraphQL, you can build a query that only returns the data required to display the player’s current season statistics.
Improved developer experience
There are a number of capabilities of GraphQL that make WP-GraphQL a great tool for developing some types of content applications. It provides efficiency in creating TypeScript definitions. If your site is heavily reliant on live data, GraphQL subscriptions automatically push changes to your site. And depending on how you want to paginate, the ability to use cursor-based pagination instead of fixed page increments offers a favorable change in the user experience.
Type retrieval
If your team uses TypeScript, creating TypeScript definitions (* .d.ts) directly from the WP-GraphQL schema will speed up integration using a custom frontend in combination with the WordPress backend because the data structure is already known.
Live data with subscriptions
Event-based subscriptions allow for client applications to increment live data by telling the server what data it wants pushed back to the client. An example of this might be a feature where users react with a like or an emoji in response to a developing news story like election results. Your frontend application could subscribe to the reaction count of each user via GraphQL to receive more immediate updates to increment the count.
WP-GraphQL supports cursor-based pagination
The pagination supported by the WordPress REST API is limited to a page-based sequencing. This means if a user searches your site for a subject that has 100 results, those results will be broken into increments of 5 per page, 10 per page, or whatever other custom value you set.
WP-GraphQL allows you to configure paging based on cursor location, meaning that in a list of 100 results, if the user has seen everything up to result 8, they will always see result 9 when they increment the page, regardless of any other factors that may have changed.
If it’s a popular topic, there may have been a new story published since they started looking at the results. With standard pagination, there’s a chance that the last item on the current page becomes the first item on the following page because of the additional article. Cursor-based pagination avoids this scenario.
WP-GraphQL for headless CMS scenarios
A growing number of sites and apps are adopting WordPress as a headless CMS. The WordPress backend makes it easy to add and manage content even when WordPress isn’t acting as the frontend user experience.
WP-GraphQL provides a structured declarative way for frontends to query the WordPress data and return the specific data required to support each frontend use case. Using GraphQL also mitigates the potential for breaking changes to the required API calls in cases where individual frontend applications may be on release cycles that aren’t synchronized.
Cons of using WP-GraphQL
What we’ve highlighted so far are strengths of WP-GraphQL in some pretty specific use cases. WP-GraphQL is not without challenges. Knowing when WP-GraphQL isn’t the right solution for your website is just as important as knowing when the WordPress REST API may provide a better solution.
Caching is more complicated
One of the areas where GraphQL generally adds more complexity is in caching. REST uses predictable URLs to facilitate caching of frequently accessed resources that don’t change very often. Most content on high-traffic media or government sites falls into this category.
The GraphQL underlying queries behind WP-GraphQL are dynamic and structure-dependent, which translates to needing a custom caching solution rather than relying on the known caching solutions available to WordPress sites today.
Inconsistent plugin compatibility with WP-GraphQL
Plugins that store their data in custom table structures in the WordPress database may not be accessible to WPGraphQL without additional development. There is a growing list of Extensions to WP-GraphQL that address this for some of the more popular plugins, but it certainly doesn’t have parity with the WordPress plugin repository.
Increased CPU load compared to REST
Individual GraphQL requests have the potential to use more CPU than a REST API request for the same information. This can be further exacerbated when the GraphQL request is poorly structured.
Having expertise within your team to optimize GraphQL queries will offset this potential negative, but it’s worth highlighting as a risk. The WordPress REST API supports batch requests, which are potentially a more efficient solution to improving performance for many use cases.
The bottom line on WPGraph-QL
The key takeaway here is that WP-GraphQL is a powerful tool when you need it. Knowing when your website will benefit from WPGraph-QL over the core WordPress REST API requires careful assessment of the content presentation goals for your site.
Many websites perform at their best using the core WordPress REST API without ever needing WPGraph-QL. The team at WordPress VIP can help you align the best solution for your website with your content publishing goals.

Jake Ludington
Jake is a technology writer and product manager. He started building websites with WordPress in 2005. His writing has appeared in Popular Science, Make magazine, The New Stack, and many other technology publications.