Migrate Your WordPress Site to Astro

WordPress powers 43% of the web, but a growing number of developers and businesses are choosing to leave it behind. The reasons vary — performance, security, maintenance burden, cost — but the destination is increasingly the same: a modern static-site framework. And for content-driven websites, Astro has emerged as the leading choice.

This guide covers everything you need to know about migrating a WordPress site to Astro: why Astro specifically, what the migration actually involves, the different ways to do it, and the gotchas you will hit along the way.

Why Astro specifically?

There are dozens of static-site generators and JavaScript frameworks. Before diving into migration mechanics, it is worth understanding what makes Astro different and why it has become the default recommendation for WordPress migrations.

Zero JavaScript by default

Astro’s defining feature is its output: pure HTML and CSS with no JavaScript unless you explicitly add it. Every page is pre-rendered at build time into static HTML files. This is the opposite of frameworks like Next.js or Remix, which ship a React runtime to every page even when the page is entirely static content.

For a WordPress site that is fundamentally a collection of pages and blog posts, this matters enormously. You are replacing a PHP/MySQL stack with plain HTML files, and nothing more. The result is Lighthouse scores of 95-100 consistently, Time to First Byte under 50ms, and page loads under a second on mobile.

Content collections

Astro has a built-in content layer that maps directly to how WordPress organizes content. You define a collection schema in a config file, then create markdown or MDX files that match that schema:

src/content/
  blog/
    my-first-post.md
    another-post.md
  pages/
    about.md
    services.md
  config.ts   # defines schemas with Zod validation

Each markdown file has frontmatter (title, date, excerpt, featured image, categories, tags) that maps almost one-to-one with WordPress post metadata. Astro validates this frontmatter at build time, so you catch errors before deployment rather than discovering broken pages in production.

Island architecture

When you do need interactivity — a contact form, an image carousel, a search widget — Astro uses “islands.” You can drop a React, Vue, Svelte, or Preact component into an otherwise static page, and Astro will hydrate only that component. The rest of the page stays as zero-JS HTML.

This is ideal for WordPress migrations because most WordPress sites are 95% static content with a few interactive elements (forms, sliders, accordions). You don’t need to rewrite those in vanilla JS or ship a full framework runtime. Just island the interactive parts.

How it compares to other frameworks

Next.js: More powerful for interactive applications, but ships React to every page. Overkill for most content sites. Better choice if you need authentication, server-side logic, or app-like features.
Hugo: Extremely fast builds, but uses Go templates which have a steep learning curve. No component model, no island architecture.
11ty (Eleventy): Flexible and minimal, but less opinionated — you make more decisions yourself. No built-in content validation.
Gatsby: Largely abandoned by its maintainers. Not recommended for new projects.
SvelteKit: Good framework, but like Next.js, designed more for interactive apps than pure content sites.

Astro occupies a specific niche: content-driven websites where performance matters and JavaScript should be minimal. That is exactly what most WordPress sites are.

What does a WordPress-to-Astro migration actually involve?

Before choosing a migration approach, it helps to understand what the migration entails at a technical level. It is not just “export content and import it somewhere else.”

Content extraction

WordPress stores content in a MySQL database. Blog posts and pages are stored in the wp_posts table, with content as HTML (and if you use Gutenberg, as HTML with embedded block comments like ). You need to extract this content and convert it to markdown files with proper frontmatter.

The WordPress REST API (/wp-json/wp/v2/posts, /wp-json/wp/v2/pages) is often the easiest extraction path — most WordPress sites have it enabled by default. You can also use the built-in XML export (Tools > Export in wp-admin), which gives you a WXR file containing all posts, pages, comments, and metadata.

Gutenberg block conversion

If the WordPress site uses the Gutenberg block editor (default since WordPress 5.0), post content contains block markup like:

<!-- wp:heading {"level":2} -->
<h2>Section Title</h2>
<!-- wp:heading -->

