Headless WordPress: Pros, Cons, Setup and Who Needs It

Headless WordPress means using WordPress only as the place where content is written and stored, while a separate front end shows that content to visitors. The front end is usually built with a JavaScript framework such as Next.js or Astro and fetches posts and pages through an API. It suits sites that publish the same content to several channels, teams with front-end developers, and products with heavy interactivity. For most business websites, a well-built traditional WordPress site is cheaper, simpler and just as fast.

This guide explains how headless WordPress works, its honest pros and cons, how to set one up, and how to tell whether your site needs it.

How headless WordPress works

A normal WordPress site does two jobs. It stores your content, and its theme turns that content into the HTML pages visitors see. A headless site splits those jobs between two applications:

• WordPress, the back end. Editors log in, write posts and upload media as usual. The theme is no longer used to render pages.
• The front end. A separate application asks WordPress for content and builds the pages. It can run on a different server, often a platform such as Vercel, Netlify or Cloudflare.

The two talk through an API. WordPress has two options:

• The REST API, which is built into WordPress core. Content is available at addresses such as /wp-json/wp/v2/posts. See the REST API Handbook.
• GraphQL, through the free WPGraphQL plugin. GraphQL lets the front end ask for exactly the fields a page needs in a single request, which is why most headless projects use it.

“Decoupled” is a related term. Some people use it for setups where the WordPress theme still renders some pages, while the front end handles others. The trade-offs below apply to both.

Pros of headless WordPress

• Content in many places. The same posts and products can feed a website, a mobile app, a kiosk, a newsletter and other sites. This is the strongest reason to go headless.
• Freedom on the front end. Front-end developers can use modern tools, components and design systems instead of a WordPress theme.
• Fast pages when built well. Pages can be generated ahead of time and served from a content delivery network (CDN), so most visits never touch the WordPress server.
• A smaller attack surface. Visitors never reach WordPress directly. The admin can be placed behind a firewall, a VPN or an IP allow list.
• Room to scale. Traffic spikes hit the CDN and the front end, not the database.
• Editors keep a familiar tool. Content teams keep the WordPress editor they already know.

Cons of headless WordPress

• Two applications to build, host and maintain. You now have WordPress and a front end, each with its own updates, hosting, monitoring and failures.
• Many plugins stop working on the front end. Page builders, sliders, popups, related-post widgets and anything else that outputs HTML through the theme will not appear on the new site. Each needs a replacement or custom work.
• Forms, search and comments need rebuilding. These are one plugin on a normal site. On a headless site, the front end has to send data back to WordPress or to another service.
• SEO needs care. Titles, meta tags, canonical URLs, sitemaps, structured data and redirects no longer come for free from your SEO plugin. The front end must read them from the API and output them. Major SEO plugins expose this data, but someone has to wire it up and test it.
• Previews are harder. Editors expect to click “Preview” and see a draft. On a headless site, that link must point to a front-end route that signs in to WordPress and loads unpublished content.
• Block editor content needs styling twice. Blocks arrive as HTML, but the CSS and layout rules from the theme are gone. The front end has to style or rebuild each block your editors use.
• Publishing may not be instant. If pages are built ahead of time, a change only appears after the page is rebuilt or the cache is cleared. This needs webhooks and a clear process.
• Higher cost. More code, more hosting and more specialist skills usually mean a bigger budget, both for the build and every year after.

Who needs headless WordPress

Headless is worth the extra work when at least one of these is true:

• You publish to more than one channel. A website plus a mobile app, a partner portal or digital signage, all fed from one place.
• You have, or will hire, front-end developers. A team that works in React, Vue or Svelte every day will be faster on a headless front end than in a PHP theme.
• The front end is an application, not a set of pages. Dashboards, configurators, calculators and logged-in tools that feel like software.
• You serve very high or very spiky traffic. News, media and launch-driven sites where serving everything from a CDN removes most of the load.
• WordPress is one source among several. A front end that also pulls from a store, a product database or a search service, with WordPress handling editorial content.
• Security rules require the admin to be private. Organizations that want no public route to the content system at all.

Who does not need headless WordPress

• Most marketing and brochure sites. If the website is the only channel, a traditional theme does the job at a fraction of the cost.
• Sites that rely on page builders. Elementor, Divi and similar tools produce layouts that a headless front end cannot use. Editors lose the ability to build pages visually.
• Small teams without front-end developers. Someone has to own the second application. If nobody can, it will age fast.
• Sites built on plugin features. Membership, learning management, booking and many WooCommerce extensions depend on the theme layer. Rebuilding their front ends is a large project.
• Sites that are slow today. If speed is the problem, fix the cause first. Our guide on why your WordPress site is slow and our Core Web Vitals guide show how. Going headless to escape a slow site often moves the problem instead of solving it.

A useful test: list the features your site uses today and ask, for each one, who will rebuild it on the front end. If that list is long and the answer is unclear, headless is probably not the right move yet.

How to set up headless WordPress

The steps below describe a common setup: WordPress with WPGraphQL as the back end, and Next.js or Astro as the front end.

1. Prepare WordPress as a content back end

Install WordPress as usual, ideally on its own subdomain such as cms.example.com. Then:

• Install and activate WPGraphQL. The GraphQL endpoint appears at /graphql.
• Model your content with custom post types and fields. If you use Advanced Custom Fields (ACF), turn on its GraphQL support so the fields appear in the API.
• Check that your SEO plugin exposes its data to the API, or add the extension that does.
• Set the site address in Settings → General so links in content point to the right place, or rewrite them in the front end.

