Headless WordPress gets sold hard. Agencies pitch it as the modern way to build, and vendors publish case studies where everything got faster and nobody misses anything. I build headless sites for a living, and I'm going to tell you something those pitches won't: most WordPress sites should not go headless.
This post explains what headless actually changes, what it costs, and how I decide with clients whether it's worth it. I've built on both sides of this line: over nine years of classic WordPress work, and production headless builds on Next.js. My own portfolio runs on Next.js with a headless CMS (Sanity), so I use this architecture where it fits. The point is knowing where it fits.
What headless WordPress actually means
A normal WordPress site does two jobs with one piece of software. WordPress stores your content and renders your pages. Your theme's PHP templates turn database content into HTML on the server that hosts WordPress.
Headless splits those jobs. WordPress keeps the first one: editors still log in to wp-admin, write posts, and manage media. But nothing renders there. Instead, a separate frontend application (in this post, Next.js) fetches content over an API and builds the pages. The two halves can live on different servers. Visitors never touch the WordPress server directly.
The API layer is either the WordPress REST API, which ships with core, or WPGraphQL, a free plugin that exposes content over GraphQL. Both work. They have different trade-offs around caching and query flexibility, which I'll touch on later.
That's the whole idea. Everything else in the headless debate is a consequence of that split.
What you gain
I'll skip the adjectives and describe the mechanics, because the benefits are real but specific.
Performance you control end to end. With Next.js, pages can be built ahead of time (static generation) or built once and re-used until the content changes (Incremental Static Regeneration, ISR). A visitor in Melbourne gets pre-built HTML from a CDN edge node near them, not a PHP render from your origin server. There's no theme overhead and no plugin scripts you didn't choose. Core Web Vitals targets (LCP under 2.5 seconds, INP under 200ms, CLS under 0.1) are much easier to hit when you own every byte of the frontend.
To be fair: a well-built classic WordPress theme with good hosting and full-page caching can also pass Core Web Vitals. The difference is the ceiling and the consistency. Headless makes the fast path the default rather than something you defend against every new plugin.
A smaller attack surface. Your public site is static HTML and JavaScript. wp-admin, xmlrpc, wp-login, and the PHP runtime can sit behind a firewall, on a private URL, or restricted by IP. Most automated WordPress attacks are aimed at endpoints that no longer face the public.
Frontend freedom. React components, TypeScript, real code review, a component library shared with your product team. If your organization already builds with React, the website stops being the odd system nobody wants to touch.
One content source, many destinations. The same WordPress content can feed a website, a mobile app, and a partner integration through the same API. Few businesses need this. The ones that do really need it.
What you lose
This is the section the sales pitches leave out, and it's where projects go wrong.
Plugins that touch the frontend stop working. This is the big one. A WordPress plugin can add admin features (fine, wp-admin still exists) or frontend output (gone, there is no theme anymore). Contact forms, page builders, membership gates, SEO plugins that render meta tags, WooCommerce checkout, sliders, cookie banners: anything that prints HTML has to be rebuilt in the Next.js frontend. When someone quotes you a headless build, ask them to walk your current plugin list and label each one "still works", "needs rebuilding", or "needs replacing with a service". That exercise is the single best predictor of the real project cost.
Preview and editing workflows need engineering. Editors expect to click Preview and see the post. In headless, that requires wiring up a preview mode: the frontend has to fetch draft content with authentication. Next.js supports this (Draft Mode), WPGraphQL and the REST API can serve drafts, but somebody has to build and maintain the connection. The same goes for "publish and see it live immediately", which needs cache revalidation hooked to WordPress save events.
Two systems to host, deploy, and debug. You now run WordPress (somewhere) plus a Node.js frontend (somewhere else, often Vercel or similar). Two deployments, two sets of logs, two things that can break. When a page looks wrong, the answer might be in WordPress content, the API layer, the frontend code, or the cache between them.
You need a developer relationship. A classic WordPress site can limp along for years with an admin who installs plugins. A headless site cannot. If the business is not prepared to keep a developer available (freelance retainer is fine, full time is not required), do not go headless.
Real costs
Numbers vary by scope, so instead of inventing a price table, here's where the money goes:
- arrow_forwardThe build. A headless rebuild is a frontend rebuild plus API integration plus preview/workflow engineering. Expect it to cost more than an equivalent classic theme build. The frontend work is comparable, and the integration work is additional.
- arrow_forwardHosting. Often a wash or slightly higher. You still pay for WordPress hosting (it can be smaller, since it serves only editors and the API), plus frontend hosting. Vercel, Netlify, and Cloudflare all have free tiers that real sites outgrow.
- arrow_forwardMaintenance. WordPress updates continue as before. Add to that Next.js major versions, dependency updates, and API compatibility checks. Budget ongoing developer time, even if it's a few hours a month.
- arrow_forwardThe features you rebuild. Forms, search, comments, redirects. Each is a solved problem (a form service, a search service or API endpoint, a redirect map in the frontend), but each is a line item.
When headless is worth it
Concrete cases where I recommend it:
- Content-heavy sites where speed is revenue. Publishers, marketing sites with paid traffic, and businesses competing on organic search where Core Web Vitals and crawl efficiency matter at scale. Pre-rendered pages from a CDN are hard to beat.
- Teams already building in React. If your product is React and your engineers live in TypeScript, a PHP theme is the outlier in your stack. Headless brings the website into your existing workflow.
- Multi-channel content. The same content feeds web, app, and syndication. WordPress becomes a content API, which it's genuinely good at.
- High-risk security profiles. If your WordPress site keeps getting attacked, or compliance wants the CMS off the public internet, taking wp-admin off the public web removes most of the attack surface in one move.
- Sites strangled by their theme. Legacy sites where the theme and page-builder stack is so tangled that a rebuild is needed anyway. If you're rebuilding the frontend regardless, headless deserves a serious look.
When to stay on classic WordPress
Also concrete:
- Small business sites and brochures. Five to thirty pages, a contact form, a blog. Classic WordPress with a lean theme does this well for a fraction of the cost. Headless here is engineering for its own sake.
- Plugin-dependent businesses. If WooCommerce with its extensions, a membership plugin, LMS, or booking system is the core of the site, headless means rebuilding the exact features WordPress gives you free. Headless WooCommerce is possible. It's rarely worth it below serious scale.
- No developer on call. Covered above, but it disqualifies more projects than any other factor.
- "Our site is slow." Slowness alone is not a reason to go headless. Most slow WordPress sites are slow for fixable reasons: hosting, plugins, database bloat, images. A speed optimization pass costs a small fraction of a headless rebuild. Fix the actual problem first, then decide.
- Editorial teams with heavy visual workflows. If editors build landing pages in Elementor or Divi weekly and love it, headless takes that power away and replaces it with developer tickets or a block-based approximation. That trade needs to be named out loud before anyone signs off.
The stack I use
When a project does justify headless, my default stack looks like this:
- arrow_forwardWordPress with WPGraphQL for complex content models, or the native REST API for simpler ones. REST responses are plain cacheable URLs, which matters at scale; GraphQL gives the frontend precise queries and better typing. I choose per project.
- arrow_forwardNext.js App Router with ISR. Pages are statically generated, then revalidated on demand when content changes:
// app/blog/[slug]/page.tsx
export const revalidate = 3600; // safety net: refresh at most hourly
export async function generateStaticParams() {
const posts = await getAllPostSlugs();
return posts.map((slug) => ({ slug }));
}- arrow_forwardOn-demand revalidation wired to WordPress. A small mu-plugin fires a webhook on save, and a Next.js route handler revalidates just the affected paths:
// WordPress side: notify the frontend on publish/update
add_action( 'save_post', function ( $post_id, $post ) {
if ( wp_is_post_revision( $post_id ) || $post->post_status !== 'publish' ) {
return;
}
wp_remote_post( 'https://example.com/api/revalidate', [
'body' => wp_json_encode([
'secret' => REVALIDATE_SECRET,
'path' => '/blog/' . $post->post_name,
]),
'headers' => [ 'Content-Type' => 'application/json' ],
]);
}, 10, 2 );// Next.js side: app/api/revalidate/route.ts
import { revalidatePath } from 'next/cache';
import { NextRequest, NextResponse } from 'next/server';
export async function POST(request: NextRequest) {
const { secret, path } = await request.json();
if (secret !== process.env.REVALIDATE_SECRET) {
return NextResponse.json({ ok: false }, { status: 401 });
}
revalidatePath(path);
return NextResponse.json({ ok: true });
}With this in place, editors publish in WordPress and the live page updates within seconds, while every visitor still gets cached, pre-built HTML. This pattern (or its equivalent with revalidateTag) is the backbone of every headless build I ship. I go deeper on the architecture options on my headless WordPress development page.
Migrating without losing SEO
The most common fear I hear from site owners is losing rankings during the switch. The risk is real but manageable, and it comes from three places: changed URLs, missing metadata, and rendering differences.
The short version of my checklist: keep every URL identical where possible and 301-redirect the rest; reproduce titles, meta descriptions, canonicals, and structured data exactly (crawl the old site and diff against the new one before launch); prefer static generation or ISR over client-side rendering so crawlers get full HTML; keep the XML sitemap and robots rules; and watch Google Search Console daily for the first weeks after cutover. Handled this way, migrations hold their rankings. The horror stories you read online are what skipping these steps looks like.
FAQ
Is headless WordPress faster than normal WordPress? Usually, because pages are pre-built and served from a CDN. But a well-optimized classic site can pass Core Web Vitals too. Headless raises the performance ceiling and makes fast the default; it isn't the only way to be fast.
Do editors still use wp-admin? Yes. Writing, editing, media, and categories all stay the same. What changes is previewing and any page-builder workflow.
Can I keep WooCommerce? Technically yes, practically it means rebuilding cart and checkout in the frontend. For most stores I recommend against it.
What does it cost to maintain? Plan for regular WordPress updates plus a few hours of developer time a month for the frontend. If that budget doesn't exist, stay classic.
Do I need a headless setup for good SEO? No. Classic WordPress can be excellent for SEO. Headless helps when speed and rendering control are the bottleneck, and it adds SEO risk during migration if handled carelessly.
The honest summary
Go headless when the mechanics above map to your situation: speed as a business lever, a React team, multi-channel content, a hard security requirement, or a rebuild happening anyway. Stay classic when the site is small, plugin-dependent, or has no developer support. And never go headless just because the site is slow; diagnose that first.
If you're weighing this decision for a real site, I do exactly this work: honest assessments first, builds second. Details and past projects are on my headless WordPress developer page, and I work remotely with clients in Australia, Europe, and the US.