Going headless means keeping WordPress as your content editor while a separate framework like Next.js renders the front end. This guide walks through the full setup in order: prepare WordPress, choose your API, build the Next.js front end, preserve SEO, lock down security, and deploy. Most tutorials stop at “fetch a post” — here we also cover the parts that break in production: meta migration, draft previews, CORS, and redirects.
What is headless WordPress, and when should you use it?
Headless WordPress decouples the content management back end from the presentation layer: WordPress serves data over an API, and a JavaScript framework renders the pages. You keep the familiar WordPress editor and plugins while gaining the speed, component model, and developer experience of a modern front end.
It is the right call when you need fast Core Web Vitals, an app-like UI, a shared content source for web plus mobile, or a custom design that fights traditional themes. It is overkill for a simple brochure site — in that case a well-built classic theme is cheaper to run. For a deeper architectural comparison, see our guide on headless WordPress with React and Next.js and the broader question of React vs WordPress.
Step 1: Prepare your WordPress back end
Configure WordPress as a content API by setting pretty permalinks, enabling the REST API, and installing the plugins your front end will read from. This is the foundation every later step depends on.
- Set permalinks: Go to Settings → Permalinks and choose “Post name.” The WordPress REST API is enabled by default at
/wp-json/wp/v2once permalinks are not set to “Plain.” - Keep SEO meta in WordPress: Leave Yoast or Rank Math installed so editors still control titles, descriptions, and Open Graph data — you will read those fields into the front end later.
- Decide on a CMS-only setup: Treat WordPress as a back office. You will point your domain at the front end, not at
wp-admin. Understanding what a headless CMS is helps frame these choices.
Step 2: Choose your API — REST or WPGraphQL
Use the built-in REST API for simple sites and fast onboarding; install WPGraphQL when you need to fetch nested data in a single request and avoid over-fetching. Both are production-ready — the choice is about data shape and developer ergonomics.
| Factor | REST API (built-in) | WPGraphQL (plugin) |
|---|---|---|
| Setup | None — works out of the box | Install & activate WPGraphQL |
| Data fetching | Multiple endpoints, can over-fetch | One query, exactly the fields you ask for |
| Nested data (post + author + media) | Several requests or _embed | Single request |
| Learning curve | Familiar HTTP/JSON | Requires GraphQL knowledge |
| Best for | Blogs, small to mid sites | Complex apps, many content types |
If you install WPGraphQL, a new “GraphQL” menu appears in wp-admin with an IDE to test queries. For most marketing sites the REST API is enough; reach for GraphQL when component trees demand deeply related data.
Step 3: Build the Next.js front end
Scaffold a Next.js app, store your WordPress API URL in an environment variable, then fetch content in server components or data-fetching functions. The front end becomes the public site; WordPress stays private.
- Create the app with
npx create-next-app@latest. - Add
NEXT_PUBLIC_WORDPRESS_API_URL=https://cms.yoursite.com/wp-json/wp/v2to.env.local. - Write a
getPosts()helper that fetches/posts?_embedso featured images and author data come back in one call. - Build a dynamic route — for example
app/blog/[slug]/page.js— that fetches a single post by slug and renders its HTML. - Use Incremental Static Regeneration so pages rebuild on a schedule instead of on every request, balancing speed and freshness.
Run npm run dev and your headless site is live at localhost:3000, pulling real content from WordPress. Curious about budget before you commit? Our breakdown of Next.js development cost sets expectations.
Step 4: Preserve SEO — the step most guides skip
Headless does not inherit your theme’s SEO automatically; you must read Yoast/Rank Math meta from the API and render it as real HTML tags in Next.js. Skip this and you lose titles, canonicals, and structured data overnight.
- Pull meta fields: Yoast exposes a
yoast_head_jsonobject via REST; map its title, description, canonical, and Open Graph values into the Next.jsgenerateMetadata()function. - Generate a sitemap and robots: Produce
sitemap.xmlandrobots.txtfrom the framework, not WordPress, so they reflect the live front-end URLs. - Re-emit structured data: Output Article, FAQ, and Breadcrumb JSON-LD in the page head. Google’s structured data documentation confirms it must be present in the rendered HTML to count.
- Match URL structure: Keep the same
/blog/<slug>/paths so existing rankings survive the migration.
For a fuller checklist, see our guide to technical SEO for WordPress and the best SEO plugins for WordPress that expose clean API meta.
Step 5: Handle previews, CORS, and security
Production headless sites need draft previews, correct CORS headers, and a locked-down back end — the trio that breaks first when teams ship. Address them before launch, not after.
- Draft previews: Use Next.js Draft Mode with an authenticated WordPress request so editors can preview unpublished posts pulled by ID rather than slug.
- CORS: The browser blocks requests from your front-end origin to the WordPress domain by default. Allow your dev and production origins via a small
functions.phpfilter or a CORS plugin. - Authentication: Use Application Passwords or JWT for private endpoints and preview calls — never expose admin credentials in client code.
- Lock the back end: Restrict
wp-admin, disable the front-end theme rendering, and put WordPress on a subdomain such ascms.yoursite.com.
Step 6: Deploy and connect revalidation
Deploy the Next.js front end to a platform like Vercel and wire WordPress publish events to trigger on-demand revalidation so edits appear within seconds. The back end can stay on traditional WordPress hosting.
- Push your repository and set the same environment variables in your host’s dashboard.
- Choose ISR with a sensible
revalidateinterval, plus an on-demand revalidation webhook fired by a WordPress “save_post” hook for instant updates. - Set up redirects for any legacy URLs that changed, so no link equity is lost.
- Verify rendered meta, sitemap, and JSON-LD with a crawler before pointing your domain over.
The same pattern powers headless commerce — if you sell products, our guide to headless WooCommerce extends these steps to the store. Still weighing platforms entirely? Review why WordPress remains a strong content back end even when the front end is decoupled.
Common mistakes to avoid
Most failed headless launches trace back to a handful of avoidable errors around SEO, caching, and content parity.
- Forgetting to render meta tags and structured data, tanking rankings post-launch.
- Hard-coding the WordPress URL instead of using environment variables.
- Ignoring image optimization — proxy WordPress media through the framework’s image component.
- No revalidation strategy, so editors see stale content and lose trust in the system.
- Leaving the old theme front end crawlable, creating duplicate content.
Ready to go headless without the SEO and deployment pitfalls? Our team handles WordPress preparation, API setup, Next.js builds, and migration end to end. Explore our custom WordPress development services to scope your headless project.
Frequently asked questions
Not strictly. The REST API ships with WordPress and works once permalinks are set to Post name, so you can build a headless front end with zero plugins. You only need WPGraphQL if you prefer GraphQL queries, and you should keep an SEO plugin like Yoast so editors still control meta fields.
Use the built-in REST API for blogs and small to mid-size sites because it requires no setup. Choose WPGraphQL when you need to fetch deeply nested data, such as a post with its author and media, in a single request without over-fetching. Both are production-ready; the decision comes down to data shape and team familiarity.
It can if you skip the SEO step. Headless front ends do not inherit your theme’s meta automatically. Read Yoast or Rank Math fields from the API, render them as real HTML tags, output JSON-LD structured data, generate a sitemap from the framework, and keep the same URL structure to preserve rankings during migration.
Use Next.js Draft Mode combined with an authenticated WordPress request. Instead of fetching published posts by slug, the preview route fetches the draft by ID using Application Passwords or JWT authentication. This lets editors see unpublished changes on the live front end before the post goes public, matching the classic WordPress preview experience.
With Incremental Static Regeneration plus an on-demand revalidation webhook fired by WordPress on save, edits typically appear within seconds. Without on-demand revalidation, pages refresh only on the interval you set, so editors may wait minutes. Wiring the WordPress save_post hook to a revalidation endpoint gives near-instant updates while keeping static performance.
