Headless WordPress has become the default recommendation in developer circles and at WordPress conferences. The pitch is compelling: decouple the frontend from WordPress, use React or Next.js for rendering, consume WordPress content via the REST API or WPGraphQL, and deploy the frontend to Vercel or Netlify for edge-cached performance. The architecture diagrams look clean and modern. The developer experience feels like a significant upgrade from PHP templating. The conference talks are inspiring. And in roughly 60% of the projects where we have seen headless WordPress implemented in production, it was the wrong architectural choice that added cost and complexity without proportional benefit.

That is not a criticism of headless architecture as a concept. It is a criticism of applying it indiscriminately without honest evaluation of trade-offs. At Harbor Software, we have built both traditional WordPress sites and headless WordPress sites for production use. We have migrated traditional sites to headless when the use case justified it, and in two cases, we have migrated headless sites back to traditional WordPress because the headless architecture was creating more problems than it solved. Both approaches have clear strengths and equally clear failure modes. Here is a decision framework for choosing between them based on actual project requirements rather than architectural fashion or developer preference.

What Headless Actually Means in Practice (and What It Costs)

In a traditional WordPress setup, WordPress handles everything end-to-end: content management in the admin panel, template rendering through PHP theme files, and frontend HTML delivery to the visitor’s browser. A visitor requests a URL, WordPress’s PHP engine processes the request, queries the MySQL database, applies the appropriate theme template, assembles the HTML, and returns the complete page.

In a headless setup, WordPress handles only content management and storage. The frontend is a completely separate application, typically built with React, Next.js, Nuxt.js, or Astro, that fetches content from WordPress via its REST API or through a GraphQL layer like WPGraphQL. WordPress becomes a “content API backend” rather than a complete website that generates pages. The frontend application is deployed, hosted, and maintained independently from WordPress.

The immediate, concrete costs of going headless are predictable and should be budgeted before making the architectural decision:

• Two codebases instead of one. You now maintain a WordPress installation (PHP, plugins, database) for the backend CMS and a separate JavaScript application for the frontend. These require separate deployment pipelines, separate hosting environments with different requirements, separate dependency management, separate monitoring, and separate security considerations. When something breaks, you must diagnose whether the issue is in WordPress, the API layer, or the frontend application.
• The WordPress plugin ecosystem is effectively halved. Plugins that modify frontend rendering, which includes page builders like Elementor, SEO plugins that inject structured data and meta tags, schema markup generators, related posts widgets, comment systems, and any plugin that outputs HTML on the visitor-facing site, do not work in a headless setup. Their admin-side functionality (data storage, settings UI, content analysis) may still work, but anything that generates frontend output must be reimplemented manually in your JavaScript frontend code.
• Content preview is broken by default and difficult to fix. WordPress’s built-in “Preview” button renders a PHP-based preview using the active theme. In a headless setup, the preview must somehow reach your decoupled frontend application with the draft content, which requires custom preview URL configuration, authentication token passing, and often a dedicated preview deployment. In our audits of headless WordPress sites built by other agencies, approximately 75% have broken or completely absent preview functionality. Content editors cannot see their changes before publishing, which is a severe usability regression from traditional WordPress.
• Development cost is 2-3x higher for equivalent functionality. Every feature that WordPress handles automatically in a traditional setup must be manually implemented in the headless frontend: URL-based pagination with proper SEO markup, archive pages with correct post counts, search functionality with relevance ranking, custom 404 pages, XML sitemap generation, canonical URL management, breadcrumb navigation, and Open Graph meta tags. We track development hours meticulously: a 20-page business website takes 80-120 hours with traditional WordPress. The same site with identical functionality built headless takes 200-350 hours.

When Headless Is Genuinely the Right Choice

Despite the costs, headless WordPress is the correct architecture for specific, identifiable use cases. The common thread across these use cases is that they have technical requirements that traditional WordPress genuinely cannot meet without extensive hacking that would be more expensive and fragile than a clean headless implementation.

Multi-Platform Content Delivery

If the same content needs to be consumed and displayed by a website, a native iOS/Android mobile application, a digital signage system in retail stores, and potentially a smart TV or voice assistant application, headless is the only sensible architecture. Traditional WordPress renders content as HTML, which browsers can display but native applications cannot use directly. A headless WordPress API delivers structured JSON data that any client platform can consume and render in its native format and design language.

// WordPress REST API response - platform-agnostic structured data
{
  "id": 142,
  "title": { "rendered": "New Product Launch" },
  "content": { "rendered": "<p>We are excited to announce...</p>" },
  "acf": {
    "hero_image": {
      "url": "https://cdn.example.com/hero.webp",
      "width": 1920,
      "height": 1080
    },
    "launch_date": "2024-06-01",
    "product_id": "SKU-4521"
  }
}
// The web app renders this as a responsive HTML page with CSS
// The iOS app renders it as a native SwiftUI view
// The digital signage renders it as a fullscreen kiosk display
// All platforms consume the same API, managed from one WordPress admin

Performance-Critical Applications Requiring Global Edge Delivery

