How to make your WordPress site headless without losing SEO

importivity.com ran on WordPress with Elementor. A cold visit took around ten seconds. The team edits that site every week, so moving off WordPress was not an option. I made it headless instead: the team kept the same admin, and the public site started loading in about a second.

This guide is the whole method, written so you can do it on your own site. It covers what headless means, when it is worth it, every step of the move, the exact prompts to hand Claude for each step, and the SEO checks that decide whether your rankings survive.

What headless WordPress is

A normal WordPress site does two jobs. It stores your content, and it builds the page every time someone visits. PHP runs, the database answers, the theme and plugins add their CSS and JavaScript, and only then does the visitor see anything.

Headless splits those jobs. WordPress keeps the first one: your team logs in, writes and edits exactly as before. A separate front end takes the second one. It reads the content from WordPress through its API and turns it into fast, finished pages.

Your editors keep WordPress. Your visitors never touch it.

The "head" is the part visitors see. Headless means WordPress no longer draws it.

Why it is worth doing

• Speed. Pages are built ahead of time, so the browser gets finished HTML instead of waiting on PHP and a database.
• The same editor. Nobody retrains. Posts, pages, media and custom fields stay where they are.
• Security. The WordPress admin can sit on a private subdomain. Visitors only ever hit static pages.
• Stability under traffic. A spike serves files that already exist. The database is not woken up for every visit.
• Freedom on the front end. You design with modern tools instead of fighting a theme or a page builder.

When it is not worth it

Be honest about the trade offs before you start.

• Anything a plugin prints on the page will not come across by itself. Page builders like Elementor, form plugins, sliders and popups all need rebuilding on the new front end.
• You now run two things: the CMS and the front end.
• Previews and publishing need wiring so a new post shows up without a manual rebuild.

If your site is small, rarely visited, and already fast enough, a good cache plugin is cheaper. Headless pays off when speed matters to sales, when the site is large, or when a page builder is dragging every page down.

What you need

Three things, before you start.

• A Claude subscriptionA paid plan that includes Claude Code, like Pro or Max. Claude Code is the version that works in your terminal: it reads files, runs commands and edits code, instead of only chatting.
• A VPS for the new front endAny small Linux server with 2 GB of RAM or more runs a Next.js site behind nginx. WordPress can stay on the hosting it has now.
• SSH access to your WordPress siteThe login to the server WordPress runs on, ideally with WP-CLI installed. If your host offers no SSH, SFTP works, but then Claude can only move files, not run commands.

Also useful: access to your domain's DNS for the switch on launch day, and Google Search Console for the before and after.

Two kinds of access, two different jobs

There are two ways into WordPress in this guide, and they are not interchangeable.

• SSH is for Claude, during the move. With it, Claude runs WP-CLI on the server: it lists every post and page, installs plugins, exports redirects, reads your theme and settings, and backs up the database. That is far faster than clicking through the admin.
• The REST API is for the new website, forever after. The front end reads content through it, because WordPress hands over finished content there: shortcodes run, filters applied, SEO tags filled in by Yoast or Rank Math. Reading the database directly would give you raw rows and none of that.

Claude works on the server over SSH. The website reads through the API. The site itself never holds a login that can change anything.

Keep the SSH access safe while Claude has it.

• Point it at a staging copy of the site first, or at the very least back up the database before anything changes.
• Create a separate SSH user for the job and remove it when you are done. Do not hand over your main root login.
• Never paste a password or private key into the chat. Set the key up on your own machine, so Claude uses the connection without ever seeing the secret.
• Ask Claude to show you every command that changes something before it runs it.
• Skip plain FTP. It cannot run commands, and it sends your password unencrypted.

Step 1: Audit the site you have

You cannot keep what you have not listed. Before touching anything, write down every URL, every template, and every plugin that puts something on the page.

• Export every URL from the XML sitemap, plus any page that is not in it.
• Group them by type: pages, posts, categories, tags, custom post types, archives.
• Export every redirect you already have. importivity.com had 250, and every one of them came across.
• List the plugins that output anything visible: forms, SEO tags, schema, sliders, popups, analytics.
• Record a baseline: PageSpeed scores for your key pages and three months of Search Console data.