You can test a query in the GraphiQL IDE that WPGraphQL adds to the admin:

query LatestPosts {
  posts(first: 10) {
    nodes {
      title
      slug
      date
      excerpt
    }
  }
}

2. Choose a front-end framework

• Next.js is the most common choice and has the most examples. Faust.js, a toolkit from WP Engine, adds previews, authentication and template handling for WordPress on top of Next.js.
• Astro suits content sites. It ships very little JavaScript by default and builds fast, static pages.
• Nuxt or SvelteKit are good choices for teams that already work in Vue or Svelte.

Pick the framework your developers know best. A familiar tool matters more than small differences in features.

3. Fetch content and build pages

The front end requests content from the GraphQL endpoint and turns it into pages. A minimal example in JavaScript:

const res = await fetch('https://cms.example.com/graphql', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: `query Post($slug: ID!) {
      post(id: $slug, idType: SLUG) { title content date }
    }`,
    variables: { slug: 'hello-world' },
  }),
});
const { data } = await res.json();

Decide how each type of page is built:

• Static generation builds pages ahead of time. It is the fastest option and works well for posts and landing pages.
• Server rendering builds each page on request. Use it for search results and personalized pages.
• Incremental regeneration, where the framework supports it, rebuilds individual pages in the background after content changes.

4. Rebuild what plugins used to do

Make a list of everything the old theme and plugins did on the front end, and decide how each will work now:

• SEO tags, sitemaps and redirects. Output titles, descriptions, canonical URLs and structured data from the API. Generate a sitemap from the front end, and move redirects to it or to your host.
• Forms. Send submissions to the form plugin’s REST API, for example the Gravity Forms REST API, or to a form service.
• Search. Use WordPress search through the API for small sites, or a dedicated search service for larger ones.
• Menus, widgets and global settings. Expose them through the API so editors can still change them without a developer.

5. Set up previews and publishing

• Point the WordPress preview link to a preview route on the front end that authenticates with WordPress and loads drafts.
• Add a webhook that tells the front end to rebuild or clear the cache when a post is published, updated or deleted.
• Test the full editor workflow with the people who will use it, not only the developers.

6. Lock down and host both sides

• Host the front end on a platform that supports your rendering choice. Host WordPress on a server sized for the admin and the API, not for public traffic.
• Restrict the WordPress admin by IP, VPN or single sign-on. Block the old theme from rendering public pages so search engines do not index two copies of the site.
• Limit what the API exposes. Turn off introspection in production if you do not need it, and keep draft content behind authentication.
• Keep WordPress updated and backed up as usual. See our WordPress security hardening checklist.

7. Test before launch

Treat the launch like a migration. Crawl the old and new sites and compare URLs, titles and redirects, using our migration SEO checklist. Run end-to-end tests on forms and key journeys, as described in our guide to automated testing with Playwright and PHPUnit, and load test the API with k6 so a rebuild or cache flush does not overload WordPress.

A middle ground worth considering

Many teams want one benefit of headless without the full cost. There are options in between:

• Keep the theme, add an app. The website stays traditional, and only the mobile app or one interactive section reads from the API.
• Use a block theme. Modern block themes give developers a cleaner, component-based way to build in WordPress itself.
• Put a CDN and full-page cache in front of WordPress. For sites where speed is the goal, this delivers much of the headless performance gain. See our guide to server tuning with PHP-FPM, OPcache and Redis.
• Tighten the workflow, not the architecture. If the real pain is risky changes, a Git-based workflow such as Bedrock with CI/CD may solve it.

Thinking about going headless?

Our headless WordPress service starts with an honest fit check. We look at your site, your team and your plans, and tell you whether headless is worth it. If it is, we build the WordPress back end, the API and the front end, and test the whole thing before launch. If it is not, we tell you what will get you the result you want for less. Contact us with your site address and what you hope to gain.

Frequently asked questions

What is headless WordPress?

Headless WordPress uses WordPress only to manage content. A separate front end, usually built with a JavaScript framework such as Next.js or Astro, fetches that content through the REST API or GraphQL and shows it to visitors. The WordPress theme is no longer used.

Is headless WordPress faster?

It can be, especially when pages are built ahead of time and served from a CDN. But a well-tuned traditional WordPress site with page caching is also fast. Speed alone is rarely a good reason to go headless.

Do WordPress plugins work on a headless site?

Plugins that work in the admin or on data, such as custom fields, user roles or editorial workflow, usually keep working. Plugins that change what visitors see, such as page builders, sliders, popups and many form and SEO plugins, need extra work or a replacement on the new front end.

Can editors still preview posts on headless WordPress?

Yes, but it has to be built. The front end needs a preview route that signs in to WordPress and loads draft content. Frameworks such as Faust.js help with this, but preview is one of the most common gaps in headless projects.

Is headless WordPress more secure?

It reduces exposure, because visitors never reach WordPress directly and the admin can sit behind a firewall or private network. WordPress itself still needs updates, backups and hardening, and the API becomes a new surface that needs protecting.

How much does headless WordPress cost compared to a normal site?

More, in most cases. You build and host two applications instead of one, and features that a plugin gives you for free on a normal site, such as forms, search or previews, often need custom work. Plan for higher build and maintenance costs.