If your application has a hard business requirement for sub-100ms Time to First Byte globally (not just a nice-to-have for Lighthouse scores), traditional WordPress cannot achieve this without aggressive full-page caching that introduces significant delays when content is updated. A headless setup with static site generation (Next.js with ISR or Astro with on-demand revalidation) pre-renders pages and serves them from CDN edge nodes worldwide, achieving 20-50ms TTFB regardless of the visitor’s geographic location or the WordPress server’s response time.

// Next.js ISR with WordPress as content source
export async function getStaticProps({ params }) {
  const res = await fetch(
    `https://cms.example.com/wp-json/wp/v2/posts?slug=${params.slug}`
  );
  const posts = await res.json();
  return {
    props: { post: posts[0] },
    revalidate: 60  // Regenerate in background every 60 seconds
  };
}
// Result: visitors always get a pre-built static page from CDN edge
// WordPress server is never in the critical request path
// Content updates propagate within 60 seconds automatically

Complex Interactive Frontend Applications

If the frontend requires substantial client-side interactivity such as real-time collaborative editing, complex multi-step product configurators with live 3D previews, interactive data visualizations that respond to user input, or single-page application flows with client-side routing, a React or Vue frontend provides dramatically better developer tooling, component architecture, and user experience than WordPress themes augmented with jQuery scripts.

When Traditional WordPress Is the Right Choice

Traditional WordPress is the correct architecture when none of the headless triggers above apply, which encompasses the majority of business websites that we encounter in our agency work.

Content-focused websites (blogs, corporate sites, landing page collections, documentation portals) work better with traditional WordPress because the CMS, theme system, and plugin ecosystem are specifically designed for this use case. SEO plugins, page builders, block editors, search, archives, and preview all work out of the box. Going headless for a content site means spending 100+ hours reimplementing functionality that WordPress provides for free.

E-commerce with WooCommerce is almost always better served by traditional WordPress because WooCommerce’s checkout flow is deceptively complex. It handles address validation, real-time shipping rate calculation, coupon stacking rules, jurisdiction-based tax calculation, payment gateway integration with 3D Secure authentication, inventory reservation during checkout, and order creation with email notifications. Reimplementing this complete flow in a React frontend is easily a 200-hour project with ongoing maintenance costs as WooCommerce updates its checkout behavior.

Teams without dedicated JavaScript frontend engineers should avoid headless WordPress entirely. A team of skilled WordPress/PHP developers can build and maintain excellent traditional WordPress sites. The same team will produce fragile, unmaintainable React frontends because headless requires fundamentally different skills: client-side state management, API integration patterns, build tooling (webpack/Vite/TypeScript), and deployment workflows that are foreign to PHP-focused developers.

The Hybrid Approach: Best of Both Worlds

The headless-versus-traditional choice is not binary. Our most successful architecture for complex sites is a hybrid: traditional WordPress with PHP rendering for the 80% of pages that are content-driven and benefit from the plugin ecosystem, combined with embedded React components for the 20% of features that require rich client-side interactivity.

// Hybrid: WordPress renders the page, React handles interactive features
// WordPress serves the page shell with standard PHP theme rendering
// React components mount in designated container divs via shortcodes
// Both layers share authentication through WordPress cookies
// Result: content team keeps full CMS editing capability
// Engineers build interactive features with modern tooling
// Performance overhead is limited to pages that actually need React

This hybrid approach delivers the pragmatic benefits of both architectures: WordPress’s content management, preview, SEO plugins, and theme system for the majority of the site, plus modern JavaScript components for features that genuinely benefit from client-side rendering. The development cost is lower than full headless because you only build custom frontends for features that actually need them, and the content team retains the editing experience they know and prefer.

The Decision Framework

When evaluating whether to go headless, run through these six questions honestly:

1. Does the content need to be consumed by non-web clients (mobile apps, IoT devices, digital signage)? If yes, headless is justified.
2. Does the frontend require complex interactivity beyond what progressive enhancement and modern CSS can provide? If more than 2-3 features need it, consider headless or hybrid.
3. Is sub-100ms global TTFB a hard business requirement with measurable revenue impact? If yes, headless with static generation.
4. Does your team include dedicated frontend engineers with production React or Vue experience? If no, traditional WordPress is the safer choice.
5. Is the content team comfortable working without visual preview and without a page builder? If no, traditional WordPress preserves their workflow.
6. Can the project budget absorb 2-3x the development hours compared to traditional? If no, headless will blow the budget.

If you answered “no” to questions 1 through 3, traditional WordPress is almost certainly the right architectural choice. The headless approach will cost more money, take longer to build, introduce more operational complexity, and deliver a result that is functionally equivalent to what WordPress provides with a good theme and proper optimization.

The Migration Reality: Lessons from Both Directions

We have migrated sites in both directions: traditional to headless and headless back to traditional. Both migrations are more expensive than most teams anticipate, which is why the initial architectural decision matters so much.

