Headless WordPress is the architectural pattern of using WordPress purely as a content management backend while building the public-facing frontend with a separate technology — React, Vue, Gatsby, or a mobile app. The WordPress REST API (now in core since 4.7) and the WPGraphQL plugin have made this pattern increasingly practical in 2018.
Why Go Headless?
- Performance — A static React or Gatsby frontend can be served from a CDN with sub-50ms TTFB globally
- Security — The WordPress admin is never publicly exposed; your frontend is static HTML/JS
- Developer experience — Frontend teams work with modern JavaScript tooling, not PHP templates
- Multi-channel — One WordPress instance serves content to a website, a mobile app, and a kiosk simultaneously
Option 1: WordPress REST API
Every WordPress installation (4.7+) exposes content at /wp-json/wp/v2/. Fetch posts in your React app:
useEffect(() => {
fetch('https://cms.yoursite.com/wp-json/wp/v2/posts?_embed')
.then(r => r.json())
.then(setPosts);
}, []);Option 2: WPGraphQL
The WPGraphQL plugin exposes your WordPress data as a GraphQL API at /graphql. GraphQL lets the client request exactly the fields it needs, eliminating over-fetching:
query {
posts(first: 10) {
nodes {
title
slug
date
featuredImage { sourceUrl }
}
}
}Authentication for Protected Content
For authenticated endpoints (creating posts, accessing private content), use JWT authentication via the wp-api-jwt-auth plugin. The client exchanges WordPress credentials for a JWT token and includes it in the Authorization header of subsequent requests.
Gatsby + WordPress: The Static Headless Stack
The gatsby-source-wordpress plugin pulls all your WordPress content at build time and generates static pages. Deployments update on a webhook when you publish new content. The result: a WordPress-managed site served as lightning-fast static HTML.
Trade-offs
Going headless adds architectural complexity. Real-time preview, form handling, and search require additional solutions. Comments need a third-party service or a custom API endpoint. Weigh these costs against the performance and flexibility gains before committing.
Headless WordPress is not for every project — but for high-traffic sites with dedicated frontend teams, it is a game-changer.
