You installed WordPress to publish, and now someone on your team wants to rip out the frontend and rebuild it in Next.js. That is headless WordPress: keep the admin and the editor, drop the PHP theme, and serve your content to a separate frontend over an API. Done for the right reason, it makes a blog faster and frees your developers from theme templates. Done for the wrong one, it doubles what you have to maintain and quietly breaks half the plugins you were relying on. This guide walks the full decoupling process, then draws the line most tutorials skip: when the honest answer is to not go headless at all.
Key takeaways
- Headless WordPress keeps WordPress as the content backend and serves posts over the built-in REST API (
/wp-json/wp/v2/) or the WPGraphQL plugin, rendered by a separate frontend such as Next.js, Astro, Nuxt, or SvelteKit. - A decoupled setup has four moving parts: the WordPress backend, a data layer (REST or WPGraphQL), a frontend framework, and two hosting environments to deploy and patch.
- The hidden cost is real: you now run two stacks, frontend plugins like Yoast meta output and contact forms stop rendering, and preview plus SEO tags have to be rebuilt by hand.
- Frontity is discontinued and Faust.js development has slowed, so in 2026 most teams wire the REST API or WPGraphQL straight into Next.js or Astro rather than a dedicated headless framework.
- Skip headless WordPress if you have no frontend or DevOps team, lean on WordPress SEO plugins, or just want a fast multilingual blog. A purpose-built headless blog CMS is decoupled by default with no server to patch.
What "headless WordPress" actually means
Standard WordPress is coupled. The same install stores your content and renders the public pages: a PHP theme turns your posts into HTML, and the visitor sees whatever the theme decides. Headless WordPress, also called decoupled WordPress, cuts that in half. WordPress keeps managing content in the admin, but the frontend presentation layer is removed. Your posts leave WordPress as structured data over an API, and a frontend you build yourself fetches that data and renders it.
The connection point has existed for years. The WordPress REST API has shipped in core since version 4.7, exposing posts, pages, media, and taxonomies as JSON at endpoints like /wp-json/wp/v2/posts. That is what makes "headless" possible without a plugin: any frontend that can call a URL and read JSON can render your blog. The trade you are making is control for responsibility. You get to build the reader-facing site in whatever framework you want, and in return you own every part of that frontend that WordPress used to handle for you.
If you are still weighing the architecture itself, WordPress vs headless CMS and what is a headless CMS cover the decision at a higher level. This guide assumes you have decided to try decoupling and want to know exactly what it takes.
The four moving parts of a decoupled setup
Before any code, it helps to see the whole shape. Every headless WordPress build is the same four pieces.
- The WordPress backend. Your existing install keeps the block editor, media library, user roles, scheduling, and multi-author bylines. This is the part WordPress has spent twenty years getting right, and it is usually the reason to keep WordPress at all.
- The data layer. This is how content leaves WordPress. Your two options are the built-in REST API or WPGraphQL, a community plugin now stewarded by WP Engine that exposes the same data over GraphQL.
- The frontend framework. The site your readers actually see. Next.js is the most common pairing, Astro is popular for content-heavy blogs because it ships almost no JavaScript, and Nuxt or SvelteKit cover Vue and Svelte teams.
- Two hosting environments. The WordPress backend runs on its own host, and the frontend deploys separately. Wiring, preview, and cache invalidation live in the gap between them.
REST or WPGraphQL is the choice most first-timers overthink. The honest default: start with REST because it is built in and well documented, and move to WPGraphQL only when you hit a wall, usually when one page needs a post plus its author, category, and related posts in a single query. Our blog API guide covers the general fetch-and-render pattern that applies to either layer.
How to decouple the frontend, step by step
Step 1: Turn WordPress into a pure backend
You do not uninstall the theme so much as stop using it for public rendering. The REST API is already live at /wp-json/wp/v2/posts the moment WordPress is running, so the backend work is mostly hardening: lock down the admin, decide whether the WordPress domain is public or hidden behind a subdomain like cms.yoursite.com, and confirm the endpoints return the fields your frontend needs.
Step 2: Pick your data layer
For a blog, the REST API is usually enough. A single request returns a clean list of posts, and you filter by status, category, or search with query parameters. Reach for WPGraphQL when the content model gets nested, strict typing matters, or your frontend is already GraphQL-native with Apollo or Relay. Adding WPGraphQL means another plugin to install, secure, and update, so add it because the data shape demands it, not by default.
Step 3: Build and connect the frontend
This is where the real work sits. Your frontend fetches from the WordPress API and renders the result. The core loop is one function:
async function getPosts() {
const res = await fetch(
"https://cms.yoursite.com/wp-json/wp/v2/posts?per_page=20&_embed"
);
if (!res.ok) throw new Error(`WordPress fetch failed: ${res.status}`);
return res.json();
}
From there you map posts to a list page, build a dynamic route for each slug, and render post.content.rendered as HTML. If you are on Next.js specifically, our headless CMS Next.js integration walks the App Router, static params, and caching in detail. The same shape applies to Astro, Nuxt, and SvelteKit with different routing syntax.
Step 4: Rebuild preview, drafts, and auth
Coupled WordPress gives editors a live preview inside the theme. Decoupled, that preview is gone until you build it. You need an authenticated route on your frontend that reads draft content with a bearer token, and you have to teach editors that they are previewing through the frontend app, not the WordPress theme, so cache and build timing can make it behave slightly differently. This is real engineering, not a checkbox.
Step 5: Reconstruct the SEO output
Here is the tax nobody mentions upfront. Yoast SEO and Rank Math render meta tags, Open Graph, JSON-LD, and sitemaps server-side inside the WordPress theme. On a decoupled frontend, none of that carries over automatically. Yoast still works in the admin for content analysis, but its output has to be exposed through the API and re-emitted in your frontend's <head> by hand. You are effectively rebuilding a redirect map, structured data, Open Graph tags, robots rules, and sitemaps that used to be free.
Step 6: Deploy and invalidate two stacks
Finally, both halves ship. The WordPress backend keeps taking core and plugin security updates, and the frontend deploys on its own pipeline. When an editor publishes, the frontend cache has to know, usually through a webhook that triggers revalidation. Two deploy targets, two sets of logs, two things to patch.
What breaks when you go headless
The tutorials that stop at "it is faster and more secure" leave out the part where a working WordPress site loses features the day you decouple it. The honest list:
- Front-end plugins stop rendering. Anything that outputs HTML through the theme, page builders, contact forms, cookie-consent banners, becomes irrelevant. Your frontend is a separate app now, and it does not run PHP.
- SEO plugins need reconstruction. As covered above, Yoast and Rank Math still generate the data, but emitting it to the reader is your frontend's job.
- Preview gets harder. The instant, in-theme preview is replaced by custom authenticated routes you build and maintain.
- Multilingual has to be re-wired. WPML still runs in the backend and stays compatible with Yoast through its glue plugin, but the hreflang tags and locale routing that WPML normally handles in the theme now have to be reproduced on your frontend. At scale that is a project, not a setting.
- The bill grows. Running WordPress headless is not free in practice.
That last point deserves its own section, because cost is where the "should I even do this" question usually gets answered.
The real cost of running WordPress headless
The WordPress software is free. Running a production headless build is not. Managed WordPress hosting on WP Engine or Kinsta typically runs $30 to $200 a month for a backend you trust, ACF Pro for structured fields is around $59 a year, WPML for multilingual is roughly $99 to $199 a year, and a premium caching plugin adds $49 to $99. Before any custom development, the plugin bill alone commonly lands between $300 and $500 a year, and industry estimates put the build premium for going headless at 20 to 40 percent over a comparable traditional site. Then the frontend is a separate hosting cost on top.
Set that against a purpose-built headless blog CMS and the trade becomes clear. The comparison below is what actually differs day to day.
| Traditional WordPress | Headless WordPress (self-managed) | Kamaan (headless blog CMS) | |
|---|---|---|---|
| Who renders the frontend | WordPress PHP theme | Your own frontend (Next.js, Astro) | Your own frontend (Next.js, Nuxt, Astro, and more) |
| Data layer | None, coupled | REST API or WPGraphQL plugin | REST API Delivery, standard JSON |
| Servers you patch | One WordPress stack | WordPress backend plus frontend, two stacks | None, fully managed |
| Frontend SEO metadata | Yoast renders it | Rebuild by hand from Yoast data | SEO fields delivered through the API |
| Multilingual and hreflang | WPML plugin, added cost | WPML plus hand-wired hreflang on the frontend | Auto-Multilingual Delivery, hreflang server-side |
| Publish from Claude or ChatGPT | No | No | MCP Server and ChatGPT Actions |
| Running many blogs | Separate install each | Separate WordPress plus frontend each | One dashboard, Multi-Site Management |
| Typical starting cost | Hosting plus plugins | $30 to $200/mo host plus $300 to $500/yr plugins plus dev | Starter $19/mo, tiers scale by sites and languages |
The point is not that WordPress is bad. It is that headless WordPress asks you to take on a frontend, a data layer, two hosting environments, and a pile of reconstruction work, and for a blog that is often more machine than the job needs.
When to skip headless WordPress
Decoupling WordPress is a genuine fit for some teams. Go headless when you have dedicated frontend and DevOps engineers, when you need the exact same content on a website plus an app plus a kiosk, when you specifically want a React or Vue frontend you fully control, and when your editors love WordPress workflows enough to keep the backend.
Skip it, or at least pause, when any of these are true:
- You do not have a frontend developer and a DevOps function to run two stacks.
- You depend on WordPress plugins for SEO, forms, analytics, or governance.
- You mostly want a fast blog, not a multichannel content platform.
- You want a multilingual blog and do not want to hand-wire hreflang on your frontend.
If you read that list and recognized yourself, notice what you are actually asking for: a decoupled blog your frontend fetches over an API, in every language, without running a server. That is a headless blog CMS by definition, and you can start there instead of bolting it onto WordPress. Alternatives to WordPress for a blog and how to add a blog to your SaaS map that path.
How teams handle this in practice
Consider a founder running three SaaS products, each with its own blog. On self-managed headless WordPress that is three WordPress installs to patch, three data layers, and three frontends to keep alive, plus WPML on each one for languages. Moved onto Kamaan, the same founder runs all three blogs from one account and one dashboard through Multi-Site Management, fetches each product's posts into its existing frontend over one REST API shape, and switches between sites in a click. Growth at $49 a month covers three sites and three languages, so there is one bill instead of a stack of hosting and plugin renewals. Our multi-site CMS guide covers that command-center setup.
Or take a solo founder who wants an English blog that also ranks in Spanish and German. The headless WordPress route means WPML in the backend and then reproducing hreflang and locale routing on the Next.js frontend by hand. On Kamaan, the founder publishes once in English and Auto-Multilingual Delivery produces each language version at its own URL with correct hreflang emitted server-side, so the frontend just fetches the language it needs. Publish once, go live in 99+ languages on the top tier, with no hreflang wiring to maintain.
Going headless does not require WordPress at all. If the goal is a decoupled blog your frontend fetches over an API, in every language, you can start there instead of ending there.
FAQ
Is headless WordPress worth it?
It is worth it when you have the engineering resources to run two stacks and a real reason to decouple, such as omnichannel delivery or a frontend framework you must control. It is usually not worth it for a standard blog or brochure site, where the maintenance and SEO-reconstruction cost outweighs the speed gain. The rendering strategy matters more than the CMS: headless does not hurt SEO if you use server-side rendering or static generation, but it does if you ship a client-side app with no pre-rendering.
Is headless WordPress free?
The WordPress software is free, but a production headless build is not. You are paying for managed WordPress hosting, typically $30 to $200 a month, plus plugins like ACF Pro and WPML that commonly total $300 to $500 a year, plus separate hosting for the frontend, plus the developer time to build and maintain it. Factor all of that in and the total cost of ownership is often comparable to a paid headless CMS subscription.
What are the disadvantages of headless WordPress?
The main ones are added complexity from running two hosting environments, the loss of front-end plugins and visual editing, no built-in preview, and SEO output that has to be rebuilt on your frontend because Yoast and Rank Math render it server-side in the theme. Multilingual also needs re-wiring, since hreflang and locale routing no longer come from the theme.
Do SEO plugins like Yoast work with headless WordPress?
Yoast still works inside the WordPress admin for content analysis and still generates metadata, but it renders that metadata server-side through the theme, which no longer exists on a decoupled frontend. To keep the SEO benefit you have to expose Yoast's output through the REST API or WPGraphQL and re-emit it in your frontend's head. It is not automatic.
Can I use headless WordPress with Next.js?
Yes, Next.js is the most common frontend for headless WordPress. You fetch posts from the WordPress REST API or WPGraphQL, render them in App Router pages, and use static generation or incremental regeneration for caching. Frontity and Faust.js used to package this, but Frontity is discontinued and Faust.js development has slowed, so most 2026 builds wire the API into Next.js directly. Our headless CMS Next.js integration shows the full setup.
Do I even need WordPress to go headless?
No. Headless is an architecture, not a WordPress feature. If your goal is a decoupled blog delivered over an API into your own frontend, a purpose-built headless blog CMS gives you that on day one without a WordPress backend to host, secure, and patch. You skip the data-layer choice, the SEO reconstruction, and the second hosting environment entirely.
Related on Kamaan
- WordPress vs headless CMS: an honest look at when each one wins
- Blog API: how to fetch and render headless CMS content in any framework
- Headless CMS Next.js integration: step-by-step setup
- Alternatives to WordPress for a blog: 7 modern options for founders
- How to add a blog to your SaaS product
Start building with Kamaan
If you went looking for headless WordPress because you wanted a decoupled blog your developers could fetch into their own frontend, you were describing Kamaan. It is a headless blog CMS that is decoupled by design: your content leaves through REST API Delivery as standard JSON into Next.js, Nuxt, SvelteKit, Astro, React, or Vue, with no WordPress server to run and no SEO layer to rebuild. You publish once and Auto-Multilingual Delivery handles the language versions and hreflang, you run every product blog from one dashboard with Multi-Site Management, and you can write and publish straight from Claude, Cursor, or ChatGPT through the MCP Server and ChatGPT Actions. Price is the easy part: Starter is $19 a month for one site, Growth is $49 for three, and every tier includes a free first month. See how Kamaan works or compare the tiers, then start building the blog you actually wanted.
