Back to the blog

Migrating from WordPress to Astro: steps, trade-offs and SEO checks

What to keep and rebuild when moving from WordPress to Astro: content, plugins, editing and SEO. Learn how to plan the switch and preserve URL paths.

Published
Reading time
8 minutes
Topics
Astro · WordPress · Website migration · Technical SEO

Migrating from WordPress to Astro means separating the content you want to keep, the presentation you need to rebuild and the features currently handled by plugins. Decide who will edit the website afterwards, preserve the domain and URL paths where practical, and test each feature before replacing the live site.

A slow WordPress website does not automatically need a migration. Image, caching or hosting problems may be fixable without a rebuild. Moving makes sense when the problem it solves justifies the development and ongoing maintenance.

This guide covers that process with a feature inventory and a code example for preserving URL paths. The example uses fictional addresses; it is not a client migration or a benchmark of traffic improvements.

When moving from WordPress to Astro makes sense

I would consider it for a service website or blog that needs control over its frontend, fewer page-builder dependencies and a defined content structure. Someone must also own the code and publishing workflow afterwards.

I would be more cautious if the business relies on WooCommerce, memberships, bookings, comments or several connected plugins. Rebuilding those features may cost more than fixing the existing site. If the problem is an outdated design, redesigning within WordPress is another option.

The Astro versus WordPress comparison covers platform choice. This guide addresses a different question: what must be resolved before replacing a website that already exists.

Decide whether WordPress stays as the CMS

There are two distinct approaches:

  • Remove WordPress. Move content into files or another CMS, agree how editing will work and replace the features the site uses.
  • Keep WordPress as a headless CMS. Editors keep their dashboard while Astro uses its data to build the public website. WordPress still needs hosting, updates and access management.

Astro documents connecting to WordPress through its API. Keeping the dashboard does not automatically preserve the theme, previews or plugin behaviour in the new frontend.

If that is the chosen approach, the Astro with headless WordPress guide covers the TypeScript REST connection, pagination, route generation and the publishing and SEO decisions missing from a basic proof of concept.

With build-time rendering, publishing in WordPress must trigger a fresh Astro build. Fetching data on each request requires maintaining a server and that dependency. A dashboard that says “published” while the website still shows the old version is an unfinished workflow.

Inventory the website before exporting

Start with URLs from the sitemap, a crawl, Search Console and WordPress itself. No single source guarantees a complete list. Include campaign pages, documents and linked URLs that are absent from the navigation.

For each page, record its destination, content, behaviour and remaining checks. A small inventory might include these decisions:

Current URL Decision and required check
/services/consultation/ Keep the path and check content, CTA and metadata.
/blog/first-consultation/ Keep the path, original date, links and image.
/book/ Identify what processes and confirms a booking before rebuilding the interface.
/wp-content/uploads/guide.pdf Preserve the file or define its new location and redirect.

Include forms, search, cookies, analytics, translations and email attached to the domain. Replacing the website should not accidentally change mail records. Record who controls the domain, DNS, hosting and external accounts.

What transfers and what needs rebuilding

Exporting content and rebuilding a website are separate tasks. The theme and plugins may produce behaviour that is not stored in a text field.

WordPress feature What Astro needs
Posts and pages Import text, dates, authors and relationships; review the rendered result.
Media library Copy files, update references and preserve useful information such as alt text.
Theme or Elementor Rebuild components, styling, responsive layouts and interactions. Importing posts does not convert the design.
Shortcodes and plugin blocks Identify each type and replace it with equivalent content or components.
SEO plugin Extract the required data and generate titles, descriptions, canonicals, schema and sitemaps in the new system.
Contact form Connect submission, validation, abuse protection and confirmation; check actual delivery.
Search, comments or bookings Choose an implementation or service with an agreed cost and owner.
Redirects and languages Move rules and URL relationships into the new hosting and routing setup.

A form that looks identical but sends nothing is a lost feature. So is a shortcode appearing as plain text in a post. These checks belong in the agreed scope.

Export data without mistaking one response for a complete backup

