Migrate Your WordPress Site to Next.js

If you are considering migrating your WordPress site to a modern JavaScript framework, Next.js is probably on your list. It is the most popular React framework, backed by Vercel, and used by companies from Netflix to the Washington Post. But “popular” and “right for your project” are not the same thing.

This guide gives you an honest breakdown of when Next.js is the right migration target, when a different framework makes more sense, and how to actually execute the migration regardless of which direction you choose.

The honest framework comparison

The JavaScript framework ecosystem is large, and each option has genuine strengths. Here is how they compare for a WordPress migration specifically:

Next.js

What it is: A React-based framework with server-side rendering (SSR), static site generation (SSG), incremental static regeneration (ISR), API routes, middleware, and server actions. It is a full-stack framework that can handle everything from static marketing pages to complex web applications.

Best for:

Sites that need authentication (user accounts, member areas, dashboards)
Applications with significant client-side interactivity (real-time features, complex forms, data-heavy dashboards)
Sites that need API routes or server-side logic
Teams already proficient in React
Projects where part of the site is static content and part is a dynamic application

Trade-offs:

Ships React runtime JavaScript to every page, even pages that are purely static content. This affects Lighthouse scores — typically 80-95 versus 95-100 for static-only frameworks.
More complex to configure than content-focused frameworks. The App Router, server components, client components, layout files, and loading states have a learning curve.
Hosting is more expensive if you use SSR features. Vercel’s free tier is generous, but serverless function invocations add up at scale ($0-20/month for small to medium sites, potentially more for high-traffic sites with SSR).
Vercel lock-in is real but avoidable. Next.js can be self-hosted or deployed to other platforms, but some features (middleware, ISR, image optimization) work best on Vercel.

Astro

What it is: A web framework purpose-built for content-driven websites. Ships zero JavaScript by default. Pages are pre-rendered as static HTML at build time.

Best for:

Content sites: blogs, marketing pages, documentation, portfolios, business homepages
Sites where performance is the top priority
Projects where most or all pages are static content
Teams that want the simplest possible architecture

Trade-offs:

Not designed for highly interactive applications. You can add React/Vue/Svelte components as “islands” for interactive sections, but if your entire site is interactive, Astro is the wrong tool.
Younger ecosystem than Next.js. Fewer tutorials, blog posts, and Stack Overflow answers (though the community is growing rapidly).

For most WordPress migrations — blogs, marketing sites, business sites — Astro is the better target. WordPress sites are overwhelmingly content-driven, and Astro is purpose-built for that use case. It has built-in content collections that map directly to WordPress’s post/page model, and the performance improvement (zero JS shipped) is significant.

Other options worth considering

SvelteKit: Svelte-based framework with excellent performance. Good middle ground between Next.js and Astro — can do both static and dynamic well. Smaller ecosystem than Next.js but growing.
Remix: React-based but with a different philosophy than Next.js. Focuses on web fundamentals (forms, HTTP caching). Good for sites that need progressive enhancement.
Hugo: Not JavaScript-based (Go), but the fastest build times of any static site generator. Good for very large sites (10,000+ pages) where build time matters.
11ty (Eleventy): Minimal, flexible, uses familiar template languages. Good if you want maximum control with minimal framework overhead.

When Next.js is genuinely the right choice

Choose Next.js over Astro or other static frameworks when your site needs:

Authentication and user accounts

If your WordPress site has membership areas, user dashboards, or gated content, Next.js handles this natively. The App Router supports server-side authentication checks, session management, and role-based access control. Libraries like NextAuth.js (now Auth.js) provide OAuth, credentials-based auth, and session management with minimal setup.

A static framework like Astro can add authentication through external services (Auth0, Clerk, Supabase Auth), but the integration is less seamless than Next.js where authentication is a first-class concern.

API routes and server-side logic

If your WordPress site uses plugins that process data on the server — advanced form handling, payment processing, webhook receivers, integrations with external services — Next.js can replace that server-side logic with API routes in the same codebase.

For example, a WordPress site that uses Gravity Forms with conditional logic and CRM integration might need a server endpoint to process submissions. In Next.js, you create an API route at app/api/contact/route.ts that handles the processing. In a static framework, you need an external service or separate backend.

Complex client-side interactivity

If your WordPress site has (or needs) rich interactive features — data visualization dashboards, real-time notifications, complex multi-step forms, interactive product configurators — Next.js’s React foundation handles this naturally. Astro can host React components as islands, but if most of your site is interactive rather than static, Next.js is the simpler architecture.

The marketing site + application combo

Some WordPress sites are actually two things: a marketing site (homepage, about, pricing, blog) and a web application (dashboard, settings, user-facing tools). Next.js can serve both from a single codebase. The marketing pages can be statically generated for performance, while the application pages use SSR for dynamic content.

The headless WordPress option (and its trade-offs)

Before committing to a full migration, consider the headless WordPress approach: keep WordPress as your CMS backend and use Next.js (or Astro) as the frontend.

