Headless WordPress: What You Gain and What You Give Up

In a headless WordPress setup, editors keep the WordPress admin and visitors never see a WordPress theme. A separate front end, usually a JavaScript application, requests content over an API and renders the pages. The split gives developers a free hand on the front end. It also removes most of what makes WordPress convenient: the theme, front-end plugins and the preview button all stop doing their job.

Whether that is a good trade depends on who maintains the site after launch. This article lays out both sides so you can judge it for your own team.

How headless WordPress works

WordPress becomes a content store with an admin screen. The front end reads from it in one of two ways.

The REST API is built into WordPress core and answers under /wp-json/. Posts, pages, media, taxonomies and users have endpoints out of the box, and the _fields parameter trims a response to what the page needs:

curl "https://cms.example.com/wp-json/wp/v2/posts?per_page=5&_fields=id,slug,title,excerpt"

Custom post types appear in the API only when they are registered for it, and custom fields have to be exposed deliberately, for example with register_post_meta() and its show_in_rest argument.

register_post_type( 'case_study', [
    'label'        => 'Case studies',
    'public'       => true,
    'show_in_rest' => true,
    'supports'     => [ 'title', 'editor', 'excerpt', 'thumbnail', 'custom-fields' ],
] );

WPGraphQL is a free, open-source plugin that adds a GraphQL schema and endpoint to the site. The front end sends one query describing exactly the fields a page needs, across posts, authors, terms and menus, and gets one response. Teams building with component frameworks tend to prefer it. The trade-off is a dependency on a plugin and its extensions for anything beyond core data, where the REST API ships with WordPress. The general comparison is in REST, GraphQL or webhooks.

The front end is typically built with a framework such as Next.js, Nuxt or Astro. It renders pages at build time, on a server at request time, or a mix of the two.

What you gain

Front-end freedom. The site is built from the same components, design system and tooling as the rest of your web products. Nothing in the markup is dictated by a theme or a page builder.

One content source for several channels. The same articles, products or course descriptions can feed the website, a mobile app and a partner portal without being copied.

A smaller public surface. Visitors reach the front end, not WordPress. The admin can sit on a separate hostname behind an IP allowlist or single sign-on. WordPress still has to be patched, but far less of it faces the internet.

Performance headroom. Pre-rendered pages served from a CDN are fast and stay fast under traffic spikes. Be honest about the baseline, though: a well-cached conventional WordPress site with a lean theme is fast too. If speed is the only goal, performance optimization of the existing site is a much smaller project than a rebuild.

What stops working when the theme goes

Everything WordPress and its plugins print on the public site disappears, because nothing renders that output any more. Each item below becomes development work in the front end:

• Plugins with front-end output. Forms, sliders, popups, related posts, cookie banners, comment forms and membership gates store their settings in WordPress, but their HTML, CSS and JavaScript never reach the visitor. Forms have to be rebuilt in the front end and submitted to the plugin's API or to another service.
• SEO output. Titles, meta descriptions and structured data are still edited in WordPress, and several SEO plugins expose them through the API. Your front end has to fetch and print them. The XML sitemap and redirects must be produced by the front end or the CDN, since WordPress's own versions describe a site visitors no longer reach.
• Block styling. Post content arrives as HTML in content.rendered. The styles and scripts that blocks rely on do not come with it, so every block your editors use needs matching CSS, and interactive blocks need reimplementing.
• Site Editor, Customizer, widgets and menus. Template editing in the admin has no effect. Menus can still be managed in WordPress, but only if the front end is written to request and render them.
• Links and media addresses. Links inside content point at the CMS hostname and have to be rewritten. Images are still served from the WordPress uploads folder unless you add an image service.
• Logged-in features. Password-protected posts, member content and anything in WooCommerce's cart, checkout and account pages need custom authentication and a great deal more work. See headless commerce explained before going that way with a store.

Previews and publishing have to be rebuilt

This is the part editors feel first. In a standard install, the Preview button opens the theme with the unsaved draft. With no theme, it shows nothing useful.

A working headless preview needs three pieces. The preview link is changed, with the preview_post_link filter, to open a preview route on the front end. That route identifies the editor and requests the draft or latest revision from WordPress with authenticated credentials, since drafts are not public. And the front end renders it with the same components as the live page. The REST API authentication documentation covers application passwords, which are the built-in way for an external application to make authenticated requests.

Publishing needs the same attention. If pages are pre-rendered, pressing Publish changes nothing on the live site until the front end rebuilds or revalidates that page. WordPress has to notify it, usually with a webhook fired when a post is saved, and menus, global settings and deleted posts need the same treatment. "I published it and nothing happened" is the most common complaint we hear about headless builds we are asked to take over.

You now run two applications

A headless site is two systems with a contract between them.

• WordPress still needs PHP hosting, a database, updates, backups and security monitoring.
• The front end needs its own hosting, a build pipeline, environment variables, error monitoring and regular framework upgrades.
• Between them sit API authentication, cross-origin rules, caching and the webhooks that keep the two in step.

The larger cost is organizational. On a conventional site, a marketer who wants a popup, a new form or a landing page layout installs a plugin or uses the editor. On a headless site each of those is a ticket for a front-end developer. That is fine for a company with a product team, and a constant source of friction for one without.

Who should go headless, and who should not

It suits you when most of these are true:

• You employ or retain front-end developers who will stay with the site.
• Content feeds more than one channel, or the site is one part of a larger web application.
• The design system is strict and shared across products.
• Editors mainly write structured content and do not need to compose layouts freely.

It is the wrong choice when the site is run by a small marketing team that depends on plugins and a page builder, when the motive is speed alone, or when there is no budget for continuing development after launch.

A middle path exists. Keep WordPress rendering the site with a well-built custom theme, and use the REST API only for the parts that need application-like behavior, such as a product configurator, a search interface or a dashboard. You keep previews, plugins and the editor, and add a JavaScript front end where it earns its place.

Test the decision before you commit

Do not decide from a demo of a blog index. Build a small proof of concept that includes the hard parts: one custom content type with custom fields, a working draft preview, one form submitting end to end, the SEO fields in the page head and a publish action that updates the live page within seconds. If your team builds that comfortably, the full project is realistic. If it stalls on previews, you have learned that cheaply.

For a second opinion on the architecture, or for the WordPress side of the contract (custom endpoints, authentication, webhooks, field modelling), that is our WordPress API and integration work.

Frequently asked questions

Is headless WordPress faster than a normal WordPress site?

It can be, because pages are pre-rendered and served from a CDN. A conventional site with full-page caching, optimized images and a light theme reaches similar results for most visitors. Headless raises the ceiling. It does not fix a slow site by itself.

Does going headless hurt SEO?

Not if the front end renders pages on the server or at build time and outputs titles, descriptions, canonical tags, structured data, a sitemap and redirects correctly. The risk is that all of this becomes your code to write and test, where a plugin handled it before.

Can editors still use the block editor?

Yes. They write in the same editor, and the front end receives the rendered HTML. The limit is that what they see in the editor only matches the live site if developers style each block in the front end the same way.

Can we go back to a normal theme later?

Yes. The content never left WordPress, so returning means building or installing a theme and pointing the domain back at WordPress. Custom fields and post types carry over as they are.