Migrating traditional WordPress to headless typically takes 2-3x longer than building headless from scratch because you are not just building the new frontend. You are also reverse-engineering all the implicit functionality that WordPress and your plugins provided automatically: how permalinks resolve, how search works with relevance ranking, how 301 redirects from old URLs are handled, how XML sitemaps are generated with proper lastmod dates, how canonical URLs prevent duplicate content, how pagination works with the correct total page count for SEO, and how image srcsets are generated for responsive loading. Each of these features exists as a WordPress plugin or core function that works transparently. In a headless frontend, each becomes a development task with its own edge cases and testing requirements.

Migrating headless back to traditional, which we have done twice, is equally painful but for different reasons. The content in WordPress is usually fine since the CMS never changed. The challenge is recreating the frontend design within WordPress theme constraints. Custom React components with complex state management, animated transitions, and client-side routing do not translate directly to PHP templates. You end up rebuilding the design from the original mockups rather than porting the React code, which means the migration is essentially a redesign project with all the associated cost and timeline.

Both of our headless-to-traditional migrations were motivated by the same root cause: the client’s content team could not effectively manage the site without developer assistance. In one case, the content team needed to update product descriptions, add new blog posts, and create landing pages for seasonal campaigns. Every change required a developer to update the React components, rebuild the static site, and deploy the updated frontend. What should have been a 15-minute task for a content editor became a 2-hour development ticket. The client calculated that they were spending $3,000-$5,000 per month in developer time for content changes that their previous traditional WordPress site would have handled through the admin panel at zero marginal cost.

API Performance and Caching Considerations

A detail that headless advocates often gloss over is the performance of the WordPress REST API itself. The default REST API is not designed for high-throughput frontend rendering. A typical blog listing page might require multiple API calls: one for the posts, one for featured images (since they are separate media objects), one for author data, and one for category and tag information. That is four round trips to the WordPress server for a single page render, each adding 100-300ms of latency depending on server location and database complexity.

WPGraphQL solves the multiple-request problem by allowing you to fetch all related data in a single query, but it introduces its own complexity. GraphQL queries against a WordPress database with 10,000+ posts and complex custom field relationships can be surprisingly slow if not carefully optimized with proper query depth limits, persisted queries, and caching at the GraphQL resolver level. We have seen WPGraphQL queries take 2-3 seconds on uncached requests against large databases, which negates the performance advantage that was the primary motivation for going headless in the first place.

The caching layer between the headless frontend and the WordPress API is critical infrastructure that is often treated as an afterthought. You need to cache API responses to avoid hitting WordPress on every frontend request, but you also need cache invalidation when content changes in WordPress. This requires either webhook-based invalidation (WordPress notifies the frontend cache when content changes) or time-based expiry (cache responses for N seconds and accept stale content within that window). Both approaches have trade-offs that must be designed for, not discovered in production.

// Common headless caching pattern with SWR (Stale-While-Revalidate)
// Frontend serves cached content immediately, fetches fresh data in background
const { data: posts, error } = useSWR(
  '/api/posts?page=1',
  fetcher,
  {
    revalidateOnFocus: false,
    revalidateOnReconnect: false,
    refreshInterval: 60000,  // Refresh every 60 seconds in background
    dedupingInterval: 30000, // Prevent duplicate requests within 30 seconds
  }
);
// Trade-off: content changes in WordPress may take up to 60 seconds
// to appear on the frontend, but the user experience is instant

The Real Cost Comparison: A Case Study

To make the cost difference concrete, here is a side-by-side comparison from a real project we quoted both ways for a client who asked us to evaluate both architectures for their 30-page corporate website with a blog, team directory, case studies section, and contact form.

Traditional WordPress estimate:

• Theme development and customization: 60 hours
• Content migration and setup: 12 hours
• Plugin configuration (SEO, forms, caching): 8 hours
• Testing and QA across devices: 16 hours
• Total: 96 hours at $100/hour = $9,600
• Ongoing hosting: $50/month
• Ongoing maintenance: $500/month retainer

Headless WordPress estimate (Next.js + WordPress API):

• Next.js frontend development: 120 hours
• WordPress API configuration and custom endpoints: 20 hours
• SEO implementation (sitemaps, meta, structured data): 16 hours
• Preview functionality setup: 12 hours
• Search implementation: 8 hours
• Content migration and CMS setup: 12 hours
• Deployment pipeline (WordPress + Vercel): 8 hours
• Testing and QA across devices: 20 hours
• Total: 216 hours at $100/hour = $21,600
• Ongoing hosting: $70/month (WordPress server + Vercel Pro)
• Ongoing maintenance: $800/month retainer (two codebases to maintain)

The headless approach cost 2.25x more upfront and carries 60% higher ongoing costs, for a site that has no multi-platform requirements, no complex interactivity beyond a contact form, and no performance requirements that optimized traditional WordPress cannot meet. The client chose traditional WordPress, launched on schedule, and their marketing team manages the site independently.

Save the headless architecture for projects that genuinely need it, and invest the saved budget in content quality, visual design, and marketing, the things that actually move business metrics for most organizations.