Headless WordPress decouples content management from presentation layers. WordPress serves as content API whilst separate frontend applications handle display using modern JavaScript frameworks. Professional headless implementations deliver superior performance, omnichannel content delivery, and modern development workflows whilst maintaining WordPress's content management strengths.
Headless WordPress separates backend content management from frontend presentation. WordPress REST API exposes content; independent frontends consume API building custom interfaces.
Traditional WordPress combines content management and display within single monolithic system. Headless architecture splits these concerns enabling specialised optimisation for each layer.
Frontend applications built with React, Vue, Next.js, or similar frameworks fetch WordPress content via WordPress REST API. No WordPress themes involved; custom frontends handle all presentation.
"Headless" refers to removing traditional "head" (presentation layer) whilst retaining "body" (content management). WordPress becomes pure content repository.
Headless enables omnichannel content delivery. Single WordPress installation serves websites, mobile apps, digital signage, and IoT devices simultaneously.
Modern WordPress development increasingly embraces headless approaches for performance-critical applications.
Headless WordPress provides compelling advantages justifying architectural complexity for appropriate use cases.
Superior Performance:
Static site generation or server-side rendering dramatically improves load times. Pre-rendered HTML serves instantly without PHP execution or database queries.
CDN distribution accelerates global delivery. Static files cache perfectly maximisng CDN effectiveness.
Modern frontend frameworks optimise rendering. Code splitting, lazy loading, and efficient JavaScript execution enhance user experience.
Enhanced Security:
WordPress admin hidden from public internet. Attackers cannot target login pages or find WordPress fingerprints.
Reduced attack surface. Fewer WordPress plugins required when frontend handles functionality independently.
Static frontends contain no server-side execution vulnerabilities. HTML/CSS/JavaScript files pose minimal security risks.
Developer Experience:
Modern development workflows with hot reloading, component libraries, and advanced tooling.
Separation of concerns enables specialised teams. Content team uses familiar WordPress; developers build frontends using preferred technologies.
Version control and CI/CD integration simplifies deployments. Frontend and backend deploy independently.
Scalability:
Static frontends handle traffic spikes effortlessly. CDN distribution eliminates server load concerns.
Backend and frontend scale independently. Content API and presentation optimise separately.
Flexibility:
Any frontend technology works. Choose React, Vue, Angular, Svelte, or emerging frameworks freely.
Omnichannel delivery. Serve multiple frontends from single content source.
Easy redesigns. Replace frontends without touching WordPress installation.
Headless WordPress combines content management backend with modern frontend technologies. Understanding stack components enables informed architectural decisions.
Backend: WordPress
WordPress manages content, users, and media. REST API exposes data to frontends.
Plugins extend API functionality. ACF, Yoast SEO, and custom endpoints provide additional data.
Admin interface remains unchanged. Content teams use familiar WordPress editing experience.
Frontend Frameworks:
Next.js (React): Most popular for headless WordPress. Server-side rendering, static generation, image optimisation built-in.
// pages/index.js
export async function getStaticProps() {
const res = await fetch('https://example.com/wp-json/wp/v2/posts');
const posts = await res.json();
return { props: { posts }, revalidate: 60 };
}
export default function Home({ posts }) {
return (
<div>
{posts.map(post => (
<article key={post.id}>
<h2>{post.title.rendered}</h2>
<div dangerouslySetInnerHTML={{__html: post.content.rendered}} />
</article>
))}
</div>
);
}
Gatsby: Static site generator with GraphQL. Excellent build-time optimisations. Plugin ecosystem integrates WordPress seamlessly.
Nuxt.js (Vue): Vue equivalent to Next.js. Server-side rendering and static generation for Vue developers.
Svelte/SvelteKit: Emerging framework compiling to vanilla JavaScript. Minimal runtime overhead.
Hosting:
Vercel/Netlify: Optimised for static/SSR applications. Automatic deployments, CDN distribution, serverless functions.
Traditional Hosts: Node.js hosting for custom SSR applications. Digital Ocean, AWS, or Google Cloud.
Stack selection depends on team expertise, performance requirements, and project scope.
Headless WordPress setup requires configuring WordPress for API usage and building frontend applications consuming WordPress content.
WordPress Configuration:
Enable REST API: REST API enabled by default. Verify accessibility at /wp-json/ endpoint.
Install Essential Plugins:
- WPGraphQL (if using GraphQL)
- ACF to REST API
- Yoast SEO REST API
- JWT Authentication (for authenticated requests)
Configure Permalinks: Set pretty permalinks (/post-name/) ensuring clean URLs.
Create Application User: Generate application passwords for API authentication.
Add CORS Headers (if needed):
add_action('rest_api_init', function() {
remove_filter('rest_pre_serve_request', 'rest_send_cors_headers');
add_filter('rest_pre_serve_request', function($value) {
header('Access-Control-Allow-Origin: *');
header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE');
header('Access-Control-Allow-Credentials: true');
return $value;
});
});
Frontend Setup (Next.js Example):
npx create-next-app my-headless-site
cd my-headless-site
npm install
Fetch WordPress Content:
// lib/api.js
const API_URL = process.env.WORDPRESS_API_URL;
export async function getPosts() {
const res = await fetch(`${API_URL}/wp-json/wp/v2/posts`);
const posts = await res.json();
return posts;
}
export async function getPost(slug) {
const res = await fetch(`${API_URL}/wp-json/wp/v2/posts?slug=${slug}`);
const posts = await res.json();
return posts[0];
}
Environment Variables:
// .env.local
WORDPRESS_API_URL=https://your-wordpress-site.com
Setup complexity requires frontend development expertise. Evaluate team capabilities before committing to headless architecture.
Next.js provides optimal headless WordPress foundation through static generation, server-side rendering, and image optimisation.
Static Generation with Incremental Regeneration:
// pages/posts/[slug].js
export async function getStaticPaths() {
const res = await fetch('https://example.com/wp-json/wp/v2/posts');
const posts = await res.json();
const paths = posts.map(post => ({
params: { slug: post.slug }
}));
return { paths, fallback: 'blocking' };
}
export async function getStaticProps({ params }) {
const res = await fetch(
`https://example.com/wp-json/wp/v2/posts?slug=${params.slug}`
);
const posts = await res.json();
const post = posts[0];
return {
props: { post },
revalidate: 60 // Regenerate every 60 seconds
};
}
export default function Post({ post }) {
return (
<article>
<h1>{post.title.rendered}</h1>
<div dangerouslySetInnerHTML={{__html: post.content.rendered}} />
</article>
);
}
Image Optimisation:
import Image from 'next/image';
export default function Post({ post }) {
const featuredImage = post._embedded['wp:featuredmedia'][0];
return (
<article>
{featuredImage && (
<Image
src={featuredImage.source_url}
alt={post.title.rendered}
width={featuredImage.media_details.width}
height={featuredImage.media_details.height}
/>
)}
<h1>{post.title.rendered}</h1>
<div dangerouslySetInnerHTML={{__html: post.content.rendered}} />
</article>
);
}
SEO with next-seo:
import { NextSeo } from 'next-seo';
export default function Post({ post }) {
return (
<>
<NextSeo
title={post.title.rendered}
description={post.excerpt.rendered.replace(/<[^>]*>/g, '')}
openGraph={{
title: post.title.rendered,
description: post.excerpt.rendered,
images: [
{
url: post._embedded['wp:featuredmedia'][0].source_url,
alt: post.title.rendered,
},
],
}}
/>
<article>
<h1>{post.title.rendered}</h1>
<div dangerouslySetInnerHTML={{__html: post.content.rendered}} />
</article>
</>
);
}
Next.js combines performance, developer experience, and SEO capabilities making it ideal for headless WordPress projects.
Headless WordPress maintains familiar content management whilst serving multiple frontends. Content workflows require minimal adaptation.
Content Creation:
Content teams use standard WordPress editor. Gutenberg blocks, custom fields, and media library function identically.
Preview functionality requires custom implementation. Build preview endpoints fetching unpublished content via authenticated API requests.
Custom Fields:
ACF Pro integrates with REST API exposing custom fields automatically:
// Fetch posts with ACF fields
const res = await fetch('https://example.com/wp-json/wp/v2/posts?_embed&acf_format=standard');
const posts = await res.json();
posts.forEach(post => {
console.log(post.acf.custom_field);
});
Media Management:
WordPress media library uploads and manages images normally. REST API exposes media:
const media = post._embedded['wp:featuredmedia'][0];
Content Relationships:
Custom endpoints or plugins expose relationships:
register_rest_field('post', 'related_posts', array(
'get_callback' => function($post) {
$related = get_post_meta($post['id'], 'related_posts', true);
return $related ? array_map('intval', $related) : array();
}
));
Taxonomies:
Categories and tags work via REST API:
// Fetch posts with categories
const res = await fetch('https://example.com/wp-json/wp/v2/posts?_embed');
const posts = await res.json();
posts.forEach(post => {
const categories = post._embedded['wp:term'][0];
console.log(categories);
});
Content management workflows remain largely unchanged. Technical implementation differs; editorial experience feels familiar.
Headless architecture requires careful SEO implementation. Client-side rendering harms SEO; server-side rendering or static generation proves essential.
Server-Side Rendering (SSR):
Generate HTML server-side ensuring search engines crawl content properly:
// Next.js SSR
export async function getServerSideProps({ params }) {
const post = await getPost(params.slug);
return { props: { post } };
}
Static Site Generation (SSG):
Pre-render pages at build time:
export async function getStaticProps() {
const posts = await getPosts();
return { props: { posts }, revalidate: 60 };
}
Meta Tags:
Implement comprehensive meta tags:
import Head from 'next/head';
export default function Post({ post }) {
return (
<>
<Head>
<title>{post.title.rendered}</title>
<meta name="description" content={post.excerpt.rendered} />
<meta property="og:title" content={post.title.rendered} />
<meta property="og:description" content={post.excerpt.rendered} />
<meta property="og:image" content={featuredImageUrl} />
<meta name="twitter:card" content="summary_large_image" />
</Head>
<article>
{/* Content */}
</article>
</>
);
}
Structured Data:
Implement JSON-LD schema:
const schema = {
"@context": "https://schema.org",
"@type": "Article",
"headline": post.title.rendered,
"datePublished": post.date,
"dateModified": post.modified,
"author": {
"@type": "Person",
"name": post._embedded.author[0].name
}
};
Sitemaps:
Generate XML sitemaps:
// pages/sitemap.xml.js
export async function getServerSideProps({ res }) {
const posts = await getPosts();
const sitemap = `<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
${posts.map(post => `
<url>
<loc>https://example.com/posts/${post.slug}</loc>
<lastmod>${post.modified}</lastmod>
</url>
`).join('')}
</urlset>
`;
res.setHeader('Content-Type', 'text/xml');
res.write(sitemap);
res.end();
return { props: {} };
}
Proper SEO implementation ensures headless WordPress ranks well. Combine technical implementation with strategic WordPress SEO practices.
Headless architecture enables superior performance through static generation, CDN distribution, and optimised frontends.
Static Site Generation:
Pre-render pages at build time. Serve static HTML instantly without server processing:
export async function getStaticProps() {
const posts = await fetch('https://example.com/wp-json/wp/v2/posts').then(r => r.json());
return { props: { posts }, revalidate: 3600 }; // Revalidate hourly
}
Incremental Static Regeneration:
Update static pages periodically without full rebuilds:
return {
props: { post },
revalidate: 60 // Regenerate every 60 seconds
};
CDN Distribution:
Deploy static files to CDNs. Vercel, Netlify automatically distribute globally.
Image Optimisation:
Next.js Image component automatically optimises:
<Image
src={imageUrl}
width={800}
height={600}
loading="lazy"
alt="Description"
/>
Code Splitting:
Modern frameworks automatically split code. Load only necessary JavaScript per page.
Caching Strategies:
Implement aggressive caching. Static files cache indefinitely; API responses cache briefly.
Performance Monitoring:
Monitor Core Web Vitals ensuring optimal metrics. Headless enables achieving perfect scores.
Headless WordPress combined with modern frontends delivers exceptional performance. Integrate with comprehensive WordPress speed optimisation for backend optimisation.
Headless WordPress introduces complexity warranting careful evaluation before implementation.
Increased Complexity:
Separate frontend and backend require managing two systems. Deployments, hosting, and maintenance double.
Frontend development expertise mandatory. Team needs JavaScript framework proficiency.
Preview Functionality:
WordPress preview requires custom implementation. Build authenticated preview endpoints.
Plugin Limitations:
WordPress plugins affecting frontend don't work. Form plugins, page builders, and display-affecting plugins require alternatives.
Content Editing Experience:
WYSIWYG editing differs from frontend display. Content teams cannot see exact frontend rendering during editing.
Development Time:
Initial setup takes longer than traditional WordPress. Build frontend from scratch rather than customising themes.
Cost Considerations:
Additional hosting required for frontend. Separate deployments increase infrastructure costs.
SEO Complexity:
Requires understanding SSR/SSG. Client-side rendering harms SEO demanding technical implementation.
Learning Curve:
Steeper learning curve. Traditional WordPress developers must learn modern frontend frameworks.
Evaluate challenges against benefits. Headless suits specific use cases; traditional WordPress remains appropriate for many projects.
Headless WordPress benefits justify complexity for specific scenarios. Evaluate requirements determining architectural appropriateness.
Choose Headless When:
Choose Traditional WordPress When:
Most businesses benefit from traditional WordPress. Headless proves worthwhile for performance-critical applications or sophisticated frontend requirements.
Is headless WordPress more expensive?
Yes, headless WordPress typically costs more through additional frontend development, separate hosting, and maintenance complexity. Traditional themes cost £2,000-£8,000; headless builds cost £10,000-£30,000+ due to custom frontend development. Ongoing costs double through separate hosting and maintenance for frontend and backend. Benefits justify costs for performance-critical applications; traditional WordPress proves more cost-effective for standard business websites.
Can I use WordPress plugins with headless?
Backend plugins work normally (SEO, security, custom post types). Frontend-affecting plugins (page builders, form plugins, display modifications) don't work since WordPress doesn't render frontend. Alternative solutions required: build forms in frontend, use headless CMS features, or integrate third-party services. Evaluate plugin dependencies before choosing headless architecture. Heavy plugin reliance suggests traditional WordPress better fit.
How do I preview content in headless WordPress?
Implement custom preview functionality through authenticated API requests fetching draft/unpublished content. Build preview URLs in frontend consuming authenticated endpoints. Next.js Preview Mode enables seamless previews. Alternatively, use staging WordPress installation with traditional theme for content preview, then publish to production headless site. Preview implementation adds development complexity but proves solvable.
Does headless WordPress improve security?
Headless WordPress improves security by hiding admin from public internet. Attackers cannot find login pages or identify WordPress installation. Static frontends lack server-side execution vulnerabilities. Reduced plugin count decreases attack surface. However, WordPress backend still requires security measures. Implement WordPress security best practices, authentication, and regular updates. Headless improves but doesn't eliminate security requirements.
Can I migrate from traditional WordPress to headless?
Yes, migrate from traditional to headless WordPress. Content remains in WordPress; build new frontend consuming REST API. Migration requires frontend development creating new application. Content structure typically requires minimal changes. Evaluate migration costs against benefits. Gradual migration possible: start with static pages whilst maintaining WordPress theme for complex sections. Migration proves technically feasible but resource-intensive.
What's difference between headless WordPress and JAMstack?
Headless WordPress represents specific implementation using WordPress as CMS. JAMstack (JavaScript, APIs, Markup) represents architectural pattern emphasising static generation, API consumption, and JavaScript functionality. Headless WordPress implements JAMstack principles using WordPress as content API. However, JAMstack encompasses broader ecosystem including Contentful, Strapi, or custom APIs. Headless WordPress represents JAMstack implementation; JAMstack represents architectural philosophy.
Do I need WordPress at all for headless?
WordPress provides excellent headless CMS offering mature content management, user roles, media handling, and familiar interface. Alternative headless CMSs include Contentful, Strapi, or Sanity. Choose WordPress when: content team prefers WordPress, existing WordPress installation migrating headless, or WordPress ecosystem benefits needed. Choose alternatives when: starting fresh without WordPress experience, requiring pure headless CMS, or specific alternative features essential. WordPress remains popular headless choice due to maturity and ecosystem.
Related WordPress Development Topics:
Written by the WordPress Development Team at London Web Design, building headless WordPress applications for London businesses since 2018.
