Migrating from WordPress to Astro: a step-by-step guide.

Your WordPress site is slow. You know it. Your visitors know it too — and Google figures it out faster than any of them. The question is no longer why, but how to get out without breaking your search rankings.

We cover the complete migration here: content export, rebuilding in Astro, SEO preservation, and choosing a replacement CMS. No theory — concrete steps, real numbers, and the pitfalls nobody mentions.

What you will lose (and gain)

Let’s be honest: migrating from WordPress to Astro is not just changing engines. It’s changing philosophy.

What you lose:

• The Gutenberg visual editor (replaced by a headless CMS)
• All-in-one plugins (forms, SEO, cache, galleries)
• The WordPress support community (though Astro is growing fast)

What you gain:

• A site that loads in under one second — by design, not by optimisation
• Zero JavaScript shipped to the browser by default
• No server to maintain, no plugins to update
• A monthly infrastructure cost of EUR 0
• Full ownership of your code (in your Git repository)

The question is not “is it better?”. It’s “is it better for your case?”. We come back to this at the end.

The numbers, not the promises

The results below consolidate six real, documented, sourced migrations. The Astro4B column reflects measurements on sites we delivered:

Sources: Kashif Aziz (2026), mfyz.com, Pascal Cescato (DEV.to), Kiwop Agency, Perel Web Studio, Devaradise.

A telling case: Kiwop Agency measured a +28% increase in organic click-through rate (CTR) and a Lighthouse score of 97 after migrating to Astro + Payload CMS. Perel Web Studio saw +142% organic traffic within three months.

Before you start

Three conditions for a smooth migration: a complete backup, an inventory of existing URLs, and a list of redirects to set up. URLs are the only thing that can cost you rankings if handled poorly.

The 6 migration steps

This sequence is the one we apply on every migration project at Astro4B. Order matters: do not move to the next step without validating the previous one.

01

Audit

Analyse URLs, content structure, media, and existing redirects.

02

Export

WP XML + images via All-in-One WP Migration. List all slugs and SEO meta.

03

Rebuild

Create the Astro project, layouts, components, and convert content to Markdown.

04

Choose a CMS

Set up Decap CMS for autonomous editing — without touching code.

05

Redirects

Map every old URL, configure 301s in Cloudflare Pages.

06

Launch

Deploy on Cloudflare Pages, validate Lighthouse, submit to Google Search Console.

Step 1: audit before touching anything

The migration starts before the first line of code. Open Google Search Console and export your top 50 URLs by organic traffic. These are your critical pages — the ones where a redirect mistake costs real visitors.

Your audit checklist:

• Total number of published pages and posts
• Active plugins and their Astro equivalents (forms, analytics, search, comments)
• Custom fields (ACF, Custom Fields) — exporting them requires a dedicated script
• Current URL structure (date-based /2024/06/slug/ or flat /slug/)
• Yoast/Rank Math meta descriptions and titles (they are not in the standard export)

That last point is the most common trap. Meta descriptions live in the wp_postmeta table, not in the XML export file. If you lose them, you lose your Google snippets.

Step 2: export the content

Three methods, each with its strengths:

XML export + Markdown conversion — The most common. WordPress > Tools > Export generates a WXR file. The wordpress-export-to-markdown tool (npm) converts it to Markdown files with frontmatter. Fast, reliable, but captures neither ACF fields nor Yoast meta.

WordPress REST API — Query /wp-json/wp/v2/posts to retrieve posts with their complete metadata. More precise than XML export. Requires a custom script (Node.js + Turndown for HTML → Markdown conversion).

WPGraphQL — A single query for posts + categories + metadata, versus three REST calls. More efficient on large sites. The WPGraphQL v2 plugin (2026) reduces database queries by 60 to 80%.

For a site under 100 pages, the XML export is plenty. Beyond that, the REST API or WPGraphQL prevent oversights.

Images: download the entire wp-content/uploads/ folder. Reorganise it under public/images/ and rewrite the paths in your Markdown files. Astro’s <Image> component handles optimisation (WebP, responsive, anti-CLS) at build time.

Step 3: rebuild in Astro

