Migrating from WordPress to Next.js, Vercel and Claude Code

TL;DR

• You have two routes: move everything into Next.js with a new content layer, or keep WordPress as a headless back end behind a Next.js front end
• WordPress creates far more URLs than the pages you wrote, including category, tag, author, date and attachment pages, feeds and pagination, and each one needs a decision
• Export posts through Tools, Export, or pull them through the REST API, which returns rendered HTML with shortcodes already processed
• If you run Yoast SEO, its REST API fields carry your existing titles, descriptions and canonicals, so the new site can launch with the same metadata
• Redirect rules can live in a plugin, in your SEO plugin or at the server, so collect all of them before you switch DNS
• Date-based permalinks can move to a cleaner structure with one pattern redirect, though keeping the old structure is the safer first move
• Your media library sits under wp-content/uploads, so either keep those paths or redirect them, because image search traffic follows the file URL

Why WordPress sites are moving

WordPress runs a huge part of the web and it earns that position. It is flexible, it is free to install, and there is a plugin for everything.

That last part is usually why people leave. A ten-year-old WordPress site carries an SEO plugin, a page builder, a forms plugin, a caching plugin, a security plugin and a dozen others, each loading its own scripts, each needing updates. Every update is a small risk, and every plugin is code you did not write and cannot easily read.

Claude Code changes the trade. A Next.js site holds only the code your site needs, all of it readable, and Claude Code can change any of it on request. You give up the plugin directory and gain a site that does exactly what you asked for.

This guide covers what is specific to WordPress. For the general process, start with our guide to migrating any website to Next.js, Vercel and Claude Code.

First decision: full move or headless WordPress

Before you export anything, pick a route.

A full move takes the content out of WordPress and into your new stack. Next.js renders it, a new content layer manages it, and WordPress gets switched off. You end up with one system to run.

Headless WordPress keeps WordPress as the place where content lives and moves only the front end. Next.js reads posts from the WordPress REST API and renders them, and editors keep the admin they know. You still maintain WordPress, its updates and its hosting, though nobody visits it directly.

Headless suits a team with years of editorial habits and several writers. A full move suits a small team that wants fewer moving parts. Either way the front end steps below apply, and our explainer on what a headless CMS is lays out the trade-offs in more detail.

Step one: inventory every URL WordPress creates

WordPress generates pages you never wrote. A typical site serves:

• Posts and pages, under whatever permalink structure you chose
• Category, tag and author archives
• Date archives by year and month
• Attachment pages for uploaded media
• RSS feeds at /feed and on every category
• Paginated listings such as /blog/page/2
• Media files under /wp-content/uploads

Each of these URL types need a decision on the new site: rebuild it, redirect it, or let it return a 404 or 410. Google's own site move guide says deleted content should return one of those two codes. Thin archive pages with no traffic are often better retired than rebuilt.

Pull the list from your sitemap, which WordPress or your SEO plugin generates, then add the Pages report in Google Search Console and your analytics landing pages. Anything with traffic or backlinks stays on the list.

Step two: get the content out

The built-in route is Tools, Export, which downloads an XML file of your posts, pages, comments, categories and tags. Claude Code can read it and split it into one file per post.

The REST API route is cleaner. Every WordPress install serves posts at /wp-json/wp/v2/posts, and each response includes the rendered HTML of the content. Rendered means your shortcodes have already run, so a gallery or a button shortcode arrives as HTML instead of square-bracket code. Ask Claude Code to write a script that pages through every post and page and saves them as JSON.

Write a script that pulls every published post and page from https://oursite.com/wp-json/wp/v2, with their slugs, dates, authors, categories, featured images and rendered content. Save each one as a JSON file in /content and log any request that fails.

Then check the HTML that comes out. Block editor content arrives full of wp-block class names, and page builders add their own wrappers. Ask Claude Code to list every class and wrapper pattern it finds, then decide which to style and which to strip.

Your SEO metadata comes out separately. If you run Yoast SEO, its developer documentation says it appends yoast_head and yoast_head_json fields to REST API responses, holding the title, description, canonical and Open Graph data for each post. Pull those into each post's file and the new site can launch with exactly the metadata Google already knows.

Step three: rebuild with Claude Code

Give Claude Code screenshots of each template, your theme's colours and type, and the content files. Build a component library first, then the page templates, then the blog.

Rebuild the single post template as a server component. It reads one post from /content/posts, renders the cleaned HTML, and sets the title, description and canonical from that post's Yoast fields.

Keep URLs identical wherever you can. If your permalinks use the post name, a post at /how-we-price on WordPress can sit at /how-we-price in Next.js with no redirect at all.

Step four: collect every redirect

