Headless WordPress with Next.js: Keeping WordPress as Your CMS, Honestly Explained

The dashboard stays, the theme goes

In a normal WordPress site, one system does two jobs. It stores your content, and on every visit it runs PHP, loads the theme and the plugins, and assembles the page. Headless splits those jobs. WordPress keeps the first one: editors log in, write, upload and press Publish exactly as before. A Next.js application takes the second: it fetches the content, renders the pages ahead of time and serves them from a CDN.

Visitors never touch WordPress at all. The admin usually moves to its own address, such as a subdomain, and the public domain points at Next.js. That is the appeal: the slow, plugin-laden part of WordPress is taken out of the visitor's path, and the familiar part stays where your team expects it. The theme, though, is gone. Next.js is the theme now, which has consequences we will get to.

Headless WordPress removes the theme from the visitor's path. It does not remove WordPress from yours.

REST or WPGraphQL: two pipes for the same content

The content travels from WordPress to Next.js over an API. WordPress has a REST API built into core, with routes under /wp-json/wp/v2/ for posts, pages, media, categories and users. Per the WordPress handbook, public content is generally available without logging in, while private and password-protected content, custom post types and metadata need authentication.

The alternative is WPGraphQL, a free, open-source plugin that adds a GraphQL endpoint at /graphql. Its wordpress.org listing says it is becoming a canonical plugin, with long-term support behind it. GraphQL lets the front end ask for exactly the fields a page needs in one request, which keeps queries tidy on content-heavy sites.

Neither is wrong. We pick based on how many content types the site has and how they relate. The bigger decision is whether headless suits your site at all, which the headless WordPress vs Next.js comparison weighs in detail.

From Publish button to live page: previews and revalidation

Two things make or break a headless site for editors: seeing a draft before it goes live, and seeing the change on the public site soon after pressing Publish. Neither comes free. Both have to be wired between the two systems.

Previews use Next.js Draft Mode. When an editor clicks Preview in WordPress, the link is pointed at a route on the Next.js site that checks a shared secret, sets a bypass cookie and redirects to the page. With that cookie, Next.js skips its caches and fetches the draft directly, while every other visitor keeps seeing the published version. The draft fetch must be authenticated; WPGraphQL's preview documentation notes that an unauthorized preview request quietly returns the published post instead, which looks like a bug until you know why.

1. 1

   Editor publishes

   WordPress saves the post. A small hook on publish sends a signed request to the Next.js site.

2. 2

   Next.js marks the page stale

   A route handler checks the signature and calls revalidatePath for that URL, or revalidateTag for every page that shows the post, such as the blog index.

3. 3

   Fresh render

   Next.js regenerates the page in the background and serves the new version, while visitors in the meantime still get a fast cached page.

4. 4

   Safety net

   A time-based refresh catches anything the hook missed, so a failed request delays an update rather than losing it.

Done well, editors stop noticing there are two systems. Done badly, they publish, see the old page, publish again, and file a ticket. Most complaints about headless WordPress trace back to these two wires.

The WordPress chores that do not go away

Headless fixes the front end. The back end is still a WordPress install, and it needs everything a WordPress install needs. Owners sometimes expect the maintenance to vanish with the theme. It shrinks; it does not vanish.

• Core, plugin and PHP updates continue on their usual schedule, with the usual chance that one breaks the admin or the API output the front end depends on.
• Two hosting bills: a PHP and MySQL host for WordPress, plus hosting for the Next.js front end.
• Security on the admin: the login page, plugin endpoints and user accounts are still targets, even if they now sit on a subdomain.
• Plugin licenses for anything still doing work in the admin, such as custom field or SEO plugins.
• API contracts: if a plugin update changes the shape of a field, the front end has to be updated to match, and someone has to notice first.

None of this is a reason to avoid headless. It is a reason to count it. Our hosting and maintenance plans can look after both halves, and the cost guide shows where the second system lands in a quote.

The third option

Athena CMS, with AI agents on staff.

Not a theme and not a blank Next.js repo. The content system we put behind every custom site: plain fields, a real preview, every version kept, and AI agents that handle the chores a plugin only nags you about.

• PPicassoImages
• AApolloSite analysis
• AAresCompetitor watch
• PPrometheusContent holes
• AAtlasPage depth and structure
• DDelphiAI search visibility

ZDAOAand 12 more agents. Two come with Athena; the rest are monthly add-ons.

Meet the agentsTake the Athena tour

PPicassoWeekly · ImagesAApolloWeekly · Site analysis

Plugins that go dark once WordPress stops drawing pages

Here is the part that surprises people. Many WordPress plugins work by adding things to the pages WordPress renders. Once WordPress stops rendering pages, those plugins keep running in the admin and show nothing to anyone. Their features have to be rebuilt in Next.js or dropped.

The page builder row is the big one. A site built entirely in Elementor or Divi keeps almost nothing of its design when it goes headless, because the design is the part that lived in the builder. For those sites, see Elementor to Next.js, Divi to Next.js or Hello Elementor to Next.js before choosing headless. Sites written in the block editor on a lean theme, like GeneratePress or Twenty Twenty-Five, fare much better.

Headless WordPress or Athena CMS: choosing the back end

Every Next.js site we build can sit on either back end. Headless WordPress keeps the dashboard your team knows. Athena CMS, the content system included with every site we build, replaces it with plain fields, a real preview and every version kept, and puts a staff of AI agents where the plugins used to be.

Mixed answers are fine too. Some sites keep WordPress headless for a large archive and move everything else to Athena. The full platform comparison is at Athena vs WordPress, and what the move feels like for your team is at switching from WordPress.

Getting there without breaking search or the editors' week

Going headless is still a migration for search purposes, because the HTML Google sees is now produced by different code. URLs should stay as they are, which headless makes easy since the content and slugs do not move. Titles, descriptions, canonicals and structured data need to be output by Next.js, ideally from the SEO plugin's own data so editors keep one place to edit them. The checklist is in migrating without losing SEO.

Editors need a short handover too: where Preview now opens, how long a published change takes to appear, and which old blocks or shortcodes no longer do anything. Wiring previews and publishing hooks adds a phase of its own to the migration timeline. We build headless, side-by-side and full builds through WordPress to Next.js development, and the wider migration options live on the WordPress to Next.js hub. If you are still deciding whether WordPress should stay at all, WordPress vs Next.js vs Athena CMS puts all three side by side.