Astro structures content through Content Collections: your posts are Markdown files in src/content/blog/, validated by a Zod schema at build time. A frontmatter error? The build fails. No surprises in production.

Each post has typed frontmatter:

title: "My article"
description: "The meta description, 160 characters max"
date: 2026-06-08
category: Migration
tags: [wordpress, astro]
readingTime: "8 min read"

What Astro does natively (no plugin):

• XML Sitemap (@astrojs/sitemap)
• RSS feed (@astrojs/rss)
• Image optimisation (astro:assets)
• Markdown and MDX support
• Pagination via paginate() in getStaticPaths()

What you need to add: a CMS for content editing (see next step), a client-side search engine (Pagefind), a comments system (Giscus), a contact form (Formspree or Web3Forms).

Step 4: the real question — who will edit the content?

WordPress has a visual editor. Astro has Markdown files. If your editorial team doesn’t know Git, you have a problem.

The answer: a headless CMS that plugs into Astro. The market is wide — here are the options by profile:

Decap CMS — Free, open-source, Git-based. The editor works in the browser, files are committed directly to the repository. Ideal for technical teams or blogs with few contributors. It’s our choice at Astro4B.

Storyblok — Visual editor close to WordPress, native Astro integration. Starting at EUR 99/month. The best compromise for teams used to a WYSIWYG editor.

Sanity — Fully customisable schemas, real-time collaboration. Free tier viable in production. For dev teams that want total control.

TinaCMS — Visual editor + Git-based. The best of both worlds, but still young.

The deciding criterion is simple: if your editors are technical (or willing to learn), Decap CMS. If they want to click like in WordPress, Storyblok.

Step 5: redirects — the real issue

This is where most migrations fail. Every URL that changes without a 301 redirect loses its Google authority. And URLs almost always change: WordPress often uses /2024/06/15/my-post/, Astro typically /blog/my-post/.

Redirects you must not forget:

• Every post and page (obviously)
• The RSS feed: /feed/ → /rss.xml
• Paginated archives: /page/2/, /page/3/…
• Author and category pages
• Media URLs (images) if they change
• Trailing slashes — a source of silent duplicates

Configuration: a _redirects file at the root (Cloudflare Pages, Netlify) or Cloudflare rules. All redirects must be 301 (permanent) to transfer authority.

# _redirects — Cloudflare Pages
# Format: SOURCE  DESTINATION  CODE

/category/blog/:slug   /blog/:slug   301
/author/:name          /blog         301
/?p=:id                /blog         301
/?page_id=:id          /             301

# Old WordPress sitemap
/sitemap_index.xml     /sitemap.xml  301
/wp-sitemap.xml        /sitemap.xml  301

Verification: crawl your old sitemap with a tool (Screaming Frog, batch curl) and verify that every URL returns a 301 to the correct destination. A single 404 on a high-traffic page can undo weeks of work.

“Migrating a 50-page WordPress site to Astro typically takes 2 to 4 weeks, including one week of SEO testing before the DNS switch.”

— Astro4B estimate, based on 8 migrations completed in 2025–2026

Step 6: launch and monitor

On launch day, submit your new sitemap in Google Search Console and Bing Webmaster Tools. Then monitor.

Monitoring protocol:

• Week 1 — Daily checks: crawl errors, 404 pages, deindexations
• Weeks 2–4 — Weekly checks: positions, impressions, CTR
• Month 2 — Full review: organic traffic vs pre-migration baseline

Realistic recovery timeline:

• Identical URLs + 301s in place: slight fluctuation weeks 1–2, recovery within 30 days
• URL structure change with 301s: 30 to 60 days
• Botched migration (missing redirects): -40 to -60% organic traffic in week 1

Well executed, the migration produces the opposite effect: performance gains (green Core Web Vitals) start pushing organic traffic upwards from the second month.

When NOT to migrate

We sell Astro sites. But not at any cost.

Astro excels on content sites: brochure sites, blogs, marketing sites, portfolios. For a SaaS with a dashboard, a marketplace, or a complex transactional site, other frameworks (Next.js, Remix) are better suited.

If you don’t know which category you fall into, this is probably a good time to talk about it.

---

You have a WordPress site and recognise yourself in this article? Build your project in the configurator — the price is already there.