WordPress redirects hide in more than one place. Check the Redirection plugin if you use it, which can export its rules as CSV. Check your SEO plugin, since some include their own redirect manager. And check the server, where an .htaccess file or your host's dashboard may hold rules that never appear inside WordPress.

Bring them all into one list, then add rules for anything the migration changes. Next.js handles redirects in next.config.js and sends a 308 status code for permanent ones. Google treats 301 and 308 both as permanent redirects, and its site move guide confirms permanent redirects do not lose PageRank.

Two WordPress cases deserve their own rules.

Date-based permalinks. WordPress offers several permalink structures, including day and name, and month and name. If your posts live at /2021/04/12/how-we-price, one pattern rule can send every one of them to /blog/how-we-price. That said, keeping the old structure for launch and changing it later follows Google's advice to change one thing at a time.

Media files. Images under /wp-content/uploads can rank in image search and get hotlinked by other sites. Either serve them from the same paths on the new site, or add a wildcard redirect from /wp-content/uploads/:path* to the new location.

A large WordPress site can run into thousands of redirects. Vercel allows 2,048 redirect routes in configuration and offers bulk redirects beyond that on its paid plans.

Step five: rebuild what plugins used to do

Make a list of every active plugin and what it does for visitors. They fall into a few groups.

SEO plugins become code. Titles, descriptions, canonicals, the sitemap and robots.txt all move into Next.js metadata files, set once and applied everywhere. Our guide to SEO for Vercel and Next.js sites covers each file.

Forms become a server action or a route handler that passes submissions to your email tool or CRM.

Caching and performance plugins go away. Next.js renders pages at build time or on the server, and Vercel caches them at the edge.

Comments need a decision. If yours are mostly spam, dropping them removes a problem. If you have an active discussion, bring the comments across with the posts.

The RSS feed needs keeping. Email tools that send new posts to subscribers often read your feed, so rebuild it at /feed with a route handler, or redirect the old feed URL to the new one.

Step six: where content lives now

On the headless route, WordPress stays your CMS. Contengi's WordPress integration connects to self-hosted WordPress 5.6 or newer through the core REST API with an Application Password, with no plugin to install. Its agents read every post you have, including ones Contengi never wrote, and publish new and refreshed posts back to the same URL. Your Next.js front end then renders whatever WordPress holds.

On the full move, WordPress goes away and the site needs a new home for posts. Contengi works as that AI-native CMS. Claude Code adds one signed endpoint to your site from a single prompt, posts arrive with their title, slug, SEO fields, body, FAQ and featured image, and they are stored in your own database. Edits republish to the same URL, so refreshing an old post never creates a duplicate.

Either way, page copy lives in code where Claude Code edits it, and the agents writing posts work from your knowledge base and hard rules.

What you gain

A smaller attack surface, for a start. No plugin updates to chase, no admin login at a predictable URL on your public site, and no database that every page request touches.

A faster site, if you keep it lean. You choose every script that loads, and Next.js gives you image optimisation and server rendering by default.

Better readability for AI crawlers. Vercel and MERJ's study of AI crawler traffic found that OpenAI's crawlers, ClaudeBot and PerplexityBot do not run JavaScript. A WordPress theme that loads content through scripts can hide it from them, while a server-rendered Next.js page hands it over in the first response.

And speed of change. A new landing page becomes a conversation with Claude Code instead of a page builder session.

What you do not automatically gain is traffic. The migration protects what you have and removes limits. Growth comes from what you publish after.

Launch checklist

1. Keep WordPress hosting live, behind a login, until the new site has been stable for a few weeks
2. Test every redirect on a preview deployment, including the date and media patterns
3. Confirm titles, descriptions and canonicals match the Yoast values for your top pages
4. Check the new /feed loads and your email tool still picks up posts
5. Switch DNS, submit the new sitemap in Search Console and watch the Pages report daily for two weeks

Frequently asked questions

Can I move from WordPress to Next.js without losing SEO?

You can keep the loss small and temporary. Keep URLs identical where possible, redirect every URL that changes, carry over your Yoast titles and descriptions, and expect some movement while Google recrawls.

Should I use headless WordPress or move off WordPress entirely?

Headless suits teams with several writers who want to keep the WordPress editor. A full move suits a small team that wants one system to run and no plugin updates.

How do I export WordPress content for Next.js?

Use Tools, Export for an XML file, or pull posts and pages from the REST API at /wp-json/wp/v2, which returns rendered HTML with shortcodes already processed.

What do I do with WordPress category and tag pages?

Keep the ones with traffic or backlinks, and redirect or retire the rest with a 404 or 410. Thin archive pages rarely earn their place on a rebuilt site.

Can Contengi publish to a headless WordPress site?

Yes. Contengi publishes through the WordPress REST API with an Application Password, so posts land in WordPress and your Next.js front end renders them.