The REST API has separate endpoints for posts, pages and media. This command illustrates fetching one page of public posts; replace the domain with a site you manage:

curl --fail --show-error \
  'https://example.com/wp-json/wp/v2/posts?per_page=100&page=1' \
  --output posts-page-1.json

The WordPress pagination documentation explains the limits and response headers for fetching subsequent pages. Complete the available pages and reconcile the record count. This one file does not also contain pages, every media file, drafts or the site configuration.

First make a recoverable backup of the installation and database. A content export helps move information; it does not replace a backup that can restore the service.

If the destination is Markdown or MDX, the HTML needs conversion and review. Page builders and custom blocks may require manual work. The Astro migration guide offers starting points, rather than converting every installation into a finished website.

How to preserve page URL paths

A WordPress record might have consultation as its slug and /services/consultation/ as its full path. Building the new address from the slug alone would discard that hierarchy.

This excerpt from src/pages/[...path].astro generates routes from link. The src/data/wordpress.json file represents records that have already been exported and reviewed. https://example.test is a fictional source domain and needs replacing with the real origin:

---
import records from '../data/wordpress.json';

export function getStaticPaths() {
  return records.map((record) => {
    const url = new URL(record.link);
    if (url.origin !== 'https://example.test' || url.search || url.hash) {
      throw new Error(`Review the source URL: ${record.link}`);
    }
    return {
      params: { path: url.pathname.replace(/^\/+|\/+$/g, '') },
      props: { record },
    };
  });
}
---

Using the full pathname preserves prefixes such as /blog/ and /services/. After building, check that every expected path exists and its links and assets have valid destinations. This fragment handles route generation; templates and metadata need their own implementation.

If you render the imported body with set:html, remember that the directive does not sanitise external content. Validate and sanitise HTML and URLs before publication. Resolving routes does not convert Elementor or replace plugin behaviour.

My portfolio’s multi-page Astro architecture shows how I organise content, components and metadata. It demonstrates implementation of the destination, rather than previous experience migrating a client from WordPress.

Check URLs, metadata and assets before switching

Preserve URLs that still make sense. Changing technology does not require changing the domain or every path. Where an address must change, record its equivalent and configure a permanent redirect on the host that receives requests for the old address.

If WordPress is retired, its redirect plugins will no longer handle requests that never reach it. Test the rules at the actual destination. Avoid sending every old page to the homepage without a relevant equivalent.

For each page type, compare its title, description, canonical, language, content, links and media. Review category and author pages before removing them. A posts export may omit metadata stored by SEO plugins; extract those fields separately or deliberately define replacements.

Google advises preparing a URL map and testing the move, and warns that changed URLs can cause ranking fluctuations. That is why I would not promise a migration “without losing rankings”. Google’s URL migration guidance.

Launch with checks and a recovery plan

Before switching, record which version will go live, when content changes will pause and how edits made during development will be reconciled. If WordPress remains the CMS, test a complete publishing cycle through to the public URL.

Set aside time to check the final website:

  1. Open representative pages on mobile and desktop.
  2. Follow old links and check their response or destination.
  3. Submit a test form and confirm delivery.
  4. Review indexability, sitemap, metadata and consent-aware analytics.
  5. Keep a baseline for comparing errors, visits and search queries afterwards.

Keep a backup and a procedure for restoring the previous version. Restoring the frontend does not automatically restore messages, orders or external data received during the switch.

If a URL is missing from Google afterwards, follow an indexing diagnosis rather than immediately blaming Astro. Correctly generated pages still need to be discovered and evaluated.

What a migration quote should include

Ask for the pages, content types, features, assets, languages, redirects and future editing workflow to be specified. Include who prepares the copy, who validates functional equivalence and what counts as finished.

The quote should also cover testing, the hosting switch, accounts or services that still need paying for and agreed support afterwards. Moving ten text pages has a different scope from rebuilding bookings, a catalogue or user accounts, even with a similar URL count.

The aim is to understand what you will retain and how the website will work afterwards. If you are considering a rebuild, see my custom web design and development service to define the scope before choosing the solution.