Quick answer: Headless WordPress means using WordPress as a content API (often via the REST API shipped in core since late 2016) while a separate front end (React, Vue, static site generator or mobile app) renders the experience. Benefits include flexible UX and multi-channel content. Costs include build complexity, plugin limitations, preview friction and hosting more moving parts. Choose it when you need that flexibility; keep a classic theme when editorial simplicity and plugin ecosystems matter more.
“Headless” is a hot phrase in 2018. It is not a moral upgrade. It is an architecture trade-off.
What “headless” means here
In a classic WordPress site, PHP themes render HTML on the server using the Loop, templates and plugins that hook into that lifecycle.
In a headless setup:
- Editors still work in wp-admin (mostly)
- Content is stored in WordPress
- The public site fetches posts, pages and custom fields through HTTP APIs
- A separate application renders routes, templates and interactivity
The WordPress REST API is the usual bridge. Some teams add GraphQL via plugins; evaluate maintenance carefully.
Why teams consider it
Front-end freedom. Designers and JS developers can build UI without fighting theme template hierarchy.
Multi-channel publishing. The same CMS can feed a website, a kiosk, or a mobile app.
Performance strategies. Static generation or heavy CDN caching of API responses can be fast when designed well.
Separation of concerns. Security surface of wp-admin can be isolated from the public origin (with correct networking).
Why teams regret it
Preview and editorial workflow. “View post” is harder when the front end is elsewhere. Draft preview needs custom work.
Plugins that assume PHP themes. Many SEO, form and membership plugins inject assets or shortcodes into classic renders. In headless mode you reimplement behaviour against APIs or replace the plugins.
Authentication and previews for private content need thoughtful tokens and environments.
Complexity. Two deploys, two bug surfaces, more DevOps. Small marketing sites rarely need that weight.
Page builders. Divi/Elementor-style layouts do not translate cleanly to headless. If your marketing team lives in a builder, headless fights them. See the broader builder discussion in Divi vs Elementor.
When headless WordPress is a good fit
- You already have a JS front-end team and CI/CD habits
- You need one CMS for web plus another digital surface
- Your templates are highly interactive beyond what PHP themes express comfortably
- You can invest in custom previews and form handling
- Membership or gated content is designed against the API deliberately (not bolted on)
Membership sites on classic WordPress remain simpler for many publishers; headless membership is a larger project.
When a classic (or lightly custom) theme is wiser
- Brochure sites and blogs with standard templates
- Teams that depend on WordPress plugins for forms, SEO and ecommerce UI
- Budgets that cannot fund two platforms
- Projects that need non-developers to change layouts often without engineers
Custom theme work and custom plugin development often deliver enough flexibility without going headless.
Practical architecture notes for 2018
- Keep WordPress updated and restrict admin by IP or VPN when possible
- Decide caching at the API and CDN layers; invalidation on publish is mandatory
- Map URLs carefully so SEO-friendly paths stay stable; handle redirects in the front end or edge
- Plan Yoast or other SEO metadata delivery through the API (plugins vary in support)
- Forms: post to your own endpoints; do not assume Contact Form 7 HTML will appear magically
- Images: use media endpoint URLs and responsive strategies on the front end
- Authentication: Application Passwords are not the 2018 default story yet for all hosts; plan OAuth or JWT plugins cautiously and review security
Ecommerce deserves special caution. WooCommerce storefront UX is deeply tied to classic themes. Headless commerce is possible but is a product programme, not a weekend experiment.
Content modelling
Headless rewards clean content types: titled fields, structured blocks or fields editors understand, fewer giant freeform HTML blobs. If your current site is a tangle of page-builder shortcodes, migrate content before you celebrate the new React repo.
SEO considerations
Search engines can render modern JS, but you should not rely on hope:
- Prefer server-side rendering or static generation for public marketing pages
- Deliver accurate title tags, meta and canonicals from your front end using CMS fields
- Maintain XML sitemaps that match front-end URLs
- Watch crawl behaviour after launch
Classic WordPress themes still make many SEO basics easier out of the box.
Migration path options
You do not have to flip overnight:
- Start with a headless microsite fed by the same WordPress
- Move marketing pages first; keep app dashboards classic or vice versa
- Use the REST API for a mobile app while the website stays PHP-rendered
Prove editorial workflow before expanding scope.
Cost picture
Budget for front-end build, API hardening, preview tooling, hosting for both tiers, monitoring and training. Compare that honestly against a well-built classic theme that meets the brief. The cheaper proposal on paper sometimes ignores the second platform’s care and feeding.
Team skills checklist
Before committing, confirm you have (or can hire) people who can operate Node or static hosting, reason about caching invalidation, and support editors when preview breaks. A single excited front-end contractor without CMS backup is a risk.
Ask for a prototype that includes draft preview and one form submission full. If that prototype is painful, the full site will be too.
Hybrid compromises
Some organisations keep marketing pages on classic WordPress and build a separate JS application for a logged-in product, sharing only brand CSS. That hybrid avoids forcing the entire brochure site through a headless pipeline. Choose the smallest architecture that solves the actual product need.
Write down who owns API downtime alerts before the marketing site depends on them.
FAQ
Is headless faster by default?
No. Poorly cached API sites can be slower. Good static or SSR designs can be very fast. Classic sites with good caching can also be fast.
Can editors still use the block editor (Gutenberg)?
Gutenberg is evolving through 2018 toward WordPress 5.0. Headless teams can still use emerging block content, but rendering blocks on an external front end needs a plan. Do not assume parity.
Is the REST API secure enough?
Treat it like any public API: expose only what you must, harden auth for private routes, rate-limit abuse, keep WordPress patched.
Do we lose WordPress forever if we go headless?
No. You can return to classic themes later, though front-end investment may be sunk. Avoid burning bridges in content structure.
Choose headless for reasons you can maintain
Headless WordPress shines when you need decoupled front ends and can fund the workflow tooling. It disappoints when the real need was a cleaner theme. Weigh pros and cons against your team’s skills and editorial habits.
If you want help deciding between a classic CMS build and a more custom architecture, our CMS-focused development work includes WordPress projects on both paths, chosen for fit rather than fashion.
