A headless WordPress migration usually changes far less about a writer’s day than the phrase suggests. If WordPress stays in place and only the public site is rebuilt, writers keep the same login, the same editor, the same media library and the same categories and tags. The thing that reliably stops working is preview. If instead WordPress is replaced by a different headless platform, almost nothing about the writer’s day survives, and the two situations get discussed as though they were one.
Before anything is moved, exported or decoupled, this article assumes you already have the backup and rollback plan this cluster treats as non-negotiable: a verified, restorable copy of your content and your database, taken and tested before a single change is made, plus a written answer to the question “if this is wrong on Thursday, what exactly do we do on Friday.” The rollback for a decoupling project is that the existing site stays running and reachable until the replacement has been checked against real content by the people who file the posts. Do not retire the working site to save hosting cost while the new one is still being verified.
This is written in July 2026 and describes how these setups generally behave as of that date, from platform documentation and current published guidance rather than from any rebuild performed for this site. Headless tooling moves quickly, so check the specifics against your own stack before relying on any detail here.
The distinction the question usually hides
“Going headless” is used for two projects that have almost nothing in common from an editorial seat.
The first is headless WordPress. WordPress stays exactly where it is. It keeps your posts, your users, your media, your taxonomies and your admin screens. What changes is that the public pages are no longer rendered by a WordPress theme; a separate front end reads the content out of WordPress and renders it instead. From the writing side this is a change of scenery for readers, not for you.
The second is replatforming to a headless CMS. WordPress goes away and something else holds the content. This is a full CMS-to-CMS migration and every risk in the migration guide applies to it in full, because it is exactly that.
Both get called “going headless” in the same meeting. If you are the person who has to keep publishing through it, the first question to ask, before any other, is which of the two is actually being proposed. The rest of your answer depends entirely on it and nothing else in the conversation will make the distinction for you.
What does not change when WordPress stays
If WordPress remains the place content lives, the following are simply unaffected, because they are functions of WordPress itself rather than of the theme that used to render the site:
- Your login and the admin. Same URL, same account, same permissions.
- The editor. Whichever editor you were using is the editor you keep. Blocks, if you were using blocks. The classic editor, if you were on that.
- The media library. Uploads, the existing library and the way images are attached to posts all continue as before.
- Categories and tags. They stay in WordPress and stay editable there. Whether the new front end actually renders an archive page for each one is a separate question worth asking, and it is a common gap.
- Drafts, scheduling and revisions. Post status handling is core WordPress behavior and does not depend on the theme.
- Users and roles. Who can write, who can edit others’ work and who can publish is unchanged.
That list is the reason this route gets described as the lower-risk one, and for the writing team that description is fair. Nothing is being exported, converted or re-imported, so none of the content-fidelity failures in the 12 things that break in every CMS migration are in play. Your archive is not moving. Only the thing that draws it on a screen is being replaced.
What does change, and preview is the big one
Here is the change that matters most and gets the least attention, because it looks like a small technical to-do item on a build plan rather than what it is in practice.
In a conventional WordPress install, Preview shows you the actual page as a reader will see it, produced by the same theme that produces the live site. Decoupled, that stops being automatic. The theme is no longer what renders the page, so the preview button no longer has anything to render with. Restoring it means the new front end has to be given its own way to fetch unpublished content and draw it, and until that work is done and working, writers have a publish button and no reliable way to see the result first.
This is worth stating plainly to whoever is planning the project, because a writing team that cannot preview will either publish blind or build a slow, informal workaround of screenshots and staging requests. Ask specifically: will preview work on day one, for drafts, for scheduled posts, and for edits to already-published posts? Those are three separate cases and it is common for a build to cover the first and miss the other two.
Three smaller changes tend to arrive with it:
Anything the old theme was doing quietly stops. Related-posts blocks, author boxes, breadcrumbs, sidebars and share buttons were theme features, not content. They do not travel with the content because they were never in it. Someone has to decide which of them the new front end reproduces, and that decision is easier to make before the build than after.
Formatting that depended on the theme may render differently. Content stored as platform-specific markup only looks right where something knows how to interpret it, which is the subject of what happens to shortcodes, blocks and embeds and applies here even though your posts are not moving anywhere.
Publishing may stop being instant. Depending on how the front end is built, a published post may appear immediately or may wait for the site to rebuild. If it waits, find out how long and whether an editor can trigger it, because “I fixed the typo but it is still wrong on the site” is a support conversation nobody wants to have repeatedly.
The archive question, in each of the two cases
If WordPress stays, your archive does not move. There is no export, no conversion and no import, so there is nothing here for the content-fidelity risks to attach to. The work is verification of a different kind: does every existing URL still resolve on the new front end, does every category and tag archive still exist, and does old content that used unusual formatting still render. That is a checking job, not a migration job.
If WordPress is being replaced, this is a CMS-to-CMS migration with all of its weight. Your images have to survive the move, your internal links have to be repaired afterward, and your categories and tags will not map across intact because headless platforms model classification very differently from WordPress. Treat it as the migration it is and work through this cluster from the pillar down, rather than treating it as a front-end project that happens to move some content.
The dangerous case is a project scoped and budgeted as the first and delivered as the second. It happens when “headless” is agreed before anyone has settled where the content will live, and the writing team is usually the last to find out.
What to ask for before the decision is made
If you are the editorial voice in this decision, these are the questions worth having answered in writing, before the build starts rather than after:
- Is WordPress staying as the place content lives, or is it being replaced?
- Will preview work on day one, for drafts, scheduled posts, and edits to live posts?
- Which theme features are being reproduced on the new front end, and which are being dropped? Get the dropped list explicitly.
- How long between pressing publish and the post appearing, and can an editor trigger that without a developer?
- Do category and tag archive pages still exist, and at the same URLs?
- Who fixes it when a post renders wrong? If the answer is always a developer, your editorial team has just acquired a dependency it did not have.
- What is the rollback? For a front-end swap the answer should be that the existing site can be restored while the new one is fixed.
None of these is a technical objection. They are all operational, they are all answerable before any code exists, and the cost of asking them late is paid entirely by the people who publish.
Where this article stops
This covers what a decoupled setup means for the person operating the CMS. Choosing an architecture, building the front end, writing the queries that fetch content and implementing the preview path are development work and are deliberately out of scope here, not because they do not matter but because they are a different job with a different reader. If you are the one building it, that is where to go looking; this article is written for whoever will be filing posts through the result.
FAQ
Does headless WordPress mean writers have to use a different editor?
No, provided WordPress itself is staying. The editor, the media library and the admin are all WordPress functions and are unaffected by replacing the theme that renders the public site.
Why does preview break?
Preview in a conventional install is rendered by the theme. Once the public site is rendered by something else, the theme is no longer producing pages, so preview has to be rebuilt on the new front end with its own handling for unpublished content. It is restorable, but it does not come for free.
Is a headless WordPress migration a content migration?
Not if WordPress stays. Nothing is exported or re-imported, so the content-fidelity risks of a real CMS-to-CMS move do not apply. If WordPress is being replaced by a different platform, then yes, and it should be planned as a full migration.
Will our categories and tags still work?
They remain in WordPress and remain editable. Whether the new front end renders an archive page for each of them at the same URL is a separate question and a common omission, so ask it directly rather than assuming.
What is the single most useful thing to settle first?
Whether WordPress is staying. Nearly every other answer changes depending on it, and the question is frequently left unresolved for longer than anyone realizes.
Written July 2026 against generally documented behavior of decoupled WordPress setups on that date. This is a fast-moving area; verify the specifics of your own stack before relying on any detail above.