Ask Claude:

Connect to my WordPress server with ssh wp-staging (the host is set up in my SSH config). Do not change anything yet. Use WP-CLI to list every published post, page and custom post type with its permalink, every category and tag, every active plugin, and every redirect. Also read https://example.com/sitemap_index.xml and every sitemap it links to. Write every URL to urls.csv with columns: url, type, title, meta description, canonical and HTTP status, fetching each URL to fill in the last four. Save the redirects to redirects.csv. Then list any URL that is in WordPress but missing from the sitemap, and the plugins that print something on the page.

Step 2: Turn WordPress into the back end

WordPress already has a REST API at /wp-json/wp/v2. For most sites that is enough. If you prefer GraphQL, install the WPGraphQL plugin.

• Move WordPress to its own subdomain, like cms.example.com. The main domain will belong to the new front end.
• Keep your permalink settings exactly as they are. Your URLs are your rankings.
• Make custom fields visible to the API. In ACF, turn on "Show in REST API" for each field group.
• Expose your SEO plugin's data. Yoast adds a yoast_head_json field to every REST response. Rank Math has a Headless CMS Support setting that does the same.
• Create an Application Password for the front end, so it can read drafts for previews.

Claude can do most of this over SSH with WP-CLI, like installing WPGraphQL or switching on the SEO plugin's headless option. Moving WordPress to its subdomain touches DNS and the site URL, so do that one with a backup in hand.

Ask Claude:

Over ssh wp-staging, back up the database with wp db export, then show me the commands you plan to run before running them. Install and activate any plugins we agreed on, and confirm the SEO plugin exposes its head tags in the REST API. Then fetch one page, one post and one category from https://cms.example.com/wp-json/wp/v2, and describe every field I will need to rebuild them on a new front end: title, content, featured image, custom fields, author, dates, and the SEO fields in yoast_head_json. Flag any content that is Elementor or shortcode output instead of clean HTML.

Step 3: Build the front end

I used Next.js. It can build every page ahead of time and rebuild a single page when its content changes, which is exactly what a WordPress site needs.

• Mirror your URL structure exactly. A post at /blog/my-post must still live at /blog/my-post.
• Build every page at deploy time, and let a page refresh itself when its content changes.
• Rewrite links inside the content from cms.example.com to example.com, so nobody lands on the CMS.
• Serve images compressed and in modern formats, with sizes set so the layout does not jump.
• Rebuild the page builder templates as real components. This is usually the biggest single job.

Ask Claude:

Create a Next.js App Router project that reads content from https://cms.example.com/wp-json/wp/v2. Recreate every URL in urls.csv at exactly the same path, including trailing slashes. Pre-render all of them at build time with generateStaticParams. Render titles, meta descriptions, canonicals and Open Graph tags from yoast_head_json. Rewrite any link that points at cms.example.com to example.com. Use next/image for every image.

Keep the design you already have

Going headless does not mean redesigning. If you like how the site looks, Claude can rebuild it to match: the same layout, fonts, colours, spacing and menus, as clean components instead of page builder markup. Visitors see the same site. It just loads faster.

• Give Claude the live URL of one page per template: home, a page, a post, a category, and any custom page.
• Let it pull the fonts, colours and spacing out of the current CSS, so nothing is guessed.
• Compare screenshots of old and new side by side, on desktop and on a phone, until they match.

Ask Claude:

Rebuild the design of https://example.com on the new Next.js front end so it looks the same. For each template in urls.csv, open one live example, read its CSS, and recreate the layout, fonts, colours, spacing, header and footer as React components, without Elementor markup. Then take full-page screenshots of the old and new page at 1440px and 390px wide and list every visible difference. Fix them until the list is empty.

Step 4: Rebuild what plugins used to do

Go down the plugin list from Step 1 and give each one a new home.

