GuideWordPressNext.js

WordPress to Next.js: the complete migration guide

A practical, phase-by-phase guide to migrating from WordPress to Next.js. Covers site audit, design extraction, content migration, SEO preservation, and launch — with honest trade-offs.

MigrateLab Team

Migration Experts

9 min readApril 1, 2026

WordPress to Next.js: the complete migration guide

Why Next.js

If you are migrating away from WordPress, Next.js is the most common destination — and for good reason. Built by Vercel and backed by a massive open-source community, Next.js is a React framework that handles the things WordPress needs plugins for: server-side rendering, static page generation, image optimization, SEO meta tags, and API routes. It is the framework that companies like Netflix, Nike, and The Washington Post use for their web properties.

But the reason Next.js matters for small and medium businesses is not the enterprise pedigree. It is the practical benefits:

Performance. Pages load in under 1 second without caching plugins, optimization tweaks, or CDN configuration. Fast by default, not fast by effort.
Cost. Hosting on Vercel's free tier or a $5/month VPS. No plugin licenses, no managed WordPress hosting fees, no security tool subscriptions.
AI editability. Next.js codebases are fully readable and editable by AI tools like Claude Code and Cursor. This changes the speed of every future website change.
Developer ecosystem. React is the most popular frontend framework. TypeScript is the most wanted language. Tailwind CSS is the most adopted utility framework. Finding developers, resources, and tooling for Next.js is straightforward.

This guide walks through the complete migration process — from initial audit to post-launch monitoring — in eight phases. It is based on our experience migrating dozens of WordPress sites to Next.js, including the mistakes we have learned to avoid.

Phase 1: Site audit and content inventory

Every successful migration starts with understanding exactly what you have. Rush this step and you will discover missing pages, broken integrations, and forgotten features halfway through the build.

A thorough audit covers:

Pages and content types. List every page, post type, and content structure. Standard WordPress has pages and posts. Most real-world sites also have custom post types: testimonials, case studies, team members, services, portfolio items. Each becomes a collection or content type in the new architecture.
Plugin inventory. List every active plugin and its purpose. Each plugin represents functionality that needs to exist in the new codebase — whether as a built-in framework feature, a React component, or an external API integration.
URL structure. Document every URL pattern. WordPress URL structures vary: /category/post-name/, /year/month/post-name/, /custom-post-type/slug/. Each pattern needs a corresponding route in Next.js and a redirect rule for the old format.
Media library. Count images, videos, and documents. Note total file sizes. Large media libraries (500+ images) need automated migration scripts rather than manual transfer.
External integrations. Map every connection to external services: analytics, CRM, email marketing, payment processing, chat, booking tools. Each needs to be reconnected on the new site.

Phase 2: Design extraction and component mapping

With the audit complete, the next phase is translating the visual design into a component architecture. This does not mean rebuilding every pixel — it means identifying the reusable patterns and turning them into React components.

Start by cataloging the visual elements across your site:

Navigation patterns (desktop menu, mobile hamburger, dropdowns)
Hero sections (variations across different pages)
Card layouts (blog post cards, service cards, testimonial cards)
CTA (call-to-action) sections and buttons
Footer layout and link structure
Typography scale (heading sizes, body text, captions)
Color palette (background colors, text colors, accent colors)
Spacing system (section padding, element margins)

Each visual pattern becomes a React component with typed props. A "service card" in WordPress — which might be an Elementor widget, a Gutenberg block, or a custom PHP template part — becomes a ServiceCard component in Next.js with clear, typed inputs for title, description, icon, and link.

Phase 3: Next.js project setup

The technical setup is straightforward. Initialize a new Next.js project with TypeScript and Tailwind CSS:

The key architectural decisions at this stage:

App Router vs. Pages Router. Use the App Router (default since Next.js 13). It supports React Server Components, streaming, and nested layouts — the modern standard.
CSS approach. Tailwind CSS is the recommended choice. It generates only the CSS your site actually uses (typically 15-30KB instead of 500KB+), and AI tools understand Tailwind classes natively.
CMS selection. If your site needs a content editing interface (blog, team bios, case studies), choose a headless CMS. Payload CMS (self-hosted, open source), Sanity (cloud-hosted, generous free tier), or flat Markdown files (simplest option for small sites) are the most common choices.
Deployment target. Configure for your hosting platform from the start. Vercel requires zero configuration. Cloudflare Pages and Netlify need adapter settings. Self-hosted Docker needs a Dockerfile.

