A WordPress to Astro migration should start with a URL and feature inventory, then a content-model decision. Map the content, media and plugin behavior, rebuild the templates, and prove that editors can preview and publish before changing production routing. Keep existing URLs where possible and test redirects for any that must change. A framework change cannot guarantee stable rankings.
The move can make sense when the current WordPress setup blocks campaign delivery or needs recurring repairs. Astro’s islands architecture lets the page render as HTML while selected interactive components load client-side JavaScript, as the official documentation explains. That is a useful capability, not proof that any Astro rebuild will outperform a well-managed WordPress site.
The risk is that a faster site can still lose search visibility if the migration drops URLs, changes canonicals, loses metadata, breaks images, or stops tracking conversions. Treat this as an SEO launch system, not a design refresh.
For the broader platform decision, use the website platform migration guide and compare Astro vs WordPress. If the move is already likely, pair this WordPress-specific plan with a website migration audit and the full website migration SEO checklist before launch.
When should a WordPress site move to Astro?
Consider moving a WordPress site to Astro when the public site is content-heavy and the team can own its code, CMS integration and deployments. First check whether hosting, caching, plugin cleanup or a template repair can resolve the actual constraint. A rebuild also introduces maintenance responsibilities.
Look for these triggers before recommending a rebuild:
- Plugin drag: SEO, forms, caching, page builders, redirects, schema, and tracking depend on a fragile plugin stack.
- Performance issues: Core Web Vitals work has become a recurring maintenance task instead of a one-time cleanup.
- Security maintenance: WordPress core, themes, plugins, user roles, and database exposure require constant patching.
- Brittle themes: small content or plugin changes create layout bugs because pages rely on a visual builder or old theme framework.
- Messy content: posts, pages, media, revisions, shortcodes, categories, and metadata have drifted over years.
- Slow landing-page delivery: marketing needs reusable page patterns, cleaner components, and faster launch cycles.
Do not migrate only because Astro is fashionable. If the site is a true application, has heavy logged-in behavior, or works well enough with a smaller optimization pass, the better move may be to fix WordPress, simplify plugins, or rebuild only the pages that are creating business drag.
Pre-migration inventory
The pre-migration inventory is the part of the project that protects SEO. Before rebuilding templates, create one working inventory that combines the current site crawl, WordPress exports, analytics, Search Console, redirect plugins, server rules, and paid media landing pages.
At minimum, capture these items:
| Inventory item | What to capture | Why it matters |
|---|---|---|
| URLs | Live pages, posts, taxonomy pages, redirects, PDFs, gated assets, and high-value historical URLs | Prevents lost pages, surprise 404s, and missed redirect rules |
| Templates | Homepage, landing pages, blog posts, category pages, author pages, case studies, and legal pages | Shows what needs a reusable Astro layout rather than one-off rebuild work |
| Posts and pages | Titles, body content, slugs, publish dates, modified dates, authors, categories, tags, and excerpts | Keeps content structure intact during the CMS move |
| Media | Image paths, file names, alt text, captions, featured images, Open Graph images, PDFs, and download URLs | Prevents broken images and protects accessibility metadata |
| Redirects | Plugin redirects, server redirects, legacy campaign URLs, uppercase variants, trailing slash rules, and deleted content | Gives the launch team a redirect map before DNS changes |
| Metadata | Meta titles, descriptions, canonicals, robots directives, Open Graph tags, and Twitter card tags | Prevents search snippets and sharing previews from regressing |
| Schema | Existing JSON-LD, its source and whether each type still matches the page | Prevents blindly copying stale or ineligible markup |
| Forms | Contact forms, lead magnets, newsletter forms, hidden fields, thank-you pages, spam controls, and CRM routing | Prevents lost leads after launch |
| Analytics | GA4 property, GTM container, pixels, conversion events, consent tags, UTM rules, and paid media imports | Keeps reporting and bidding signals continuous |
| Integrations | CRM, email platform, payment tools, scheduling, search, memberships, personalization, and APIs | Identifies dynamic work that may need serverless routes or a CMS integration |
This is also where you decide what not to migrate. Thin tags, duplicate archives, obsolete landing pages, old author pages, and expired campaign URLs should be mapped intentionally: keep, consolidate, redirect, noindex, or return a proper 404/410.
Choose the content model before the build
The content decision shapes the entire WordPress migration checklist. Do this before component design, because the editing workflow determines how content moves through Astro.
Option 1: Export content and retire WordPress
Export content to the new publishing system when the team can maintain Git, Markdown, MDX or an editor on top of the repository. Exporting posts is not the same as exporting a working static website.
WordPress’s Tools Export screen produces a WXR XML file containing content such as posts, pages, custom fields and taxonomies. Keep a separate database and file backup for recovery. Verify that your conversion retrieves the media files and maps SEO plugin fields, custom types and relationships; a successful XML download does not prove those parts work in Astro.
Convert and review the content, copy the required assets, and rebuild templates around the chosen model. Astro content collections provide structured content loading and schema validation. They do not automatically reconstruct WordPress themes, plugin settings or editorial approvals.
Choose this when retiring WordPress is worth the change in editing and maintenance. Agree who can publish, correct and restore content after the move.
Option 2: Headless WordPress
Use headless WordPress when the editorial team needs to retain its dashboard and content administration. Audit plugin behavior separately: keeping WordPress does not automatically carry its front-end forms, page-builder layouts or scripts into Astro.
In this model, WordPress remains the CMS and Astro becomes the public front end. Astro’s headless WordPress guide describes using the REST API or an optional GraphQL plugin. Check that each required custom content type and field is available through the chosen API.
WordPress still needs updates, hosting and access controls. For statically generated pages, define what triggers a deployment after publishing, editing or unpublishing. For request-time rendering, define cache invalidation. Both need failure reporting and an editor who knows which version is live.
Option 3: Astro content collections with a new CMS
Use a new CMS when the team needs an editing interface but does not need to retain WordPress. Astro’s CMS guides describe available integration approaches. Confirm the chosen CMS supports the required permissions, previews, content relationships and publication behavior; these are not identical across products.
This path is usually best when the current WordPress content model is part of the problem. It lets you design content types around how the marketing site actually works: services, journal posts, authors, landing pages, testimonials, case studies, locations, and FAQs.
Prove one post survives the publishing path
Before converting the whole library, use a representative post to test the destination workflow. The following is a hypothetical acceptance case, not a migration Hapy has tested or a promise that every WordPress plugin can be replaced.
Choose a post with an old permalink, a featured image, custom SEO metadata and an embedded lead form. Include a draft revision and a scheduled change if the team uses those features. Keep a record of the WordPress ID, destination path, original publication date, author and asset mappings so a second import updates the same post instead of creating a duplicate.
Check the content and plugin behavior
Compare the rendered post with the source, not only the converted Markdown. Check headings, tables, internal links, image alt text and captions. Confirm that the SEO title, description, canonical and robots rules reach the page head.
Assign each shortcode or plugin function a destination: supported component, separate service, retained WordPress endpoint or deliberate removal. A form that looks correct but sends no lead is a failed migration. Submit a test with clearly labeled test data and verify its expected destination. Astro’s WordPress migration guide explains that existing plugin features may need new implementation.
Test draft, publish, failure and unpublish
| Editor action | Required observation before launch |
|---|---|
| Preview a draft | An authorized editor can see it, but an unauthenticated visitor cannot retrieve it or find it in public HTML, feeds or caches. |
| Publish or update | The intended revision appears at the mapped URL with the right metadata and assets; record the deployment or cache update that made it live. |
| Schedule a change | The change becomes public at the agreed time, or the editor receives a clear failure alert. Do not assume a static build notices the schedule. |
| Trigger a failed build | The previous good release stays available, the owner receives the error, and the editor can tell that the update is not live. |
| Unpublish | The page, public listings and cached copies follow the agreed removal policy. Choose the appropriate status or replacement deliberately. |
Protect preview access at the application or hosting layer. A secret-looking URL, robots.txt rule or noindex tag is not access control. For headless WordPress, use an authenticated server-side path with the appropriate permissions for non-public content; do not put credentials in browser code. The WordPress REST authentication handbook explains authentication and capability checks.
Name the editor who accepts the results and the engineer who owns failures. Keep the URL and content mappings with the rollback plan. If this representative post cannot complete the workflow, resolve the gap before bulk conversion or production cutover.
Launch checks that reduce SEO risk
Google’s site-move guidance is simple in principle and unforgiving in execution: prepare the new site, create a URL mapping, implement redirects, and monitor both old and new URLs after launch. Google’s documentation also says ranking fluctuation can happen during a move while pages are recrawled and reindexed, which is why the checklist matters.
Use this website migration SEO checklist as the launch control:
-
Freeze the URL inventory. Export the final legacy URL list from WordPress, crawler data, Search Console, analytics, sitemap files, redirect plugins, and server rules. Mark each URL as keep, redirect, merge, noindex, 404, or 410.
-
Build one-to-one redirect rules. Every meaningful old URL should resolve directly to its best new equivalent. Google recommends permanent server-side redirects such as 301 or 308 where possible and warns against long redirect chains in its site move documentation.
-
Preserve or improve canonical tags. Each indexable Astro page needs a production canonical URL. Google treats canonicalization as a way to identify the preferred URL among duplicates, so do not let staging domains, trailing slash variants, or paginated paths point to the wrong target.
-
Rebuild metadata from the inventory. Carry over or rewrite meta titles, meta descriptions, Open Graph images, robots directives, and social card tags. Do not let the new system generate generic defaults across the site.
-
Recreate schema deliberately. Use only structured data that matches the page and current eligibility rules. Do not copy plugin-generated markup blindly or assume visible FAQs require FAQPage markup. Test eligible templates with Google’s Rich Results Test; valid markup does not guarantee a rich result.
-
Generate a clean sitemap. The live sitemap should include only indexable, canonical, 200-status URLs. Google’s sitemap guidance frames sitemaps as a way to help search engines discover important URLs, but they are not a substitute for clean internal links or redirects.
-
Crawl staging against the old site. Compare titles, headings, canonicals, metadata, schema, image references, internal links, and status codes. Fix missing images, broken links, wrong slugs, and staging canonicals before DNS changes.
-
Verify forms and analytics. Submit every lead form, test thank-you states, confirm CRM delivery, check GA4 realtime reports, verify GTM triggers, and confirm ad platform conversion events if paid campaigns depend on the site.
-
Launch during a lower-risk window. Avoid major campaign launches, product announcements, and peak traffic periods. Keep the old WordPress install accessible privately for recovery, but do not let it remain indexable as a duplicate site.
-
Assign ongoing monitoring. Watch Search Console indexing, crawl stats, 404s, sitemap submissions, organic landing pages, leads and conversion events. Keep a named owner after the launch period. For changed URLs, Google recommends keeping redirects for as long as possible, generally at least one year. A fixed eight-week watch does not prove migration completion.
Common migration risks and how to avoid them
Most WordPress to Astro migration problems are not caused by Astro. They come from missing inventory, unclear ownership, rushed redirects, and content decisions made after the build has already started.
| Risk | What goes wrong | Prevention |
|---|---|---|
| Lost URLs | Old posts, PDFs, taxonomy pages, or campaign pages return 404s | Build the URL map from crawler data, WordPress exports, analytics, Search Console, and redirect plugins |
| Missing images | Old /wp-content/uploads/ paths break or alt text is lost |
Download and map media assets, preserve alt text, and test rendered pages before launch |
| Changed slugs | New clean URLs accidentally replace URLs that already rank | Keep ranking URLs where possible; redirect only when the new URL is clearly better |
| Broken internal links | Pages link through old WordPress paths or redirect chains | Rewrite internal links to final Astro URLs before launch |
| Analytics gaps | GA4, GTM, pixels, or conversion events stop firing | Create tracking parity tests and verify realtime data before DNS changes |
| CMS confusion | Editors do not know whether to update WordPress, Markdown, or a new CMS | Decide the content model early and document ownership before handoff |
| Schema loss | Rich-result markup disappears during template rebuild | Audit current JSON-LD, rebuild it in shared Astro metadata components, and validate templates |
| Canonical mistakes | Staging URLs, duplicate slash variants, or paginated pages become canonical | Generate canonicals from the production site URL and crawl staging for mistakes |
Technical checks inside the Astro build
Astro will not automatically solve SEO because the framework is fast. The build still needs SEO decisions encoded in layouts, data models, and deployment behavior.
Set these controls in the project:
- Use a shared metadata component for title, description, canonical, Open Graph, Twitter card, robots, and schema behavior.
- Validate content frontmatter so missing descriptions, invalid dates, or overlong titles fail before deployment.
- Keep pages semantic: one H1, clean heading order, descriptive image alt text, and useful internal links.
- Generate the sitemap from the same URL source the templates use.
- Keep redirects in version control when the list is small, and use edge-level redirect tools for large legacy maps.
- Test the production build, not only the local development server.
- Keep important pages readable in HTML without relying on client-side rendering for core content.
The point is not to make Astro imitate WordPress. The point is to rebuild the site as a smaller, more controlled publishing system.
What to do in the first 48 hours after launch
The first 48 hours are for detection, not celebration. Have one person own the issue log and triage by severity.
Check these first:
- Homepage, top organic landing pages, and top paid landing pages return 200.
- Top legacy URLs redirect directly to the correct new URL.
- Sitemap is live and submitted in Search Console.
- Robots.txt allows production crawling and references the correct sitemap.
- Canonicals point to production URLs.
- Key templates render expected metadata and schema.
- Lead forms reach the CRM or inbox.
- GA4 realtime reports show traffic and conversion events.
- Paid media URLs and UTM parameters land on the right pages.
- Search Console starts showing expected discovery and indexing behavior.
As an initial operating plan, review the watchlist daily in the first week and weekly through week eight. Extend it where recrawling, errors or business outcomes remain unresolved. These intervals are planning choices, not Google’s guarantee. Investigate spikes in 404s, missing canonical pages, dropped conversion events or declines isolated to a directory before making broad changes.
When Hapy Co should help
If the project is a small blog, a careful internal team may be able to migrate from WordPress to Astro with the checklist above. If the site carries meaningful organic traffic, paid acquisition, lead generation, or content operations, the migration deserves a risk audit before the rebuild.
Hapy Co sells an Astro website migration engagement, so we have a commercial interest in this work. Start with the inventory and publishing acceptance case. Use those findings to decide whether to repair WordPress, retain it as a headless CMS or move the content to another system.
Before approving the build, ask for the inventory, a working publishing test and a recovery owner. At launch, verify the mapped URLs and lead flow, then monitor search performance while the changed pages are recrawled.
