28 October 202612 min read

WordPress to Headless: A Migration Guide for Next.js

A steel counter in a print shop holding a tray of lead type on the left and a stack of printed sheets on the right, with a wall-mounted pneumatic tube terminal and its brass carrier between them, one small amber indicator lamp lit.

Moving WordPress to headless means keeping WordPress as the place where editors write and manage content, and replacing the theme with a separate frontend, most often built in Next.js, that pulls the content through an API. Your editors keep a familiar admin. Your developers get a modern stack. In return, you take on two systems instead of one, and a few things WordPress did for free now have to be built.

This guide explains what changes, when the move is worth it, how a careful migration runs, and what to budget for afterwards. It is written for founders and site owners who run WordPress today and are weighing the switch, not for developers who only want a code snippet.

TL;DR

Headless WordPress keeps the editor and database, but a separate Next.js app renders the public pages. WordPress no longer produces your site’s HTML.
It pays off for highly custom frontends, content reused across web and apps, or teams that need to release design changes independently. For a standard brochure site or blog, it usually costs more than it returns.
Connect the two through the REST API or WPGraphQL, then rebuild routing, previews, forms, SEO metadata and redirects yourself.
Migrate in parallel: build the new frontend while the old site runs, validate it, then switch over. Never cut over blind.
Plan for two hosting environments, two codebases and ongoing maintenance on both.

What “headless” actually changes

In a conventional WordPress site, one system does everything. A request arrives, WordPress loads its settings, plugins and the active theme, queries the database, runs the PHP template hierarchy and returns finished HTML to the browser. WordPress.com’s explainer describes exactly this flow for the coupled setup.

In a headless setup, WordPress stops generating public pages. As WP Engine’s support documentation puts it, it remains primarily the content backend and exposes data through an API to a separately built frontend. The “head” (what visitors see) is now its own application, with its own code, hosting and release process.

Three practical consequences follow:

Your theme is gone. Templates, page builders and theme-based widgets do not carry over. The design is rebuilt in the new frontend.
Plugins split into two groups. Plugins that manage content (custom fields, SEO data, translations) keep working in the admin. Plugins that output something on the public page (forms, sliders, comment sections, many SEO features) need a replacement in the frontend. WordPress.com notes that many familiar themes, patterns, comments, forms and plugins do not work automatically without extra implementation.
Your editors mostly notice nothing, except that previews and some visual editing behave differently until you rebuild them.

Should you go headless at all?

This is the question to settle before any code. Headless is a trade, and the honest answer is often “not yet”.

When it makes sense

Pantheon’s overview lists the cases where headless earns its keep: highly customized frontends, content distributed to several channels, and frontend release cycles that need to be independent of the CMS. In practice, that looks like:

A product-like website with interactive features, dashboards or complex search, where PHP templates have become a constraint.
One content source, several outputs. Automattic notes that a single WordPress instance can feed websites and mobile apps alike.
Performance-critical pages. Frameworks such as Next.js support static generation and server-side rendering, which Pantheon cites as routes to better performance. A slow WordPress site is not automatically fixed by headless, though. Often a cleaned-up theme, better hosting and caching get you most of the way.
Security exposure you want to narrow. Removing the theme rendering layer can reduce the attack surface of the WordPress instance, according to WP Engine. The admin still needs hardening, and you can keep it off the public internet or behind access controls.
Frontend developers who want modern tooling. React and Next.js are far easier to staff and test than a heavily customized PHP theme.

The approach is used in serious institutional settings too. A WordCamp Europe 2025 session describes a Swiss public-sector career-choice portal built on headless WordPress and REST APIs.

When to wait

Headless costs more at the start and during operation. Automattic states plainly that development costs can be higher because the setup needs more initial and ongoing work, often from specialists for both backend and frontend. A WordPress speaker quoted by HubSpot cautioned that it can be a big investment and may not suit a new website without a big campaign behind it.

Stay with conventional WordPress if:

Your site is mostly pages and a blog, and a good theme already does the job.
Marketing edits layouts directly with a page builder and depends on that freedom.
You have no developer budget beyond the initial build.
Your main pain is a slow, bloated site, not an architectural limit.

A simple test: write down the three things you cannot do today on WordPress that you need to do in the next twelve months. If a plugin or a theme change solves them, you do not need headless. If the answer is “a different frontend architecture”, you probably do.

