Headless WordPress uses WordPress only as the content management back end: editors still write in the familiar admin, but visitors never see a WordPress theme. Instead, a separate front end (Next.js, Astro, Nuxt, SvelteKit, or a mobile app) fetches content through the REST API or GraphQL, and renders the site. It’s popular for performance-focused sites, multi-channel content, and teams that prefer modern JavaScript frameworks.

How it fits together

Editors → WordPress admin (cms.example.com)
              │  REST API / WPGraphQL
              ▼
Front end (Next.js / Astro / Nuxt) → static build or server rendering → www.example.com
  • WordPress runs on a server (or VPS) as usual, but can be locked down, because the public doesn’t need to reach it.
  • The front end is either statically generated at build time (fastest, very cacheable) or server-rendered per request (Node.js on a VPS, or a serverless platform).
  • Webhooks trigger rebuilds or cache purges when content changes.

APIs: REST vs GraphQL

REST API (built in) WPGraphQL (plugin)
Setup Nothing to install Install the WPGraphQL plugin
Queries Fixed endpoints (/wp-json/wp/v2/posts) Ask for exactly the fields you need
Custom fields Register them in REST ACF and others via extension plugins
Best for Simple sites, quick start Complex content models, Next.js/Gatsby-style sites

See WordPress REST API.

Pros

  • Performance: static or edge-cached pages, with no PHP on the request path.
  • Security: the WordPress admin can sit on a private hostname behind IP restrictions or SSO. The public site has no wp-login.php to attack.
  • Developer freedom: use React, Vue or Svelte components, TypeScript, and modern tooling.
  • Multi-channel: the same content feeds a website, apps and other services.

Cons

  • Two systems to build and maintain, and a more complex deployment.
  • Theme-based features don’t work automatically: page builders, many plugins’ front-end output, forms, comments, and search need to be rebuilt or replaced.
  • Previews need extra work (draft previews via authenticated API requests and preview routes).
  • SEO plugins (Yoast, Rank Math) don’t render meta tags by themselves. Their data must be fetched via the API and output by the front end.
  • More moving parts means more cost and expertise.

Rule of thumb: for a typical blog or business site, a well-tuned traditional WordPress with page caching is simpler, and usually fast enough. Go headless when you need the front-end flexibility, or multi-channel delivery.

Hosting a headless setup

WordPress back end: a normal LEMP stack, but only editors and the front-end build need access.

  • Restrict /wp-admin and wp-login.php by IP, VPN or SSO. Keep /wp-json/ (or /graphql) open to the front end, with read-only public data.
  • Page caching matters less, but API response caching (an object cache, plus HTTP caching of API responses) helps builds and server rendering. See Redis object cache.

Front end:

  • Static build (Astro, Next.js static export): host the generated files with Nginx on the same or another VPS, or on a CDN. Rebuild via a webhook (a CI pipeline, or a small build server). See deploy a static Astro site.
  • Server-rendered (Next.js, Nuxt): run Node.js with PM2 or systemd behind Nginx. See deploy Next.js on a VPS and PM2.

A single 2–4 GB VPS can run both WordPress and a Node.js front end for small sites. Split them as traffic grows. See WordPress VPS hosting.

Content changes and rebuilds

  • Static sites: a webhook on publish (WP Webhooks plugin, or a small custom action) triggers your CI or build server. Incremental builds keep this fast.
  • Server-rendered: use cache revalidation (for example Next.js on-demand revalidation) from a publish webhook.

Authentication for previews and private content

  • Application passwords (built into WordPress) or JWT plugins for authenticated API requests.
  • Keep secrets on the server side of the front end, never in browser code.

See API security best practices.

Quick reference

Piece Typical choice
CMS WordPress (admin locked down)
API REST (built in) or WPGraphQL
Front end Astro (static), Next.js or Nuxt (hybrid)
Rebuild trigger Publish webhook → CI/build
Hosting LEMP VPS + static files or Node.js behind Nginx

Related: WordPress vs Ghost and static vs dynamic sites.

  • WordPress
  • Development
  • JAMstack