• Forms: post to your own API route, or to a form service.
• Search: build it on the WordPress search endpoint, or a small search index.
• Schema: generate it from your content, or pass through what your SEO plugin produces.
• Analytics and tag manager: add them to the front end layout.

Step 5: Publishing and previews

Editors expect to press Publish and see the change. Wire that in before launch, not after.

• Add a revalidation route to the front end, protected by a secret.
• In WordPress, call that route whenever a post or page is saved, so only that page is rebuilt.
• Set up preview so editors can see a draft on the real design before it goes live.

Ask Claude:

Add an API route at /api/revalidate that takes a secret and a path, and calls revalidatePath for that path. Then write a small WordPress plugin that calls it on save_post with the post's permalink. Add Next.js draft mode so the WordPress preview button opens the draft on the new front end.

Step 6: The SEO checklist

This is the part that decides whether the move is a win or a disaster. Google should see the same site, only faster.

• Same URLs. Every URL from Step 1 returns a 200 at the same path, with the same trailing slash rule.
• Redirects. Every old redirect still works, as a 301. Any URL you retire gets its own 301 to the closest page.
• Tags. Titles, meta descriptions, canonicals and Open Graph tags match the old site, page by page.
• Canonicals point at the main domain. Never at cms.example.com.
• The CMS stays out of search. Put a noindex on the CMS subdomain, and ideally a login in front of it.
• Real HTML. Content must be in the page Google downloads, not loaded later by JavaScript.
• Sitemap and robots. The sitemap lives at the same address and lists the new URLs. robots.txt points to it.
• Structured data carries over: articles, FAQs, breadcrumbs, organisation.
• Image alt text and internal links survive the move.
• Missing pages return a real 404 status, not a friendly page with a 200.

Ask Claude:

Write a script that reads urls.csv and fetches every URL from both the old site and the new one. Report any URL where the new site does not return 200, where the title, meta description, canonical or H1 differ, where the canonical points at cms.example.com, or where the page text is under 80% of the old length. Also check every redirect in redirects.csv returns a 301 to the right place.

Run it until the report is empty. Then run it again after launch.

Step 7: Launch, measure, watch

• Build and test on staging first, at something like staging.example.com, with noindex on and a password in front of it.
• Keep the old site running until the new one is live and checked, so you can compare and roll back.
• Move the domain only once staging passes the SEO checklist and you are happy with it.
• Measure both, not just the new one. I ran both through Playwright three times each and took the median.
• Point the domain at the new front end, then submit the sitemap in Search Console.
• Watch Search Console every few days for a month: indexed pages, 404s, and your top queries.

How Claude fits in

Claude is good at the parts that are big and repetitive: crawling the old site, mapping every field, scaffolding the front end, porting templates, and writing the checks. Give it the files it needs, like urls.csv, redirects.csv and one sample API response, and ask for one step at a time.

Two things stay with you. Decide which URLs to keep, merge or retire, and read the parity report yourself before you switch the domain. Claude writes the checks. You decide when the site is ready.

What happened on importivity.com

The team kept editing in the same admin. Largest contentful paint halved, from 2.2 seconds to 1.1. The page went from 1.4MB to 516KB. All 250 redirects came across, and no URL lost its ranking in the move.

Let Claude do it for you

Read this guide and follow it step by step to make my WordPress site headless: https://moazzanishfaq.com/blog/headless-wordpress-guide

My current site: https://example.com
SSH to the WordPress server: ssh wp-staging (already set up in my SSH config)
WordPress REST API: https://example.com/wp-json/wp/v2, with an Application Password in the WP_APP_PASSWORD environment variable
Server for the new front end: ssh frontend-vps

Keep the current design exactly as it is.
Start with the homepage only. Build it, send me the staging link and wait for my approval. Only once I approve it, build the rest of the pages.
Build everything on a staging environment first, at staging.example.com, with noindex on and a password in front of it. Do not touch the live site or the DNS.
Back up the database before any change, and show me every command that changes something before you run it.
When staging is ready, run the SEO checks from Step 6 against the live site and send me the report. I will move the domain myself once I am happy.