Choosing the API: REST or WPGraphQL

Your Next.js app needs a way to read content. WordPress offers two main routes, and Vercel’s guide confirms both work with Next.js: the REST API or WPGraphQL.

	REST API	WPGraphQL
Availability	Built into WordPress	Free plugin you install
Data shape	Fixed endpoints per content type	You request exactly the fields you need
Fetching related data	Often several requests	Often one request
Learning curve	Low, familiar to most developers	Higher, needs GraphQL knowledge
Good fit	Simple sites, few content types	Complex content models, many relations

The REST API exposes posts, pages and custom post types without installing anything. WPGraphQL is a free, open-source plugin that adds an extendable GraphQL schema and API to a WordPress site. For a site with a handful of content types, REST is enough and has one less moving part. For a site with custom fields, taxonomies and nested relations, GraphQL saves many round trips and keeps the frontend code tidy.

Whichever you choose, decide early and stick to it. Mixing both in one frontend doubles the surface you have to maintain.

How a WordPress to Next.js migration runs

The sequence below is how we would structure it for a business site. Names of tools vary, but the order rarely does.

Step 1: Audit what the current site really does

List every URL pattern, content type, form, plugin, redirect, integration and tracking script. Many sites quietly depend on a plugin for something nobody remembers: a newsletter signup, a redirect map, a language switcher, a schema markup block. Anything not on this list will break on launch day.

Also measure your baseline: organic traffic by landing page, Core Web Vitals, conversion rates. You will want a before and after.

Step 2: Clean and model the content

Headless exposes messy content. Shortcodes inside post bodies, page-builder markup and hard-coded styles do not render in a new frontend. Decide how each content type will be stored: structured custom fields for repeating blocks, clean block-editor content for articles. This is the step teams underestimate, and it often takes longer than the frontend.

Step 3: Prepare WordPress as a backend

A typical build starts by preparing WordPress API access: enabling the API you chose, setting up authentication where needed, and exposing custom fields. Put the admin on a separate subdomain, restrict who can reach it, and keep the public site’s domain pointed at the frontend only.

Step 4: Build the Next.js frontend

The same Kinsta walkthrough describes the core pattern: create pages and dynamic routes that fetch posts, then render the fetched content. Beyond that, you will rebuild:

Routing. Your existing URLs must survive. Dynamic and catch-all routes can map incoming paths to WordPress slugs, so /blog/my-post/ keeps working.
Images. Decide where media is served from, how it is resized and which formats are delivered. Next.js has built-in image optimization you can use.
SEO metadata. Titles, descriptions, canonical tags, Open Graph data, XML sitemaps and structured data have to be generated by the frontend from the data WordPress provides. Automattic flags that frontend SEO does not work automatically as it does in a traditional install.
Forms. Contact and signup forms need a new handler, with spam protection and delivery to wherever the leads go.
Search, pagination, archives and feeds. Each is a small feature you now own.

Step 5: Rebuild previews

Editors expect to click “Preview” and see their draft. Headless breaks this by default, and Pantheon lists the loss of built-in features like live previews as a known drawback. Build a preview route in Next.js that accepts a secure token and fetches the draft. Test it with the actual editors, not only developers. If previews are slow or unreliable, editors lose trust in the whole setup.

Step 6: Decide how content updates reach the live site

If the frontend generates pages ahead of time, it must learn when content changes. The usual answer is a webhook: when an editor publishes, WordPress notifies the frontend, which rebuilds or revalidates only the affected pages. Next.js supports on-demand revalidation for this. The alternatives are rendering on every request (always fresh, more server load) or time-based revalidation (simple, but changes appear with a delay). Choose per page type: a pricing page that must update instantly differs from an archive that can lag a few minutes.

Step 7: Run both sites in parallel, then switch

The safest migration adds the new frontend while the existing WordPress site keeps operating, then switches DNS or a reverse proxy once the new frontend is validated. Before the switch:

Crawl both versions and compare URLs, titles, headings, canonical tags and structured data.
Check every redirect, including old campaign URLs and trailing slash behavior.
Test forms end to end, and confirm analytics and consent tooling fire correctly.
Run performance tests on real templates, on mobile.
Keep the old site reachable for a short rollback window.