How it works: WordPress becomes a content API. You install a plugin like WPGraphQL or use the built-in REST API. Your Next.js frontend fetches content from the WordPress API at build time (for static pages) or at request time (for dynamic pages).

When this makes sense:

Your content team is deeply invested in wp-admin and cannot transition to a different editing workflow
You have complex content models (custom post types, ACF fields, custom taxonomies) that would be expensive to replicate in markdown
You need the WordPress editor’s rich formatting capabilities
You are migrating incrementally and want to decouple frontend from backend first

When this does not make sense:

Your content is relatively simple (blog posts, pages) — markdown files in a Git repo are simpler and free
You want to eliminate WordPress entirely for cost and maintenance reasons
You want a simpler architecture — headless WordPress means maintaining two systems (WordPress backend + Next.js frontend)
Budget is a concern — you still need WordPress hosting ($25-$300/month), plus hosting for the Next.js frontend

The headless approach is a legitimate intermediate step. Many teams go headless first, then gradually move content from WordPress to markdown as they get comfortable with the new frontend. Eventually, WordPress is decommissioned entirely.

If your content does not change hourly and your team can learn a markdown-based workflow, going directly to a fully static site (no WordPress backend) is simpler, cheaper, and easier to maintain.

How to migrate: your options

1. AI coding agents (most flexible — hours to days)

AI coding agents like Claude Code, Cursor, Windsurf, and Cline are the most effective way to migrate a WordPress site to Next.js or Astro. They can scaffold the project, convert content, build React or Astro components, and iterate on errors.

For a Next.js migration specifically:

Export WordPress content (XML export or REST API)
Tell the agent: “Create a Next.js App Router project from this WordPress export. Use the App Router with static generation for blog posts. Convert posts to MDX.”
The agent creates the directory structure: app/, app/blog/[slug]/, app/api/, components/, content/
It converts WordPress posts to MDX files with frontmatter
It builds React layout components matching your current design
It sets up next.config.js with MDX support and image optimization
For headless WordPress: it creates data fetching functions that pull from your WordPress REST API or WPGraphQL endpoint

For an Astro migration:

Same content export
“Create an Astro project with content collections for blog posts and pages. Zero JS. Tailwind for styling.”
The agent creates src/content/, src/pages/, src/components/, src/layouts/
Blog posts become markdown files in content collections with Zod schema validation
Pages become .astro files or markdown

Real-world examples:

cursor.com migrated from Sanity CMS to code + Markdown in 3 days for $260 in AI tokens. CDN costs dropped from $56,848/year to near-zero. (Source)
Sid Bharath migrated his WordPress blog to Astro in 3 hours using Claude Code. PageSpeed went from 67 to 100, LCP from 7.2s to 0.5s. (Source)
Prefect.io rebuilt their CMS-based website as code in 1 week instead of the estimated 6 weeks. (Source)

Cost: $20/month subscription + API tokens. A blog migration typically uses $10-50 in tokens. Complex sites with many pages and interactive features may cost $100-300.

2. AI app builders (for non-developers — hours)

Bolt.new, v0.dev, Lovable, and Replit Agent can generate Next.js or Astro projects from descriptions and screenshots. v0.dev is particularly well-suited for Next.js since it is built by Vercel and generates React/Next.js code natively.

Screenshot your WordPress pages, paste them into the tool, describe what you want. Iterate until you are satisfied. These tools are improving rapidly but may produce code that needs cleanup for production use.

3. Hire a developer or agency

Freelancers on Upwork charge $500-$5,000 for a Next.js or Astro migration, depending on complexity. Agencies charge $5,000-$25,000 for complex sites. When hiring for a Next.js migration specifically, look for developers with App Router experience (not just the legacy Pages Router). Many developers now use AI tools, which has shortened timelines significantly.

4. Automated migration tools

Tools like BrowserCat Migrate automate the end-to-end migration process. Some tools target Astro output by default since it is the natural fit for content sites; from an Astro codebase, you can add React components as islands if you need interactivity, or use the content and structure as a reference for building a Next.js version.

5. WordPress export tools

These handle content extraction:

WordPress REST API: /wp-json/wp/v2/posts, /wp-json/wp/v2/pages. Most flexible option, especially for custom post types. Works well for both Next.js (fetch at build time) and Astro.
WPGraphQL: GraphQL API for WordPress. More efficient than REST for fetching nested/related data. Commonly used with Next.js headless setups.
WordPress XML Export: Built-in export via Tools > Export. Good for a one-time full migration.
wordpress-export-to-markdown: Converts XML to markdown/MDX with frontmatter.

6. Manual migration

To Next.js (App Router):

