Migrating from WordPress to Next.js: What Actually Happens

The WordPress Paradox

WordPress is simultaneously the most popular CMS in the world and the one people most want to leave. It powers 40% of all websites, and yet the search query "migrate away from WordPress" has tripled in volume since 2024.

The reasons are predictable:

• Security maintenance is relentless. WordPress core, themes, and plugins need constant updates. Skip one, and you're a target for automated attacks. The average WordPress site has 20+ plugins, each one a potential vulnerability.
• Performance degrades over time. Every plugin adds JavaScript, CSS, and database queries. A fresh WordPress install loads in 1.2 seconds. After two years of real-world use? 4-6 seconds is common.
• PHP is yesterday's language for frontend. The frontend world has moved to React, TypeScript, and edge computing. WordPress is still rendering HTML on a PHP server, and the performance gap is widening every year.
• AI tools can't edit WordPress themes. Claude Code can't navigate a WordPress theme with its mix of PHP, HTML, CSS, JavaScript, and template hierarchy. But give it a Next.js project with Tailwind? It can refactor the entire frontend in minutes.

The Honest Migration Timeline

Every WordPress-to-Next.js migration guide shows a neat flowchart. Here's what the flowchart doesn't show:

Week 1: The Audit That Humbles You

You open your WordPress admin and start cataloguing. That's when you realize your simple WordPress site actually has:

• 23 active plugins, 8 of which you don't recognize
• A theme that was last updated in 2023
• 4 custom post types created by plugins
• 127 blog posts with rich content, embedded videos, and custom shortcodes
• WooCommerce with 3 payment gateways (if applicable)
• A contact form with conditional logic and CRM integration
• Custom PHP functions in functions.php that you forgot you wrote
• SEO metadata managed by Yoast across every single page

This is a typical WordPress site. Not a complex one. A typical one.

Week 2: The Plugin Audit

Every WordPress plugin needs a replacement strategy. There are three categories:

1. Plugins you can replace with native code. Contact forms, SEO meta tags, image optimization, caching — these are all built into modern frameworks. You don't need a plugin for what Next.js does out of the box.

2. Plugins you can replace with services. Email marketing (use the API directly), analytics (use Plausible or Umami), booking systems (Cal.com), e-commerce (Shopify's Storefront API).

3. Plugins you'll need to rebuild. Custom calculators, proprietary workflows, membership gates, complex form logic. These require actual development work, and this is where migration timelines explode.

Week 3-4: The Content Migration Hellscape

WordPress content migration sounds simple: export posts, import them to your new CMS. In reality:

• Shortcodes are everywhere. WordPress plugins inject shortcodes like [gallery ids="1,2,3"] and [contact-form-7 id="42"] throughout your content. Each one needs to be identified and replaced with actual components.
• The Block Editor (Gutenberg) generates complex HTML. Those nice-looking columns, buttons, and media blocks? They generate HTML with WordPress-specific class names and data attributes that mean nothing outside WordPress.
• Image paths are absolute. Every image in your content points to yoursite.com/wp-content/uploads/2024/03/image.jpg. You need to download every image, re-optimize it, upload to your new host, and rewrite every reference.
• Post metadata is scattered. SEO titles are in the Yoast meta table. Featured images are in the post_meta table. Custom fields are wherever ACF decided to put them. Your export needs to gather data from 3-5 different database tables per post.

Week 5: The WooCommerce Problem (If Applicable)

If your WordPress site has WooCommerce, the migration complexity doubles. Product data, customer accounts, order history, tax rules, shipping zones, discount codes — all of this lives in WordPress's database and needs to go somewhere.

Most teams realize at this point that the best strategy is to keep WooCommerce for e-commerce (or switch to Shopify) and build the marketing site in Next.js. A headless architecture where the storefront is decoupled from the CMS. It works, but it's a fundamentally different architecture than what you had before.

The Technical Migration: Step by Step

1. Export Your Content

Use the WordPress REST API (/wp-json/wp/v2/posts) to export content programmatically. Don't use the XML export — it's lossy and hard to parse. Write a script that pulls every post with its metadata, categories, tags, and featured images.

2. Set Up Your Next.js Project

Start with a clean Next.js 15 project. Add Tailwind CSS for styling, Payload CMS (or your CMS of choice) for content management, and set up your deployment pipeline early. Don't wait until the end to figure out hosting.

3. Build Your Component Library

Translate your WordPress theme into React components. Don't try to replicate it exactly — take this opportunity to improve the design. Your old WordPress theme probably has style inconsistencies that you've been ignoring.

4. Transform and Import Content

Write a transformation script that converts WordPress HTML to your new format. Handle shortcodes, rewrite image URLs, and preserve SEO metadata. This script will be ugly. That's fine. It only needs to run once.

5. Implement URL Redirects

WordPress URLs follow patterns like /2024/03/post-title/ or /category/post-title/. Your new site probably uses /blog/post-title. Every old URL needs a 301 redirect to the new URL. Miss one and you lose that page's search ranking permanently.

6. SEO Verification

After launch, monitor Google Search Console daily for two weeks. Watch for crawl errors, dropped pages, and indexing issues. Your rankings will fluctuate — that's normal. If they haven't stabilized after 4 weeks, something went wrong with the migration.

What Makes This Hard (Really)

The technical steps above are knowable. The hard part of a WordPress migration is scope management. Every WordPress site has grown organically over years. Features were added piecemeal. Plugins were installed to solve problems that nobody remembers anymore. Content was created by multiple people with different formatting habits.

When you migrate, you have to make hundreds of micro-decisions: Do we keep this feature? Do we rebuild this form exactly, or improve it? Do we migrate all 127 blog posts, or just the 30 that get traffic? Each decision takes time, and the decisions compound.

This is why most WordPress migrations take 2-3x longer than initially estimated. Not because the technology is hard, but because the scope is always bigger than you think.

The AI Advantage

Here's the silver lining: once your site is in Next.js, the speed advantage is permanent. Need to add a new page? Claude Code can scaffold it in 30 seconds. Need to update your pricing section? Describe the changes in plain English. Need to fix a mobile layout bug? AI tools can identify and fix CSS issues faster than any human.

The migration is a one-time cost. The velocity gain is forever.