WPGraphQL: a GraphQL API for WordPress sites and headless builds

What WPGraphQL replaces on a WordPress site

WordPress ships a REST API. It is resource-shaped: you request a post, you get the post object and everything attached to it. WPGraphQL takes the other approach. The README describes it as an "extendable GraphQL API for any WordPress site", and the practical effect is that the client names the fields it wants and the server returns exactly those fields in one response. A frontend that needs a post title, its author name and three related posts issues one query instead of three REST calls and a client-side join. The plugin targets two audiences. The first is a WordPress developer who has heard of GraphQL and wants to query their own content without hand-writing REST controllers. The second is a GraphQL developer who has been handed a WordPress site and does not want to learn the WP_Query API. The README states this split directly: whether you are "a WordPress developer exploring GraphQL or a GraphQL expert diving into WordPress". The schema covers what WordPress core already models: posts, pages, custom post types, taxonomies, users and more. Anything a plugin adds, such as WooCommerce products or ACF field groups, is not in core and arrives through a separate extension.

How the schema is assembled and extended

The core plugin registers a GraphQL endpoint on the site and builds its schema from the WordPress object model. The README lists two developer-facing registration functions, `register_graphql_field` and `register_graphql_connection`, as the extension points. Those two names describe the shape of the whole system. A field adds a value to an existing type. A connection adds a paginated relationship between two types, which is how the schema expresses things like posts belonging to a category. The repository is a monorepo, and that layout is the clearest statement of intent. Under `plugins/` sit the core plugin, `wp-graphql-ide`, `wp-graphql-smart-cache` and `wp-graphql-acf`. The README draws a line between what belongs in core and what does not. Core owns the schema for WordPress core features, performance work that benefits every user, and the developer APIs. Plugin integrations such as ACF, Yoast and WooCommerce are explicitly listed as better as extensions. There is a third category called Experiments, described as proposed features that need real-world validation before committing, with the stated possibility that an experiment graduates to core or is removed. That is a real trade-off: it keeps the core schema smaller, and it means the surface you depend on can live in several repositories with separate release cycles. The release list bears this out. In the week before 2026-09-23 the repository published core versions 2.23.0 and 2.23.1 and IDE version 5.6.0, three releases across two packages.

Installing WPGraphQL and running a first query

The README's Get Started list gives the shortest path, a WP-CLI command that installs the plugin from WordPress.org and activates it in one step. Run it against the site you want to expose.

wp plugin install wp-graphql --activate

After activation the site serves a GraphQL endpoint. The README points to a hosted live demo at repl.wpgraphql.com for trying queries without installing anything, and to WordPress Playground for a browser preview of the plugin. To explore your own schema, the documentation references the GraphiQL IDE, which the README also ships as the `wp-graphql-ide` plugin in this monorepo. Open the IDE from the WordPress admin once it is active. The README's Quick Start guide is the documented next step for a first query. For contributors the README gives a different path: clone the repository and run `npm install` followed by `npm run wp-env start`, which starts a WordPress environment with all the monorepo plugins loaded. The root `package.json` requires Node 22 or newer and npm 10 or newer, and the monorepo is orchestrated with Turborepo.

Where the plugin is the wrong tool

A GraphQL endpoint is a second public surface on a WordPress install, and it inherits the site's exposure. Anything the schema exposes is reachable by anyone who can reach the endpoint, which is why the related-search list contains queries about CORS and JWT authentication: both are configuration problems that appear after the endpoint exists, not before. The README does not cover authentication or access control, so treat those as things to verify against the documentation rather than assume. The second limitation is structural. Core deliberately excludes plugin-specific integrations, so a WooCommerce or ACF query depends on a separate extension that versions independently. The README states the consequence plainly: experiments may graduate to core or be removed, while extensions live independently forever. A schema your frontend compiles against is therefore assembled from several packages, and an update to any of them can change it. Third, the plugin is the wrong choice when nothing consumes the API. A theme that renders its own templates gains no benefit from a GraphQL layer, and the site takes on a new endpoint to secure. Fourth, the project's own scope statement rules out opinionated workflows and framework-specific features, so teams expecting the plugin to decide their content modelling will not find that here.

WPGraphQL compared with the WordPress REST API

The honest comparison is not GraphQL against REST in the abstract. It is this plugin against the REST routes WordPress already registers. REST is built in, versioned by the WordPress core release cycle, and documented by WordPress itself. WPGraphQL is a plugin with its own release cadence, currently publishing patch releases within days of each other, and a schema that extensions can alter. Where the plugin wins is query shape. Fetching a post, its author and its categories over REST costs multiple requests or a request with embedded resources, and the payload still contains fields the client discards. WPGraphQL returns the requested fields in one response, which matters most on slow connections and in static builds that run hundreds of queries at build time. Where REST wins is stability and reach. A REST route is unlikely to change shape between WordPress minor versions, and it is the API that every WordPress hosting platform, caching layer and client library already understands. The plugin also carries a caching story that REST does not need in the same form: the monorepo ships WPGraphQL Smart Cache, which the README describes as providing enhanced performance, network-level caching and cache invalidation. That is an acknowledgement that a single POST endpoint is harder to cache at a CDN than a set of GET routes, and the extension exists to close that gap.

Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-09-22, one day before this writing. Core version 2.23.1 was released the same day. The README states a long-term stability goal built on semantic versioning and backward compatibility, and the repository contains a schema linter workflow alongside integration, lint, end-to-end and CodeQL checks, plus a release-please configuration and a manifest file for managing versions across packages. Those are the mechanisms that make upgrades predictable, and they cost the project effort on every change. For an operator the upgrade cost is different. You are running a plugin whose schema is partly defined by other plugins, so a core update and an extension update can land in the same week. The practical safeguard is a staging site that runs the frontend's real queries before production does. On licensing, the plugin is GPL-3.0. That is the same licence family as WordPress itself, and it means the code can be modified and redistributed under the same terms. It also means the licence does not grant trademark rights or any warranty, and nothing here should be read as legal advice about your own distribution plans.

Editorial conclusion

Adopt WPGraphQL when a decoupled frontend, a mobile app or a build step needs typed access to WordPress content and you are willing to maintain a schema that extensions can change. Skip it for a small brochure site whose theme already renders everything, or for a team that cannot test plugin updates against a schema. Before committing, install the plugin on a staging copy, open the GraphQL endpoint in the browser and confirm which post types appear in the schema, then check whether the extensions you depend on ship their own schema changes.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. wp-graphql/wp-graphql on GitHub