What does headless WordPress development actually mean?
Headless WordPress development separates the “body” of WordPress, where content is written and stored, from the “head”, the theme that turns it into web pages. WordPress keeps doing what it does well: logins, the block editor, media library, revisions and user roles. A different application, usually built with Next.js or Astro, asks WordPress for content through an API and builds the pages visitors see.
The connection runs over one of two channels. The WordPress developer handbook describes the REST API as an interface that lets applications send and receive data as JSON, and notes that it also underpins the block editor itself. WPGraphQL, a free open-source plugin listed on WordPress.org, adds a GraphQL schema so the front end can ask for exactly the fields it needs in one request.
For your team, very little changes on the writing side. Posts are drafted, reviewed and published in the same dashboard. What changes is everything after the Publish button: the page is generated by modern JavaScript tooling, cached on a content delivery network, and served without the PHP theme or front-end plugins running on every visit.
- Content layer: WordPress admin, database, media, users
- API layer: REST API at /wp-json/ or WPGraphQL at /graphql
- Presentation layer: Next.js or Astro templates, deployed separately
- Glue: preview links, publish webhooks, redirects and sitemaps
When is headless WordPress worth the extra complexity?
Headless is worth it when WordPress is doing a good job as an editor but a poor job as a website, and a theme tune-up cannot close the gap. The clearest signals are content volume, traffic spikes, interface ambitions and multiple output channels.
Large or fast-moving content libraries
News portals, publishers, education sites and knowledge bases with thousands of posts benefit from pages served ready-made from a CDN, so a traffic spike never touches the WordPress server.
Interfaces a theme struggles with
Product finders, calculators, filtered directories and app-like navigation are easier to build well in React or Astro components than inside a PHP theme with jQuery add-ons.
One content source, many outputs
When the same articles must feed a website, an Android and iOS app, a partner widget and newsletters, WordPress as a content API avoids copying text between systems.
Security separation
With the public site served from static files or an edge network, the WordPress admin can live on a separate, locked-down subdomain that visitors never reach.
If none of these apply, stop here. A normal theme built carefully will cost less and give your team fewer surprises. We will tell you that on the first call.
When headless WordPress development is overkill
Headless is overkill for most small business websites. If you have fewer than a few dozen pages, publish a handful of posts a month, and the main complaint is speed, the cheaper fix is a lean theme, fewer plugins and proper caching.
Headless also hurts when your team relies on plugins that change what visitors see. Page builders like Elementor, popup tools, sliders, form builders, membership plugins and many WooCommerce extensions render their output through the theme. In a headless build that output disappears, and each feature has to be rebuilt in the front end or replaced with an API-friendly alternative. If your site is essentially a collection of front-end plugins, going headless means rebuilding most of it.
Finally, consider who maintains the site. A traditional WordPress site can be looked after by many freelancers across India. A headless site needs someone comfortable with both WordPress and a JavaScript framework, plus two hosting environments. That is fine if you plan for it, and a problem if you do not.
- Small brochure site that already loads quickly: stay traditional
- Site built almost entirely in a page builder: rebuild or tune, not headless
- No budget for a developer after launch: stay traditional
- Main problem is slow hosting or plugin bloat: fix speed first
For the speed-first route, see our WordPress speed optimisation service; for a plain rebuild, custom WordPress theme development.
WPGraphQL vs REST API for headless WordPress: which should you use?
Use WPGraphQL when your front end is Next.js, pages combine many content types, or you rely on ACF fields; use the core REST API when the site is small, the front end is Astro with simple listings, or you want no extra plugins. Both are free and both work in production.
The REST API ships with WordPress, lives under /wp-json/, and returns fixed shapes per endpoint. It is easy to cache and easy to debug in a browser, but a single page often needs several requests: one for the post, one for the author, one for categories, one for the featured image. You can trim responses with the _fields and _embed parameters, but the shape is still set by WordPress.
WPGraphQL exposes one endpoint where the front end asks for exactly the fields it needs, nested as deeply as necessary, in one round trip. Its WordPress.org listing describes it as extendable and notes that it is becoming a canonical plugin, and a companion WPGraphQL for ACF extension exposes custom fields in the same schema. The trade-off is one more plugin to update and a query layer your developer must understand well enough to keep efficient.
Our rule of thumb: Astro with fewer than a few hundred posts and simple templates, REST. Next.js, complex templates, ACF-heavy content or multiple channels, WPGraphQL.
Next.js or Astro for the headless WordPress front end?
Pick Astro for content sites that are mostly reading, and Next.js for sites that behave more like applications. Both can pre-build pages from WordPress and both produce fast HTML; they differ in how much JavaScript they ship and how they handle dynamic parts.
Astro sends HTML with almost no JavaScript by default and adds interactive “islands” only where needed, such as a search box or a filter. That makes it a natural fit for blogs, magazines, documentation and marketing sites. Its WordPress guide fetches content from the REST API at /wp-json/wp/v2/ and pre-builds pages, with on-demand server rendering available when you need fresher content.
Next.js is a React framework with static generation, server rendering and incremental revalidation built in. It suits sites with logged-in areas, personalised content, complex filtering or a shared codebase with a React Native app. Its Draft Mode feature, documented on nextjs.org, is designed for exactly the headless preview problem covered below.
Either way, the choice is about your next three years, not about hype. If your team or next developer knows React, Next.js lowers hiring risk. If the site is 90% articles and you want the lightest possible pages, Astro is simpler to own.
How does preview work in headless WordPress?
Preview works when the WordPress Preview button is pointed at a secure route on the front end that switches on draft mode and fetches the unpublished revision. Without this, editors click Preview and see the old theme or a blank page, which is the most common complaint about badly built headless sites.
On Next.js, the documented pattern is a route handler that checks a shared secret, confirms the slug exists, enables Draft Mode by setting a cookie and redirects to the page. Next.js documentation explains that while Draft Mode is on, cached and pre-rendered content is bypassed for that editor only, while other visitors keep seeing the cached version. The front end then requests the draft from WordPress using an authenticated call, so drafts never leak publicly.
On Astro, preview is usually handled by a small server-rendered route or a separate preview deployment that reads drafts with an application password.
We also fix the smaller editor annoyances: the “View post” link in the admin points to the new domain, featured images show correct crops, and a banner makes clear when someone is looking at a draft rather than the live page.
Keeping Yoast or Rank Math SEO data in headless WordPress
Your SEO plugin keeps working in the admin, but its output no longer reaches visitors automatically, because the theme that printed those tags is gone. The front end must fetch the SEO data and render it in each page's head.
Yoast's developer documentation describes two REST fields for this: yoast_head, a ready-made block of meta tags and schema, and yoast_head_json, the same information as structured key-value data. It also documents a get_head endpoint that returns the head for any URL. Rank Math's knowledge base describes a Headless CMS Support toggle in its general settings that exposes a getHead REST endpoint returning the plugin's head tags for a given URL. For WPGraphQL, community extensions expose the same SEO fields in the schema.
Getting tags onto the page is only half the job. We also make sure canonical URLs point to the public front-end domain, not the WordPress subdomain; the XML sitemap lists front-end URLs; redirects created in the plugin are honoured by the front end; noindex settings carry across; and the WordPress admin domain itself is blocked from indexing so Google never sees two copies of your site.
- Titles and meta descriptions rendered server-side, not injected by JavaScript
- Canonical tags rewritten to the public domain
- Schema output from the SEO plugin validated in the Rich Results Test
- Sitemap regenerated with front-end URLs and submitted in Search Console
- Old theme URLs and plugin redirects mapped one to one
Hosting both layers of a headless WordPress site
You pay for two kinds of hosting: a server for WordPress and PHP, and a platform for the front end. The good news is that the WordPress server can be smaller than before, because visitors no longer hit it directly.
The WordPress side needs PHP, MySQL or MariaDB, backups and updates, just like any WordPress site. It can sit on a managed WordPress host or a small cloud server, ideally on a subdomain such as cms.yourdomain.com with the admin protected. The front end can be deployed as static files on a CDN, or on a platform that supports server rendering for Next.js or Astro. Pure static output is the cheapest to run; server rendering costs more but lets pages update without a full rebuild.
Another of us on our team handles the cloud setup, including AWS where it suits, DNS, SSL, caching rules and the webhook that tells the front end to rebuild or revalidate when someone clicks Publish. Every account is opened in your name, and we document which service does what so a future developer is not guessing.
How much does headless WordPress development cost in India?
With BtechWaleTech, smaller headless WordPress builds start at ₹10,000 (US$150), and content sites with 299 or more pages start at ₹20,000 (US$300). Headless stores and member portals are priced nearer our ecommerce and custom web app plans.
Across the market, headless quotes vary widely, and the spread comes from a few concrete things: how many unique page templates must be built as components; whether existing page-builder layouts must be recreated; whether preview must work for every post type; how many ACF field groups and custom post types exist; and whether the project includes content migration or redirects from an old site.
There are running costs too. You will pay for WordPress hosting, a front-end host, and possibly a search or form service that replaces a plugin. None of these are large for a typical Indian business site, but they belong in the budget from day one, and our quote lists them as separate lines so there are no surprises.
Headless WordPress project timeline, phase by phase
A smaller headless site usually takes three to five weeks; a large publisher or migration project takes longer, depending on templates and content volume. The phases below overlap slightly.
Week 1: content audit and model
We list every content type, field and template, decide what stays in WordPress and what becomes front-end code, and agree the API choice.
Weeks 1–2: WordPress preparation
Custom post types, ACF groups, roles, the API plugin, application passwords, and locking the admin onto its own subdomain.
Weeks 2–4: front-end build
Templates for home, posts, archives and special pages, SEO head rendering, image handling and the preview route, all on a staging URL.
Final week: launch
Redirect testing, sitemap submission, rebuild webhooks, speed checks on real phones, DNS switch and handover notes.
Gutenberg blocks and ACF in a headless build
Blocks are where headless projects succeed or struggle. If editors build pages from blocks, the front end must know how to render each block type, or it falls back to raw HTML that ignores your design system.
We handle this in one of two ways. For simple posts, the front end renders the post content HTML and styles common blocks such as headings, lists, images, quotes and embeds. For designed landing pages, we define a small set of custom blocks or ACF flexible-content layouts, each mapped to a matching Astro or React component. Editors still arrange sections visually; the front end draws them with clean, fast code.
The lesson from inherited projects is to keep the block list short. Twelve well-built section types cover most business sites, and each one added later costs development time on both sides of the API.
Moving an existing WordPress site to headless without losing traffic
Keep every URL identical where possible, and redirect the rest one to one. The content itself does not move, because it stays in WordPress, so the main risk is on the URL, template and metadata side.
Before the switch we crawl the current site, export every live URL from the sitemap and Search Console, and compare it with the URLs the new front end produces. Pagination, category archives, author pages, attachment pages and old campaign URLs are the usual gaps. We also compare titles, canonicals and structured data page by page on staging.
After launch we watch Google Search Console coverage and performance reports closely for the first weeks. If you would rather leave WordPress completely, our WordPress to Next.js migration guide covers that route, and recovering from a traffic drop after migration covers what to do if a move has already gone wrong.
Risks and red flags when hiring for headless WordPress development
The biggest risk is a developer who builds a beautiful front end and leaves the editors behind. Ask to see the editor experience of a previous headless build, not just the public pages.
- No working Preview button, or preview only for posts and not pages
- SEO tags added in the browser by JavaScript rather than in the HTML
- WordPress admin left on the main domain and indexable
- Every edit requires a developer because blocks were not mapped
- A full site rebuild on every publish with no plan for large sites
- Front-end and hosting accounts held in the developer's name
- No written note on what replaces each front-end plugin you used before
A good headless WordPress developer will raise most of these points before you do. If the proposal only talks about speed scores, ask about editing, preview and redirects.
Headless WordPress, AI search and structured content
A headless site can be easier for search engines and AI assistants to read, as long as pages are rendered as complete HTML on the server or at build time. Crawlers that do not run JavaScript still see the full article, headings and schema.
Because content arrives from WordPress as structured data rather than as a theme template, it is simple to add consistent FAQ, article, breadcrumb and organisation schema across thousands of pages, and to keep headings clean. That clarity helps Google's AI Overviews and other answer engines identify what each page is about. Nobody can guarantee rankings or AI citations, but clean, well-structured HTML removes technical barriers.
For ongoing search work after launch, our monthly SEO starts at ₹10,000/mo, with Google Search Console reports you can check yourself.
Worked example: a hypothetical regional news site going headless
This is an illustration, not a real client. Imagine a Hindi and English regional news portal in Lucknow with years of archives on WordPress. Traffic spikes during elections and exam results, and the server slows down exactly when readers arrive.
The editors are happy with WordPress and do not want a new tool. The site is mostly articles, category pages and author pages, with a live-updates widget for big events. That points to headless WordPress with an Astro front end: articles pre-built and served from a CDN, category pages refreshed on publish, and the live widget as a small interactive island reading from the REST API.
We would propose starting at the ₹20,000 plan for a site of this size, with separate lines for the bilingual templates, the live widget and redirect mapping of the archive. The WordPress admin moves to a protected subdomain. Yoast data is rendered through yoast_head_json, the sitemap is regenerated with public URLs, and the Preview button opens drafts through a server route. During an election spike, readers are served cached pages while the WordPress server only handles editors.
Headless WordPress development for businesses across India
We work remotely with publishers, schools, tourism businesses and brands across the country, using video calls and WhatsApp, with payment by UPI or bank transfer. Bilingual Hindi and English builds, and pages in other Indian languages with copy you supply, are handled with correct language tags.
City pages describe the local businesses we work with, for example in Mumbai, New Delhi, Lucknow, Jaipur, Kochi, Guwahati, Dehradun, Udaipur and Surat. Clients abroad are billed in USD through Wise, bank wire or PayPal; see countries we work with.