<!-- wp:image {"id":42,"sizeSlug":"large"} -->
<figure class="wp-block-image size-large">
  <img src="/wp-content/uploads/2024/hero.jpg" alt="Hero" />
</figure>
<!-- /wp:image -->

This needs to be converted to clean markdown or Astro components. Simple blocks (paragraphs, headings, lists, images) convert cleanly. Complex blocks (columns, galleries, custom blocks from plugins) require more work and may need custom Astro components.

Images and media

WordPress stores uploaded images in /wp-content/uploads/YYYY/MM/ and generates multiple sizes (thumbnail, medium, large, full). You need to download the images, decide which sizes to keep, and update all references in your content. WordPress also lazy-loads images with various techniques — data-src, data-lazy-src, srcset attributes — that you need to handle during extraction.

URL structure and redirects

WordPress uses URL patterns like /2024/03/my-post/ or /my-post/ depending on permalink settings. Your Astro site needs to either match these URLs exactly (to preserve SEO) or set up 301 redirects from old URLs to new ones. Missing this step means broken links, lost search rankings, and 404 errors for anyone who bookmarked or linked to your old pages.

Plugin functionality replacement

Every WordPress plugin your site uses represents functionality you need to replace:

Contact forms (Contact Form 7, WPForms, Gravity Forms) — Replace with Formspree, Netlify Forms, or a custom form handler
SEO (Yoast, RankMath) — Port meta titles, descriptions, and Open Graph tags to Astro frontmatter and <head> tags. Note that Yoast and RankMath store metadata in custom wp_postmeta fields, not in the post content
Analytics (Google Analytics, MonsterInsights) — Add the tracking snippet to your Astro layout
Image optimization (Smush, ShortPixel) — Astro has built-in image optimization with astro:assets
Caching (WP Super Cache, W3 Total Cache) — Not needed; static files are inherently cached
Security (Wordfence, Sucuri) — Not needed; no server-side attack surface

Custom post types and ACF fields

If your WordPress site uses custom post types (e.g., “Projects,” “Testimonials,” “Team Members”) or Advanced Custom Fields, these need to be mapped to Astro content collections with appropriate schemas. ACF fields are stored in wp_postmeta and won’t appear in a standard XML export — you will need the REST API or a plugin like ACF to REST API to extract them.

WooCommerce and membership content

If your site has WooCommerce or membership functionality, a static site migration is more complex. Product catalogs can be migrated to static pages, but checkout flows, inventory management, and user accounts need a different solution (Shopify, Stripe, or a separate backend). This is an area where WordPress may genuinely be the better choice — see “When not to migrate” below.

How to migrate: six approaches

There is no single right way to do this. The best approach depends on your technical skills, budget, timeline, and how complex your WordPress site is.

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

AI coding agents like Claude Code, Cursor, Windsurf, and Cline are the most broadly useful migration approach. These tools can read files, write code, run terminal commands, and iterate on errors — essentially acting as a junior developer who works very fast.

How it works step by step:

Export your WordPress content. Use the built-in XML export (Tools > Export in wp-admin) or pull content from the REST API. For REST API extraction, you can ask the AI agent to write a script: “Write a Node.js script that fetches all posts and pages from my WordPress REST API at example.com and saves them as markdown files with frontmatter.”
Scaffold the Astro project. Ask the agent to create a new Astro project and set up the structure: “Create a new Astro project with content collections for blog posts and pages. Use Tailwind CSS for styling.”
Convert content. Point the agent at your exported content: “Convert these WordPress XML posts into markdown files in src/content/blog/. Preserve the title, date, excerpt, categories, tags, and featured image as frontmatter.”
Build layouts and components. Share your current WordPress site URL or screenshots: “Look at example.com and recreate the header, footer, and page layout as Astro components.” The agent can inspect the live site’s HTML/CSS and reproduce it.
Handle images. “Download all images referenced in these markdown files from the WordPress site and save them to public/images/. Update the markdown references.”
Set up deployment. “Add a Cloudflare Pages deployment config” or “Set up Vercel deployment.”

