WPGraphQL: Headless WordPress with a Real GraphQL API
WPGraphQL (~3.8k stars) adds a GraphQL schema and endpoint to WordPress so front ends (Next.js, Nuxt, SvelteKit, React Native, or custom apps) can query posts, pages, menus, users, and — with extensions — ACF fields, without wrestling the WordPress REST API's inconsistent shape and over-fetching defaults. Headless WordPress stopped being experimental years ago; WPGraphQL is the API layer many of those architectures standardize on.
What problem WPGraphQL solves
The WordPress REST API is serviceable but often requires multiple round trips, returns more data than mobile clients need, and shapes responses around WordPress internals rather than your front-end component tree. GraphQL lets the client specify exactly which fields it needs in one request:
- Fetch a page slug, title, featured image URL, and three ACF modules in one query
- Share queries between web and native apps with typed clients (Apollo, urql, Relay)
- Evolve the front end without versioning REST endpoints for every template tweak
- Integrate with static generation and ISR in Next.js App Router setups
Who WPGraphQL is for
- Teams building decoupled front ends where WordPress is the content CMS only
- Products needing web + mobile from one content source
- Developers evaluating Faust.js or similar headless WP frameworks
- Agencies standardizing on Bedrock for WordPress and JavaScript frameworks for presentation
When NOT to choose headless / WPGraphQL
- Marketing sites happy in Sage + ACF classic themes — headless adds deploy complexity
- Client must edit entirely in Site Editor with live preview — FSE block themes may fit better
- Tiny blogs with no custom front-end team — traditional themes are simpler
- Heavy reliance on WordPress plugin shortcodes in content — decoupled rendering must reimplement or sandbox them
Architecture overview
WordPress remains the source of truth for content, users, and media. WPGraphQL exposes a /graphql endpoint (configurable) registered via the plugin. Your front-end app queries that endpoint at build time (SSG), request time (SSR), or in the client (CSR) depending on framework choices. Media URLs typically still point at the WordPress uploads directory or a CDN in front of it.
Getting started (high level)
- Install WPGraphQL via Plugins → Add New or WP-CLI:
wp plugin install wp-graphql --activate - Open GraphiQL IDE in wp-admin (bundled) to explore the schema interactively.
- Query a simple post:
posts { nodes { title slug date } } - Add WPGraphQL for ACF extension when field groups must appear in the schema.
- Wire your Next.js data layer (getStaticProps, generateStaticParams, or Server Components fetch).
- Debug slow resolvers with Query Monitor on the WordPress side.
ACF on headless sites
Many headless projects store page composition in ACF — hero modules, feature grids, FAQs — while the React front end maps each layout to a component. Editors still need a usable WordPress admin for day-to-day entry. Two operational gaps appear repeatedly:
- Bulk copy updates before publishing to the front end — solved by Quickfields Bulk Editor for ACF (spreadsheet editing with autosave). Guide: Quickfields blog post.
- Schema exposure — ensure ACF field groups are registered for GraphQL via the extension; not automatic for every field type.
CSV and image bulk workflows: Quickfields Pro.
WPGraphQL vs REST vs classic theme
| Approach | Rendering | API |
|---|---|---|
| Classic Sage/ACF theme | PHP on server | Optional REST for forms |
| WP REST API only | Decoupled possible | Multiple endpoints, fixed shapes |
| WPGraphQL | Decoupled standard | Single endpoint, client-shaped queries |
Common extensions and ecosystem
- WPGraphQL for ACF — expose field groups to the schema
- WPGraphQL for WooCommerce — e-commerce headless (when applicable)
- Faust.js — Next.js toolkit from WP Engine ecosystem
- Rank Math / Yoast GraphQL extensions for SEO metadata in headless setups
Check the main repo and documentation site for current extension compatibility lists.
Gotchas
- Authentication — public read vs authenticated mutations require careful JWT or cookie strategies; do not expose draft content publicly.
- Preview mode — headless preview is harder than classic themes; plan draft URLs early.
- Cache invalidation — ISR and webhooks must trigger rebuilds when editors publish.
- N+1 in resolvers — use Query Monitor to catch expensive meta lookups per node.
- Plugin shortcodes in post_content — front end may need a parser or sanitized HTML strategy.
FAQ
Is WPGraphQL production-ready? Widely used; treat extensions and auth as project-specific engineering work.
Replace the theme entirely? Often yes for public pages — WordPress becomes CMS-only; some teams keep a minimal theme for admin.
Works with Bedrock? Yes — install like any Composer or wp-admin plugin.
Hosting? Ensure hosting allows GraphQL POST requests and does not block long query bodies at the WAF.
SEO without PHP templates? Use Yoast/Rank Math GraphQL extensions or manual meta tags fed from queried SEO fields — plan this before launch, not after.
Media handling? Images still resolve to WordPress attachment URLs; configure CDN plugins or offload media consistently so GraphQL-returned URLs match production.
Headless editorial workflow (end to end)
Editors work in familiar wp-admin with ACF field groups. Developers define GraphQL queries matching React components. On publish, a webhook triggers ISR revalidation or a static rebuild. When legal requests terminology changes across 50 pages, editors use Quickfields Bulk Editor for ACF for spreadsheet updates, then publish — the front end picks up changes on next revalidation. Developers debug resolver performance with Query Monitor on the WordPress host and optimize N+1 meta fetches. Infrastructure runs on Bedrock with deploy scripts via WP-CLI. This is the modern headless stack WPGraphQL enables — not just an API plugin, but a content pipeline architecture.