What is WordPress to Next.js Migration?
WordPress to Next.js migration is the process of moving a WordPress site to a Next.js frontend, often retaining WordPress as a headless CMS.
What is WordPress to Next.js Migration?
WordPress to Next.js migration is replacing your WordPress theme frontend with a Next.js app while keeping WordPress as a headless CMS (via REST API or WPGraphQL). You're rebuilding templates in React, mapping every URL to preserve SEO, and moving from LAMP/PHP hosting to Node.js infrastructure like Vercel or AWS. Since Next.js 13.4 (May 2023) stabilized the App Router, most migrations now use React Server Components for data fetching. Sites that do this right see Largest Contentful Paint drop from 3-4s to under 1.5s — static generation and edge caching beat PHP rendering every time. We've shipped this on 50+ projects. The trigger's usually a content-heavy marketing site that's outgrown its theme and needs programmatic page generation at scale.
How it works
The migration breaks into five phases:
1. Content audit and URL mapping
Crawl the existing WordPress site (we use Screaming Frog or wget --spider) and generate a complete URL inventory. Every URL gets a destination in Next.js or a 301 redirect entry. This redirect map is the single most important SEO artifact in the migration.
2. API layer setup
Install WPGraphQL (v1.x+) or use the built-in WP REST API (/wp-json/wp/v2/). WPGraphQL's our preferred approach — it lets you query only the fields you need, reducing payload size by 40-70% compared to the REST API's default responses.
3. Next.js app scaffold
Build the Next.js project using the App Router. Each WordPress content type (posts, pages, custom post types) gets a corresponding dynamic route:
// app/blog/[slug]/page.tsx
import { getPostBySlug } from '@/lib/wp-client';
export async function generateStaticParams() {
const posts = await getAllPostSlugs();
return posts.map((slug) => ({ slug }));
}
export default async function BlogPost({ params }: { params: { slug: string } }) {
const post = await getPostBySlug(params.slug);
return <Article content={post.content} />;
}
4. Redirect implementation
All legacy URLs that change structure need 301 redirects in next.config.js or middleware. For sites with thousands of redirects, we use middleware with a lookup map loaded from a JSON file or KV store.
5. DNS cutover and verification
Switch DNS, verify redirects with a crawler, and monitor Google Search Console for coverage errors over the following 2-4 weeks.
When to use it
This migration makes sense in specific situations. It's overkill in others.
Migrate when:
- Your WordPress site has 500+ pages and needs programmatic page generation (location pages, product pages, that sort of thing)
- Page speed's a business metric and your current theme scores below 50 on Lighthouse performance
- Your engineering team already works in React/TypeScript
- You need to serve content from the edge globally
- You're pulling in non-WordPress data sources (APIs, databases, commerce platforms)
Don't migrate when:
- You've got a 20-page brochure site — a good WordPress theme or even a simple Astro site is way cheaper
- Your content editors rely heavily on Gutenberg's visual editing and aren't willing to adopt a different authoring experience
- You don't have engineering resources to maintain a JavaScript frontend long-term
- SEO's your primary traffic channel and you can't afford any temporary ranking fluctuation
WordPress to Next.js vs alternatives
| Factor | WP → Next.js | WP → Astro | WP → Remix | Full CMS migration (e.g., to Sanity + Next.js) |
|---|---|---|---|---|
| Content authoring | WordPress admin stays | WordPress admin stays | WordPress admin stays | New CMS, new training |
| Framework complexity | High (RSC, hydration) | Low (islands, zero JS default) | Medium (loaders, actions) | High |
| Best for | App-like sites, dashboards, heavy interactivity | Content-heavy, blog/docs | Form-heavy, authenticated pages | Greenfield rebuilds |
| Build times (10k pages) | ~2-5 min (ISR avoids full rebuilds) | ~3-8 min (static) | N/A (SSR) | Depends on CMS |
| Our recommendation | Default choice for React teams | Great for content sites with minimal JS | Niche, fewer WP integrations | Only if you're abandoning WP entirely |
Our preferred stack for most migrations is Next.js 14+ on Vercel with WPGraphQL and incremental static regeneration (ISR) set to 60-second revalidation intervals.
Real-world example
A B2B SaaS company with 3,200 WordPress blog posts and 400 programmatic landing pages was seeing 3.8s LCP on mobile and losing Core Web Vitals assessments in Search Console. We migrated their frontend to Next.js 14 on Vercel, kept WordPress as the headless CMS with WPGraphQL, and implemented a redirect map of 1,847 URL changes. Post-migration, mobile LCP dropped to 1.1s, CLS stayed under 0.05, and organic traffic recovered to pre-migration levels within 18 days. The redirect map was the critical piece — we caught 200+ orphaned URLs during the audit that would've become soft 404s. Total project timeline was 10 weeks with a team of two engineers.