Where possible, migrate section by section rather than all at once. Moving the blog first, for instance, gives you a live test of the pipeline with limited business risk.

What to plan for after launch

The build is the smaller part of the story. A headless site is two products.

As Kamaan notes, a typical setup means two hosting environments: one for the WordPress backend and one for the decoupled frontend. WordPress.com adds that this means more maintenance because the frontend and backend are separate codebases and technologies. In practice, budget for:

WordPress updates for core, plugins and PHP, still needed even though visitors never see the theme.
Frontend dependency updates for Next.js, React and every package, including security patches.
Monitoring of both sides, plus the connection between them. If the API is down, the site may serve stale pages or break outright.
Editor support, since publishing now involves a pipeline that can fail.
Developers who know both worlds, or two parties who communicate well. Split responsibility between a WordPress agency and a separate frontend freelancer is where many projects stall.

The question of who maintains what should be written down before launch, not discovered at the first outage.

Common mistakes

Migrating for speed alone. A static Next.js site can be very fast, but so can a well-built WordPress site. Do the comparison with real measurements.

Forgetting redirects and metadata. Traffic drops after replatforming almost always trace back to changed URLs, missing canonicals or lost structured data.

Leaving content dirty. Moving shortcode-laden posts into a clean frontend produces broken pages. Clean first.

Underestimating editors. The people who use the system daily should test it before launch, and their feedback on previews is the most valuable you will get.

Hiring a team that disappears. Headless projects have many moving parts. If the people who scoped the work are not the ones who build it, requirements get rewritten halfway through.

How we approach it at Ampersand

We are a small Zurich studio, and every project is led end to end by senior engineers, from the first consultation to handover. For a WordPress to headless move, that means the person who audits your site and tells you whether headless is the right call is the same person who builds and hands it over. If your needs are better served by keeping WordPress as it is, we will say so.

We build websites, web applications and platforms, handle system integrations and replatforming, and offer audits and senior technical guidance if you want a second opinion before committing to a rebuild. Our aim is that you can run the result independently rather than depend on us. Our published pricing page lists the services, and the projects we have delivered show the kind of work behind them. After launch, our Run & monitor plan for ongoing technical support is CHF 750 per month, and our Guidance plan for advisory support is CHF 799 per month. Replatforming and build projects are scoped individually, so there is no published price for them.

A realistic decision path

If you are still unsure, work through this sequence:

Define the problem. Name the specific limit you hit, with numbers where you can.
Try the cheaper fix. Optimize the theme, hosting, caching and images and re-measure.
Prototype one section. Build a single page type in Next.js against your real WordPress data. Two weeks of prototyping tells you more than any article.
Cost both systems. Include year-two maintenance, not only the build.
Decide with your editors. If the new workflow makes their job harder, the architecture is wrong for you, however elegant.

FAQ

Can I keep my existing WordPress content when going headless?

Yes. The content stays in WordPress and is exposed through the REST API or WPGraphQL. What usually needs work is the content’s format: shortcodes, page-builder markup and theme-dependent styling do not render in a new frontend, so plan a cleanup pass before or during the migration.

Is headless WordPress better for SEO?

Not automatically. Next.js can deliver fast, fully rendered pages, which helps, but titles, canonical tags, sitemaps, structured data and redirects all have to be rebuilt in the frontend. A careful migration can match or improve rankings; a careless one loses them.

Do I need WPGraphQL to connect WordPress to Next.js?

No. The built-in REST API is enough for many sites. WPGraphQL becomes attractive when you have many custom fields and relations and want to fetch them in a single request, but it adds a plugin and a query language to maintain.

Does headless cost more than a normal WordPress site?

Usually, yes. You maintain two codebases and two hosting environments, and you need developers comfortable with both. The extra cost is justified when the frontend flexibility, multi-channel delivery or performance gains are central to your business, not when a standard theme would do.

Can I move to headless gradually?

Yes, and it is often the safest route. You can build the Next.js frontend alongside the live WordPress site, move one section at a time, and switch traffic only after the new frontend has been validated.

Sources

Talk to us

Have a project this touches on?

A free 10-minute call is the fastest way to find out whether we are the right studio for it.

Book a free 10-min call

Keep reading