When to reach for headless WordPress (and when not to)

Headless WordPress — keeping WordPress as the editing environment and rendering the front end with something like Next.js — is the most frequently requested and most frequently regretted architecture we get asked about. It is genuinely the right answer sometimes. It is also, more often, a large bill for benefits the team could have had another way.

What follows is the framework we actually use when a client asks.

What you actually gain

• A real component model. React, typed props, a design system shared with the rest of the product. If the marketing site and the app should look identical, this is the strongest argument on the list.
• Rendering control. Static generation, incremental revalidation and edge caching per route, instead of a page cache plugin you configure and hope about.
• Composability. The front end can pull from WordPress, a commerce API, a DAM and a search index and present them as one product. A theme fights you at every step here.
• A smaller attack surface on the public edge. The origin holding your content is not the origin serving your traffic.

What it actually costs

These are the costs teams underestimate, in the order they tend to hurt.

1. 01Preview stops being free. In a theme, preview is a link. Headless, it is an authenticated draft-fetch path with its own token handling, its own cache rules and its own bugs. Editors notice on day one, and it is the single biggest source of post-launch friction.
2. 02Every plugin that renders HTML stops working. Forms, galleries, SEO output, related posts, cookie banners. A plugin is a theme-layer thing; you now own its job. Budget for reimplementing each one.
3. 03Gutenberg becomes your problem. Blocks emit markup and CSS. Headless, you either parse block HTML on the front end, or map every block to a React component and keep the two in sync forever.
4. 04Two deploys, two runtimes, two on-call surfaces. Content edits may now need a revalidation hook to appear. When something does not show up, the debugging path crosses two systems.
5. 05Editors lose the WYSIWYG contract. What they see in the editor is no longer what ships, unless you invest specifically in keeping those aligned.

The decision, in the order we ask it

1. Is the front end genuinely an application?

Authenticated dashboards, configurators, real-time data, complex multi-step flows — if the site is an app with articles attached, headless is likely correct. If it is a marketing site with a blog, it is likely not.

2. Does content come from more than one place?

One CMS, one site, one audience is the case a theme handles best. The moment you are merging WordPress with a PIM, a commerce backend or a separate docs source, the composition layer earns its keep.

3. Is there already a React design system?

If the product app has one and the marketing site must match it exactly, headless removes a whole class of drift. If you would be standing one up solely for this site, that cost belongs in the comparison.

4. Who edits, and how often?

A small team publishing weekly adapts. A newsroom publishing twenty times a day, with freelancers who were trained on the classic flow, will route around a worse editing experience — usually by asking a developer to do it, which is the outcome nobody wanted.

5. What is the honest reason?

If the answer is "the site is slow", that is a performance problem and it has a much cheaper solution. We have taken sites from four-second loads to under one second without touching the architecture, by fixing queries, caching properly and dealing with the image pipeline. Headless is not a performance strategy; it is an architecture choice that makes a performance strategy easier to execute.

The middle path most teams should take first

Before rebuilding, we almost always try the version that keeps the theme and removes the actual pain:

• A hand-built block theme, no page builder. Most WordPress performance problems are Elementor or Divi emitting hundreds of kilobytes of CSS and a jQuery dependency chain.
• Full-page caching at the edge with a proper purge strategy on publish.
• Query discipline — fix the N+1 in the loop, add the missing index, stop meta_query scanning the whole postmeta table.
• An image pipeline that actually serves AVIF/WebP at the right dimensions.
• The REST API or WPGraphQL exposed for the one widget that genuinely needs to be React, embedded as an island in an otherwise server-rendered page.

That last point deserves emphasis. Headless is not binary. A server-rendered theme with two or three React islands gets most of the component-model benefit at a fraction of the cost, and preview keeps working.

If you do go headless, decide these on day one

1. 01REST or GraphQL. WPGraphQL gives you precise queries and one round trip per view; the REST API is built in and simpler to operate. Pick one and do not run both.
2. 02Preview architecture, before anything else. Draft fetching, token lifetime, and a preview route the editors can reach without a developer.
3. 03Revalidation strategy. A save_post webhook hitting an on-demand revalidation endpoint, with a tag per content type. Time-based revalidation alone will produce "why is my edit not live" tickets forever.
4. 04Block-to-component mapping, with a documented fallback for unmapped blocks so an editor using a new block gets degraded output rather than a crash.
5. 05Where forms live. They are the most common thing to break, and the most expensive to discover broken.

// Push content changes to the front end instead of waiting for a timer.
add_action('save_post', function (int $post_id, WP_Post $post): void {
    if (wp_is_post_revision($post_id) || $post->post_status !== 'publish') {
        return;
    }

    wp_remote_post(FRONTEND_ORIGIN . '/api/revalidate', [
        'timeout'  => 5,
        'blocking' => false, // never make an editor wait on the front end
        'headers'  => ['Content-Type' => 'application/json'],
        'body'     => wp_json_encode([
            'secret' => REVALIDATE_SECRET,
            'tags'   => [$post->post_type, "post:{$post_id}"],
        ]),
    ]);
}, 10, 2);

The short version

Go headless when the front end is an application, when content genuinely comes from several systems, or when an existing design system makes the composition free. Stay with a well-built theme when the job is a fast, well-structured content site — and spend the difference on performance work that will show up in the numbers either way.

Headless solves an architecture problem. Most of the time the team has a performance problem, and those have very different price tags.