Phase 4: Page-by-page rebuild

This is the core build phase — translating each page from the WordPress design into Next.js code. The approach:

Start with the layout. Build the header, footer, and global layout first. These appear on every page and establish the component patterns.
Build the homepage. The homepage usually has the most unique sections and establishes the design system. Components built here (hero, features, testimonials, CTA) are reused throughout the site.
Build interior pages. Services, About, Contact — these pages reuse components from the homepage with different content. Builds go faster as the component library grows.
Build dynamic pages. Blog posts, case studies, and other content-driven pages need dynamic routing and CMS integration. These are built as templates that render content from the CMS.

AI tools accelerate this phase dramatically. Show Claude Code a screenshot of a WordPress page section and describe what it does, and the AI generates the corresponding React component with Tailwind styling. A page that would take a developer 4-6 hours to build from scratch takes 30-60 minutes with AI assistance.

Phase 5: Content migration

With the page templates built, the content needs to move from WordPress into the new system. The approach depends on the CMS choice:

For headless CMS (Payload, Sanity): Write a migration script that reads the WordPress XML export, transforms content into the CMS format, and creates entries via the CMS API. Images are uploaded separately and linked to their content entries. Blog posts with 50+ entries should always be migrated via script — manual entry is error-prone and time-consuming.
For flat files (Markdown, MDX): Convert WordPress content to Markdown files with frontmatter (title, date, excerpt, tags). Each post becomes a .mdx file in the project. Simpler than a CMS but without the visual editing interface.
For static pages: Content is embedded directly in the React components. This is the simplest approach for brochure sites where content changes infrequently.

Media migration: download all WordPress uploads, optimize image sizes and formats (WebP conversion, responsive sizes), and host them in cloud storage (Cloudflare R2, AWS S3) or the CMS's built-in media management.

Phase 6: CMS setup

If your site has content that changes regularly (blog posts, team members, testimonials), a headless CMS provides the editing interface your content team needs. The most common options:

Payload CMS. Open source, self-hosted, TypeScript-native. Full admin panel for content editing, media management, and access control. Runs alongside your Next.js app. Zero monthly cost (self-hosted).
Sanity. Cloud-hosted with a generous free tier. Real-time collaborative editing, powerful content modeling, and a customizable admin interface (Sanity Studio). Good for teams that want zero infrastructure management.
No CMS needed. If content changes are infrequent and handled by a developer or via AI tools, you can skip the CMS entirely. Content lives directly in the code. AI tools like Claude Code can edit content just as easily as design elements.

Phase 7: SEO preservation

SEO preservation is non-negotiable. A migration that loses search rankings has failed, regardless of how fast the new site is. The critical elements:

301 redirects. Every old URL that has changed must return a 301 redirect to the new URL. No exceptions. Configure these in next.config.js for static redirects or in middleware for dynamic patterns.
Meta tags. Title tags, meta descriptions, and canonical URLs must match the old site or be improved. Export these from Yoast or Rank Math before migration and implement them using Next.js's Metadata API.
XML sitemap. Generate a new sitemap that includes all pages and submit it to Google Search Console. Next.js can generate sitemaps automatically or via a custom route.
Structured data. Preserve any schema.org markup (Article, FAQ, HowTo, Product) and consider adding more. Structured data helps both Google and AI search tools understand your content.
robots.txt. Ensure your robots.txt allows search engine crawlers and AI crawlers access to all public pages.
Internal linking. Verify that all internal links point to correct URLs. Broken internal links are bad for SEO and user experience.

Phase 8: Launch and monitoring

With everything built, tested, and verified, launch day is straightforward:

Deploy the final build to your production hosting
Lower DNS TTL 24-48 hours before the switch
Update DNS records to point to new hosting
Verify the site loads correctly from multiple locations
Submit the new sitemap to Google Search Console
Monitor Search Console, analytics, and form submissions daily for 2 weeks
Keep the old WordPress site accessible (not public) as a fallback

Most sites see immediate improvements in Lighthouse scores and load times. SEO rankings typically maintain or improve within 2-3 months as Google recognizes the better Core Web Vitals.

The honest trade-offs

We would be doing you a disservice if we only talked about the benefits. Here are the real trade-offs of migrating from WordPress to Next.js:

One-time cost. A professional migration costs $2,000-8,000 depending on site size and complexity. This is a real upfront investment, though it pays for itself in 8-18 months of eliminated WordPress costs.
Content editing changes. Your content team will use a different admin interface. Payload and Sanity are intuitive, but there is a short learning curve. Expect 1-2 weeks of adjustment.
WordPress plugin alternatives. If you rely on niche WordPress plugins (specific WooCommerce extensions, membership plugins, LMS plugins), the equivalent functionality may need custom development in Next.js.
E-commerce complexity. If you run WooCommerce, the e-commerce migration adds significant scope. Many businesses migrate the marketing site to Next.js and keep Shopify for e-commerce, or use Saleor/Medusa as a headless alternative.

For most business websites — marketing sites, content sites, service businesses — the benefits of Next.js clearly outweigh the migration effort. For complex e-commerce or membership sites, the calculation requires more careful evaluation.

Avg Lighthouse Score

Performance score after migration to Next.js

0.8s

Avg Load Time

Typical page load for a Next.js site

$0/mo

Hosting Cost

Vercel free tier covers most business sites

100%

SEO Preserved

With proper redirects and meta tag migration

The 8-Phase Migration Process

Phase 1: Site audit and content inventory

Document every page, post type, plugin, URL pattern, media asset, and external integration on your current WordPress site. This inventory becomes the specification for the new site. Use Screaming Frog for automated crawling and Google Search Console for indexed URL lists.

Tip: Export everything before you start building. Your WordPress export is the source of truth during migration.

Phase 2: Design extraction and component mapping

Catalog all visual patterns across your site: navigation, heroes, cards, CTAs, footer, typography, colors, spacing. Map each pattern to a React component. This creates a component library that makes page builds efficient and consistent.

Tip: Screenshot every unique page section. These screenshots become specifications for the AI when generating components.

Phase 3: Next.js project setup with Tailwind

Initialize the project with Next.js App Router, TypeScript, and Tailwind CSS. Choose your CMS (Payload, Sanity, or flat files). Configure deployment for your hosting platform. Set up the Git repository and CI/CD pipeline.

Tip: Deploy early and deploy often. Set up hosting in the first hour so you can preview the site throughout the build.

Phase 4: Page-by-page rebuild

Build the global layout (header, footer), then the homepage, then interior pages, then dynamic templates. Use AI tools to accelerate component generation. Each page builds faster as the component library grows.

Tip: Build the homepage first — it establishes the design system and creates reusable components for the entire site.

Phase 5: Content migration (WordPress REST API export)

Export content from WordPress via XML export or REST API. Write migration scripts to transform and import content into your chosen CMS. Migrate and optimize all media files (WebP conversion, responsive sizing). Automate wherever possible — manual content entry is slow and error-prone.

Tip: For sites with 50+ blog posts, automated migration scripts save hours of work and reduce errors.

Phase 6: CMS setup (Payload, Sanity, or flat files)

Configure content collections, define field schemas, and set up the admin interface for your content team. Import migrated content. Test the editing workflow to ensure your team can create and update content independently.

Tip: Match the CMS content model to how your team thinks about content, not how WordPress structured it.

Phase 7: SEO preservation (redirects, meta, sitemap)

Implement 301 redirects for every changed URL. Migrate all meta tags and canonical URLs. Generate and submit a new XML sitemap. Preserve structured data markup. Verify internal linking. This phase is critical — SEO mistakes here can take months to recover from.

Tip: Test every redirect. A single 404 where a 301 should be can permanently lose that page's search ranking.

Phase 8: Launch and monitoring

Deploy to production, switch DNS, and monitor for 2 weeks. Watch Google Search Console for crawl errors, verify analytics traffic matches pre-migration levels, test all forms and integrations daily, and run weekly Lighthouse audits.

Tip: Schedule the launch mid-week during a low-traffic period. Keep the old WordPress site accessible as a fallback for 2 weeks.

WordPress PHP Template