npx create-next-app@latest my-site --typescript --tailwind --app
Create MDX content in content/blog/
Set up @next/mdx or use contentlayer2 / velite for content management
Build React components for layouts (app/layout.tsx, page templates)
Create dynamic routes: app/blog/[slug]/page.tsx
Add API routes if needed: app/api/contact/route.ts
Configure image optimization in next.config.js
Deploy to Vercel, Netlify, or self-host

To Astro:

npm create astro@latest
Define content collection schemas in src/content/config.ts
Create markdown files with frontmatter for blog posts and pages
Build Astro layouts and components
Deploy to Cloudflare Pages, Vercel, or Netlify (all have free tiers)

WordPress-specific migration challenges

Gutenberg block conversion

WordPress’s block editor stores content as HTML with comment markers: <h2>Title</h2>. Simple blocks (paragraphs, headings, lists, images) convert to markdown or MDX cleanly. Complex blocks (columns, galleries, custom blocks from plugins like Kadence or GenerateBlocks) need custom handling.

For Next.js, complex blocks can become React components. For Astro, they can become Astro components. Either way, you need to identify which blocks your site uses and plan the conversion for each one.

Plugin functionality mapping

Common WordPress plugins and their Next.js/Astro equivalents:

WordPress Plugin	Next.js Equivalent	Astro Equivalent
Yoast SEO	next-seo, custom `<head>` in layout	astro-seo, frontmatter meta
Contact Form 7	API route + form, or Formspree	Formspree, Netlify Forms
WooCommerce	Snipcart, Shopify Buy Button, custom with Stripe	Same options
Wordfence	Not needed (no server to protect)	Not needed
WP Super Cache	Not needed (SSG is pre-cached)	Not needed
MonsterInsights	Google Analytics script in layout	Same
TablePress	React table component	HTML tables or component
Advanced Custom Fields	MDX frontmatter + custom components	Content collection schemas

Image handling

WordPress generates multiple image sizes and uses lazy loading with various techniques (data-src, data-lazy-src, srcset). Both Next.js and Astro have built-in image optimization:

Next.js: next/image component handles lazy loading, responsive sizes, and format conversion (WebP/AVIF). Works with both local and remote images.
Astro: astro:assets with the <Image /> component. Optimizes at build time. Zero JS overhead.

Download the full-size originals from WordPress and let the framework handle optimization. This usually produces better results than keeping WordPress’s pre-generated sizes.

SEO preservation

Both Next.js and Astro support all the SEO features you need:

Meta tags in <head> (titles, descriptions, Open Graph, Twitter Cards)
XML sitemaps (next-sitemap for Next.js, @astrojs/sitemap for Astro)
Canonical URLs
Structured data / JSON-LD
robots.txt

The critical step is preserving URL structure. If your WordPress permalinks are /2024/03/my-post/, your new site needs either the same URL pattern or 301 redirects from every old URL to the new one. Both frameworks support URL rewrites and redirects in their configuration.

WooCommerce data

If you have a WooCommerce store, a full migration to Next.js or Astro is more complex:

Product catalogs can become static pages (good for SEO)
Checkout, cart, inventory need a separate solution: Shopify, Snipcart, Stripe, or a custom backend
Order history and customer accounts need a backend database
Consider headless WordPress for the commerce backend while using Next.js or Astro for the frontend

For simple stores (under 50 products, no inventory management), Snipcart or Shopify’s Buy Button can replace WooCommerce entirely. For complex stores, Shopify or a custom solution is more appropriate than trying to replicate WooCommerce in a static site.

Post-migration: editing content

With Next.js

Content editing depends on your content strategy:

MDX files in the repo: Edit in VS Code or any editor, commit and push. Site rebuilds on Vercel in 30-60 seconds.
Headless CMS (Sanity, Contentful, Strapi): Edit in the CMS dashboard. Webhook triggers a rebuild.
Headless WordPress: Edit in wp-admin. Webhook triggers a rebuild.

For non-technical editors, the headless CMS route provides the most familiar experience.

With Astro

Markdown files: Edit locally or on GitHub, commit and push. Deploy in 30-60 seconds.
Decap CMS / Tina CMS: Visual editor backed by Git. Non-technical users get a familiar editing experience.
Headless CMS: Same as Next.js — edit in the CMS, webhook triggers rebuild.

Making the decision

Your situation	Recommendation
Content site (blog, marketing, portfolio)	Astro
Content site + some interactive features	Astro with React islands
Web application with user accounts	Next.js
Marketing site + separate web app	Astro for marketing, Next.js for app (or Next.js for both)
Complex e-commerce	Shopify or headless WordPress + Next.js
Team only knows React	Next.js
Performance is the #1 priority	Astro
Need server-side logic (API routes, auth)	Next.js or SvelteKit

The most common mistake is choosing Next.js for a site that is purely content. Next.js is powerful, but that power comes with complexity and JavaScript overhead that content sites do not need. If your WordPress site is a blog, a marketing site, or a business homepage, start with Astro. You can always add React islands for interactive sections, and if you later need full Next.js capabilities, the content (markdown files) transfers directly.