Short answer: headless WordPress means using WordPress as a content backend (API and database) while building the public-facing site in a separate frontend framework like Next.js, Nuxt, or Astro. The frontend pulls content from WordPress through the REST API or GraphQL and renders it with whatever technology the team prefers. You get WordPress’s admin experience for content editors and modern JavaScript framework tooling for developers – at the cost of running two systems instead of one.
Headless is the right choice for sites where editorial teams need WordPress’s publishing flow but the user experience demands modern frontend performance, custom interactivity, or framework-specific features. It is overkill for a standard marketing site or blog, where classic WordPress with good hosting and caching delivers the same end result with half the infrastructure.
What headless WordPress actually means#
A standard WordPress site is coupled: the same PHP process that stores your posts in the database also renders the HTML that visitors see. When a request comes in for
/blog/my-post/
, WordPress looks up the post, passes it through the active theme’s template files, and sends back a fully-rendered HTML page. One system, one process, one codebase. This is the “monolithic” or “coupled” architecture that WordPress has used since 2003.
Headless WordPress decouples those two concerns:
- The WordPress install keeps the admin dashboard, the database, the user management, the media library, and the plugins that affect the admin side. It does not render the public site.
- A separate frontend application queries WordPress through its API for content, then renders HTML or JSON to the visitor using a different technology stack. The frontend could be Next.js, Nuxt, Astro, Gatsby, SvelteKit, a native mobile app, or anything else that can make HTTP requests.
The WordPress install runs on PHP hosting as before. The frontend runs wherever that framework runs – static-site hosting, a Node.js server, a CDN edge network. Visitors hit the frontend. The frontend talks to WordPress in the background.
“Headless” means the head (the rendered frontend) has been removed from the body (WordPress itself). You add a new head built however you want.
How the WordPress REST API enables headless#
Since WordPress 4.7 (released in 2016), every WordPress install ships with a REST API enabled by default. Visit
yoursite.com/wp-json/wp/v2/posts
on any WordPress site and you get a JSON response with the latest posts:
[
{
"id": 123,
"slug": "my-post",
"title": { "rendered": "My Post" },
"content": { "rendered": "<p>Post body HTML...</p>" },
"date": "2026-04-20T10:00:00",
"featured_media": 45,
...
}
]A frontend application makes a
fetch
or
GET
request to that URL, receives the JSON, and renders however it wants – React components, Vue templates, Svelte, raw HTML, a native iOS view. The same endpoint supports pages (
/wp-json/wp/v2/pages
), custom post types (
/wp-json/wp/v2/products
), categories, tags, media, users. Write operations work too – POST, PUT, DELETE – authenticated via application passwords or JWT.
REST API vs WPGraphQL
The REST API is the default, but many headless WordPress setups use the WPGraphQL plugin instead. GraphQL lets the frontend ask for exactly the fields it needs in a single query, which reduces over-fetching and the number of round-trips compared to REST. For sites pulling multiple related resources (a post plus its author plus its category plus its featured image), GraphQL is usually faster.
| Feature | REST API | WPGraphQL |
|---|---|---|
| Built into WordPress | Yes, since 4.7 | No, requires plugin |
| Query flexibility | Fixed endpoints per resource | Ask for any fields in one query |
| Typical requests per page | 3-10 | 1 |
| Caching | Standard HTTP caching | Harder – single query varies by fields |
| Learning curve | Lower (standard HTTP) | Higher (query language) |
| Best for | Simple integrations, mobile apps | Complex frontends, Next.js/Nuxt sites |
Pick REST if you are building something simple or want standard HTTP semantics. Pick WPGraphQL if your frontend pulls a lot of related content or uses a framework with good GraphQL tooling (Next.js, Gatsby, Apollo).
Why developers choose headless#
Three main reasons, in roughly decreasing order of importance:
Frontend performance. A Next.js site with static-generated pages and client-side hydration loads faster than a classic WordPress site in most real-world conditions, even before aggressive caching. Static HTML served from an edge network with zero PHP overhead is simply faster than PHP-rendered HTML, even if the PHP response is cached. For sites where Core Web Vitals directly affect business metrics (e-commerce, SEO-critical content), the performance delta is worth the architectural complexity.
Modern frontend tooling. React, Vue, and Svelte have ecosystems for interactivity, animations, client-side routing, and state management that WordPress themes cannot match without extensive custom work. Teams building sites that feel like applications (dashboards, configurators, interactive learning platforms) find it faster to build in a JavaScript framework than to extend a WordPress theme.
Content reuse across surfaces. The same WordPress install can feed a website, a mobile app, a partner site, and an email newsletter service through the API. When content strategy involves multiple surfaces, one coupled WordPress install cannot power all of them – but one headless WordPress install can.
Less commonly, teams go headless because they want to replace the frontend technology while keeping existing editors trained on WordPress, or because compliance requires separating the CMS from the public-facing application, or because they want to host the frontend on infrastructure WordPress cannot run on (edge workers, static-site hosts).
The real tradeoffs#
Headless WordPress is not a pure upgrade. You are trading one set of problems for another, and the trade is only worth it if you actually benefit from what you gain.
You lose the theme system
The biggest loss. WordPress themes are a massive asset – thousands of professionally designed options, installation in one click, customization through the theme customizer, a community that shares tricks and fixes. Going headless throws all of that away. You build the frontend from scratch in a framework. No existing theme helps you.
For teams with in-house frontend developers this is fine. For small businesses or non-technical site owners, it is a dealbreaker – the admin still looks like WordPress, but nothing about the public site follows WordPress conventions and no theme marketplace exists for your chosen frontend framework.
Plugins that affect the frontend stop working
This is the second biggest surprise. Plugins that modify the admin (Yoast, Advanced Custom Fields, WooCommerce, members, forms) usually still work. Plugins that output HTML or run JavaScript on the frontend (contact forms, sliders, social sharing buttons, countdown timers, 90% of plugins in the wordpress.org repo) need custom reimplementation in the frontend framework.
If your current site depends on a Gravity Forms setup, a specific slider plugin, or WooCommerce’s frontend checkout, going headless means rebuilding those flows in your frontend framework. Some plugins publish headless-compatible versions (WooCommerce has headless patterns, Gravity Forms has a REST API), but many do not.
Preview is harder
In a coupled WordPress site, the “preview” button opens the admin’s rendered version of the post. In headless, preview requires extra infrastructure – the frontend has to know how to fetch draft content, authenticate as the editor, and render the in-progress version separately from the public site. Teams usually build a separate preview subdomain that pulls directly from WordPress with admin credentials. It works, but it is extra work.
Most editorial teams underestimate how much they rely on preview until it stops working like they expect.
Two things to deploy
Every code change might affect the WordPress side, the frontend side, or both. Deploys become a two-step process. CI/CD pipelines get more complex. Testing strategies have to cover the frontend in isolation, the WordPress API in isolation, and the integration between them.
Managing one WordPress install is a few commands. Managing WordPress plus a separate frontend application is operations work that needs documentation, runbooks, and someone responsible when either side breaks.
More moving parts to secure
Two systems mean two attack surfaces. The WordPress admin still needs all the WordPress hardening that a coupled site needs. The frontend adds its own concerns – API token management, rate limiting the public API, CORS configuration, and the dependencies of whatever JavaScript framework you picked.
The admin URL of the WordPress install becomes a target worth hiding. WordPress login URL hardening applies even more in a headless setup because the admin is the only entry point for content editors – if attackers find it, they control the entire content pipeline.
When headless is the right choice#
- Sites where frontend performance directly affects revenue or SEO. E-commerce, high-value lead generation, media sites where ad impressions depend on page speed.
- Teams with frontend developers who prefer modern frameworks. You already have people who can build and maintain a Next.js or Nuxt application – using their skills beats fighting WordPress theme development.
- Multi-channel content strategy. The same content feeds a website, a mobile app, a kiosk display, a partner integration.
- Replatforming the public site without retraining editors. The marketing team loves WordPress. The new website needs to feel like a modern application. Headless bridges that gap.
- Existing WordPress installs that outgrew their theme. You have years of content in WordPress and do not want to migrate it, but the current theme cannot deliver the experience you need.
When headless is overkill#
- Standard marketing sites. A coupled WordPress site with a good theme, solid hosting, and proper caching performs well for most marketing traffic. Headless adds complexity without a proportional benefit.
- Blogs with a single editor. One-person operations almost never need the complexity of two codebases.
- Sites with no in-house frontend expertise. Without a developer who understands React, Vue, or similar, headless creates a permanent dependency on outside contractors.
- Budget-constrained projects. Headless doubles the infrastructure, deploy pipeline, and maintenance effort. Projects that cannot afford to maintain both should not start both.
- Sites heavily dependent on page builders or plugin-driven frontends. Elementor, Divi, Beaver Builder, visual composers – none of these translate to a headless frontend. If your entire site is built in Elementor, headless means rebuilding everything.
The rule of thumb: if the existing coupled site works, performs well, and editors are happy, headless is not the answer to a problem you have. If any of those three are failing for reasons a better theme or better hosting cannot fix, headless becomes worth considering.
Hosting requirements for headless WordPress#
A headless setup needs hosting for two things: the WordPress install and the frontend application.
The WordPress backend
Still a standard PHP + MySQL WordPress install. The same hosting requirements apply – PHP 8.x, decent database performance, reliable backups, security updates. The one difference is that the public traffic no longer hits WordPress directly, so WordPress hosting requirements scale with editorial team size and API request volume rather than with public visitor count. A WordPress backend serving 100,000 visitors through a static-generated Next.js frontend barely notices the load – most requests are build-time, not per-visit.
Managed WordPress hosting works fine for the backend. You need the admin, the API endpoints, and the reliability – not the frontend rendering pipeline. See how to choose WordPress hosting for what to look for.
The frontend
The frontend hosting depends on the framework:
- Static-generated sites (Astro, Next.js with
getStaticProps, Gatsby): deploy to any static-file host. Vercel, Netlify, Cloudflare Pages, and standard web hosting all work. - Server-rendered sites (Next.js with
getServerSideProps, Nuxt with SSR, Remix): need a Node.js runtime. Vercel and Netlify support this natively. Other hosts need application deployment support. - Incremental Static Regeneration (ISR): Next.js can combine static generation with on-demand rebuilds when content changes. Requires a host that understands ISR – typically Vercel, or a Node.js runtime that can handle the revalidation API.
For most headless WordPress projects, the frontend is the part that attracts the most attention at hosting-selection time. The WordPress backend is almost always an afterthought: “we already have WordPress hosting, we just need somewhere to run the Next.js app.”
Two hosts, or one
The conventional approach is two hosts: WordPress on one (a managed WordPress provider), the frontend on another (Vercel, Netlify, Cloudflare Pages). This works but adds operational overhead – two dashboards, two billing relationships, two sets of credentials, two places to investigate when something breaks.
Some hosts – including Hostney – support both workloads on the same infrastructure. You run the WordPress backend on a WordPress-optimized account, and deploy the Next.js or Nuxt frontend as a separate application to the same platform. One dashboard, one billing relationship, one vendor for incident response. The two halves of your headless site live in the same account but stay architecturally separate.
How Hostney fits into a headless WordPress setup#
Hostney supports both sides of a headless project natively.
For the WordPress backend, every Hostney account is a container-isolated WordPress install with the stack tuned for WordPress: OpenResty edge caching, PHP-FPM, Redis object caching, automated Let’s Encrypt SSL, per-site isolation, snapshot backups. The WPGraphQL and REST API endpoints work out of the box. Bot protection filters exploit traffic at the edge so the API is not constantly dealing with scanner noise.
For the frontend, Hostney’s application deployment handles Next.js, Nuxt, React, Vue, Angular, Astro, and other frameworks through Git integration. You connect a repository, pick the framework, and the platform handles the build and deploy pipeline. Two deployment modes are available:
- Static serve (SPA): the framework builds static files, the platform serves them from the edge. Available on all plans including the free trial.
- Container/SSR: the framework runs as a Node.js application with blue-green deployment for zero-downtime updates. Available on paid plans.
Because both halves run on the same infrastructure, the internal network connection between the frontend and the WordPress API is fast and does not incur cross-provider egress costs. If you need to rotate API credentials, both halves are in the same control panel. If you need to check logs across both systems during an incident, they are in the same place.
This is a different model from “host WordPress here, host Next.js there” and it makes sense specifically for teams who do not want to manage two vendor relationships for what is architecturally one website.
Summary#
Headless WordPress is a legitimate architecture for teams that actually benefit from the split – frontend performance needs modern tooling, editorial teams love the WordPress admin, content serves multiple surfaces. It is the wrong answer for most standard WordPress sites, where a well-hosted coupled install delivers 90% of the benefit with a fraction of the infrastructure.
The REST API or WPGraphQL gives the frontend a way to fetch content. The frontend framework – usually Next.js or Nuxt – handles rendering. The two halves deploy separately and communicate over HTTP. You keep WordPress’s admin and publishing experience while choosing your own rendering technology.
If you are evaluating headless seriously, start by confirming the existing coupled site cannot do the job with better hosting and a cleaner theme. If the answer is still headless, plan for the operational overhead of maintaining two systems and pick a hosting story for both halves before you start building.
For related reading: how to choose WordPress hosting covers what to look for in the WordPress-backend half, and WordPress alternatives is worth reading if you are still deciding whether to use WordPress at all versus a full JAMstack CMS like Contentful or Sanity.