1<?php
2/**
3 * Template: Single Blog Post
4 */
5get_header();
6$categories = get_the_category();
7$featured = get_the_post_thumbnail_url(get_the_ID(), 'large');
8?>
9
10<article class="post-single">
11  <?php if ($featured): ?>
12    <div class="post-hero"
13         style="background-image: url(<?php echo esc_url($featured); ?>)">
14      <div class="post-hero__overlay">
15        <h1 class="post-hero__title">
16          <?php the_title(); ?>
17        </h1>
18        <div class="post-hero__meta">
19          <span><?php echo get_the_date(); ?></span>
20          <?php if ($categories): ?>
21            <span><?php echo esc_html($categories[0]->name); ?></span>
22          <?php endif; ?>
23        </div>
24      </div>
25    </div>
26  <?php endif; ?>
27
28  <div class="post-content">
29    <?php the_content(); ?>
30  </div>
31
32  <div class="post-author">
33    <?php echo get_avatar(get_the_author_meta('email'), 64); ?>
34    <div class="post-author__info">
35      <span class="post-author__name">
36        <?php the_author(); ?>
37      </span>
38      <span class="post-author__bio">
39        <?php echo get_the_author_meta('description'); ?>
40      </span>
41    </div>
42  </div>
43</article>
44
45<?php get_footer(); ?>

Next.js React Component

1import Image from 'next/image'
2import { formatDate } from '@/lib/utils'
3import type { Post } from '@/payload-types'
4
5interface BlogPostProps {
6  post: Post
7}
8
9export default function BlogPost({ post }: BlogPostProps) {
10  const category = post.categories?.[0]
11
12  return (
13    <article className="max-w-3xl mx-auto px-4 py-12">
14      {post.featuredImage && (
15        <div className="relative h-[400px] rounded-2xl overflow-hidden mb-8">
16          <Image
17            src={post.featuredImage.url}
18            alt={post.featuredImage.alt || post.title}
19            fill
20            className="object-cover"
21            priority
22          />
23          <div className="absolute inset-0 bg-gradient-to-t
24                          from-black/70 to-transparent" />
25          <div className="absolute bottom-0 p-8">
26            <h1 className="text-3xl font-bold text-white mb-3">
27              {post.title}
28            </h1>
29            <div className="flex gap-3 text-sm text-white/70">
30              <span>{formatDate(post.publishedAt)}</span>
31              {category && (
32                <span className="bg-cyan-500/20 text-cyan-300
33                                 px-2 py-0.5 rounded">
34                  {category.name}
35                </span>
36              )}
37            </div>
38          </div>
39        </div>
40      )}
41
42      <div className="prose prose-invert prose-lg max-w-none">
43        <RichText content={post.content} />
44      </div>
45
46      {post.author && (
47        <div className="flex items-center gap-4 mt-12
48                        pt-8 border-t border-white/10">
49          <Image
50            src={post.author.avatar?.url || '/default-avatar.png'}
51            alt={post.author.name}
52            width={64}
53            height={64}
54            className="rounded-full"
55          />
56          <div>
57            <p className="font-semibold text-white">
58              {post.author.name}
59            </p>
60            <p className="text-sm text-white/60">
61              {post.author.bio}
62            </p>
63          </div>
64        </div>
65      )}
66    </article>
67  )
68}

Feature	WordPress	Next.js
Page load time	4.2s average	0.8s average
Lighthouse Performance	40-60 typical	95-100 typical
Monthly hosting cost	$30-200/mo (managed)	$0-20/mo
Security maintenance	Constant (plugins, core, PHP)	Minimal (static files, no plugins)
AI editability	Very limited (PHP, plugin hooks)	Fully AI-editable (React, TypeScript)
Content editing	Gutenberg / WP Admin	Headless CMS (Payload, Sanity)
Plugin ecosystem	60,000+ WordPress plugins	npm ecosystem + custom code
Learning curve	Low for non-developers	Higher (but AI lowers it significantly)

Honest Trade-offs of Migrating to Next.js

Pros

+Page loads drop from 4+ seconds to under 1 second
+Monthly costs drop from $100-300 to $0-20
+AI tools can edit, maintain, and deploy the codebase
+Zero plugin vulnerabilities — minimal security surface
+Full code ownership in a Git repository
+Modern developer experience (React, TypeScript, Tailwind)
+SEO improves with better Core Web Vitals

Cons

-One-time migration cost of $2,000-8,000
-Content team needs to learn a new CMS interface
-WooCommerce stores add significant migration complexity
-Loss of access to WordPress plugin marketplace
-Niche WordPress-only features may need custom development
-Short learning curve for AI editing tools

Ready to migrate from WordPress to Next.js?

We'll audit your WordPress site, map the migration path, and give you a clear estimate — timeline, cost, and expected results. Free consultation, no obligation.

Get a free migration plan