Real-world examples:

cursor.com migrated their website from Sanity CMS to code + Markdown in 3 days for $260 in AI tokens. Their CMS had been costing $56,848/year in CDN costs. (Source)
Sid Bharath migrated his WordPress blog to Astro + Cloudflare Pages in 3 hours using Claude Code. PageSpeed went from 67 to 100, LCP from 7.2s to 0.5s, monthly hosting from $20 to $0. (Source)
Prefect.io rebuilt their entire website from CMS to code in 1 week (estimated 6 weeks). New landing pages now ship in 30 minutes instead of 2 weeks. (Source)

Claude Code is particularly good for migrations because it can run terminal commands directly — it can npm create astro@latest, install dependencies, run builds to check for errors, and fix issues in a loop. Cursor and Windsurf are better if you prefer a visual IDE experience where you can watch the code being written.

Cost: $20/month for Claude Code or Cursor subscription, plus API token costs ($5-$300 depending on site complexity). A typical blog migration uses $10-50 in tokens.

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

If you are not a developer, tools like Bolt.new, v0.dev, Lovable, and Replit Agent let you describe or show what you want and get a working site.

The approach: take screenshots of your WordPress site, paste them into the app builder, and say “Recreate this site as a static Astro site.” These tools can generate surprisingly complete sites from visual references. You can then iterate: “Move the navigation to the left,” “Add a blog section,” “Change the color scheme.”

Trade-offs: Less control over code quality, may need multiple rounds of iteration, and the generated code can be harder to maintain long-term. But for a simple marketing site or portfolio, this can work well and requires zero coding knowledge.

3. Hire a developer or agency (hands-off — days to weeks)

If you want someone else to handle the migration entirely, this is a legitimate option that many businesses choose.

Freelancers (Upwork, Toptal, Fiverr): $500-$5,000 for a simple site, depending on complexity and the developer’s rate. Many freelancers now use AI tools themselves, which has driven timelines down from weeks to days.
Agencies: $5,000-$25,000 for complex sites with custom functionality, e-commerce data migration, or enterprise requirements.

When hiring, look for developers with Astro experience specifically. The framework is popular enough now that you can find specialists. Ask for examples of previous WordPress-to-Astro migrations.

4. Automated migration tools

Several tools automate parts or all of the migration process. BrowserCat Migrate is one such tool — paste your WordPress URL and it handles content extraction, Astro project scaffolding, image downloading, and deployment. Other automated approaches exist for different parts of the pipeline.

5. WordPress-specific export tools

These tools handle content extraction specifically, leaving the Astro project setup to you:

wp2md: Converts WordPress XML export to markdown files. Good for blog posts, less useful for complex pages.
Simply Static / WP2Static: WordPress plugins that export your entire site as static HTML. The output is a snapshot, not a maintainable codebase — useful as a reference but not a final solution.
WordPress REST API: Programmatic access to all your content. Most flexible extraction method, especially for custom post types and ACF fields.
WordPress XML Export: Built-in export (Tools > Export). Simple but loses some metadata.
wordpress-export-to-markdown: Converts WordPress XML to markdown with frontmatter, downloads images, and preserves directory structure. One of the better automated converters.

6. Manual migration (full control — weeks)

If you want to understand every piece of your new site, manual migration gives you that:

Export WordPress content as XML or via REST API
Set up a new Astro project: npm create astro@latest
Define content collection schemas in src/content/config.ts
Convert posts to markdown files with proper frontmatter
Build Astro layouts and components matching your WordPress theme
Download and organize images from wp-content/uploads
Set up URL redirects for any changed paths
Replace plugin functionality (forms, analytics, etc.)
Test thoroughly, especially on mobile
Deploy to Cloudflare Pages, Vercel, or Netlify

This approach takes 2-6 weeks for a typical site. It is the most time-consuming but gives you complete understanding and control over every decision.

SEO considerations

Search rankings are the thing people worry about most during a migration, and rightfully so. A botched migration can tank your organic traffic overnight.

What you must preserve:

URL structure — match old URLs exactly, or set up 301 redirects for every changed URL
Page titles and meta descriptions — port these from Yoast/RankMath to Astro frontmatter
Open Graph and Twitter Card tags
Canonical URLs
XML sitemap (Astro has sitemap integration: @astrojs/sitemap)
robots.txt
Structured data / JSON-LD (if you were using it)

What usually improves:

Core Web Vitals — Astro sites consistently pass CWV, which is a ranking factor. Only about 43% of WordPress sites pass on mobile
Page speed — faster sites get a ranking boost
Mobile performance — the biggest improvement area

The Google guidance: Google’s documentation on site migrations recommends launching the new site, keeping the old site running temporarily, monitoring Search Console for crawl errors, and submitting the new sitemap. Expect a temporary dip in rankings (1-4 weeks) as Google re-crawls and re-indexes.

Post-migration: what daily life looks like

One of the biggest adjustments after leaving WordPress is the editing workflow. There is no wp-admin. Here is what content editing looks like with an Astro site:

Adding a blog post:

Create a new markdown file in src/content/blog/
Add frontmatter (title, date, excerpt, image)
Write content in markdown
Commit and push to GitHub
Site deploys automatically in 30-60 seconds

Editing existing content:

Open the markdown file in any text editor, VS Code, or directly on GitHub.com
Make changes, commit, push — deployed in under a minute
Or tell an AI agent: “Update the pricing on the services page to reflect the new rates”

For non-technical team members:
If your team is used to wp-admin and cannot work with Git, you have options:

Decap CMS (formerly Netlify CMS): free, open-source CMS that creates a wp-admin-like editing interface backed by Git
Tina CMS: visual editing with live preview, backed by Git
Sanity / Contentful / Strapi: headless CMS options if you need a more traditional editing experience
GitHub.com’s web editor: simple enough for non-developers to edit markdown files directly

When NOT to migrate

Astro is not the right choice for every WordPress site. Be honest with yourself about these scenarios:

WooCommerce stores with active e-commerce — product catalogs can go static, but checkout/inventory/accounts need a backend. Consider Shopify instead, or keep WordPress for e-commerce.
Membership sites with user accounts, gated content, and subscription management — these need server-side logic. WordPress with a membership plugin may genuinely be simpler.
Sites updated many times per day by non-technical teams — if your content team publishes 20 articles a day and needs a visual editor, the Git-based workflow may be too much friction without a headless CMS layer.
Sites heavily dependent on specific WordPress plugins with no equivalent — some niche plugins (real estate IDX, LMS platforms, complex booking systems) have deep functionality that is expensive to replicate.
Multisite installations — WordPress multisite adds significant complexity to migration. Each sub-site needs individual handling.

WordPress is a mature, capable platform. It has problems — performance, security, maintenance cost — but it also has a massive ecosystem and 20 years of battle-tested solutions. Migrating only makes sense if the benefits outweigh the effort for your specific situation.

Decision framework: which migration approach is right for you?

Your situation	Recommended approach
Developer comfortable with CLI tools	AI coding agent (Claude Code, Cursor)
Non-developer, simple site	AI app builder (Bolt.new, Lovable)
Business with budget, want hands-off	Hire a developer or agency
Complex site, need full control	Manual migration or AI agent + manual review
Simple blog, want it done fast	Automated tool or AI agent
Enterprise site, compliance requirements	Agency + manual QA

The honest recommendation for most people: start with an AI coding agent. The cost is low ($20/month subscription + $10-50 in tokens), the speed is fast (hours to days), and you end up with code you fully own and understand. If you get stuck, you can always hand the partially-complete project to a developer to finish.