Moving a website to Astro can improve performance and simplify maintenance. But a successful migration involves more than rebuilding the homepage in .astro files. You also need to preserve URLs, content, metadata, forms, analytics, integrations, and the publishing workflow.
Use this as a working checklist. Copy it into your project issue, assign an owner to each phase, and do not approve the launch while a critical item remains unchecked.
Migration rule: The new site is ready only when it preserves the old site's valuable content, discoverability, and business functions not when it merely looks the same.
Phase 1: Decide what you are migrating
Confirm Astro suits the website. It is an excellent fit for marketing sites, blogs, documentation, landing pages, and other content-led websites.
List dynamic pages and interactive islands. Search, filters, calculators, and account widgets may need runtime code; most content does not.
Choose the content model. Decide between Markdown/MDX, Astro content collections, a headless CMS, or the existing CMS used headlessly.
Confirm the editorial workflow. Make sure non-technical editors can create, preview, update, and publish content after migration.
If you are still deciding whether the migration is justified, this Astro vs WordPress comparison explains the trade-offs around performance, plugins, ownership, and editing.
Phase 2: Audit the current website
Crawl the complete website. Use the sitemap and a crawler such as Screaming Frog or Sitebulb.
Export landing pages from Google Search Console and analytics. These sources can reveal important URLs missing from the sitemap.
Identify pages with traffic, conversions, or backlinks. Mark them as priority URLs for manual QA.
Inventory page templates. Include articles, listings, services, author pages, contact pages, archives, and error pages.
Inventory platform features. Record forms, search, comments, memberships, e-commerce, multilingual content, redirects, and scheduled publishing.
Audit third-party scripts. Include analytics, consent tools, chat widgets, schedulers, and advertising pixels.
Create a complete backup. Preserve the database, media, metadata, forms, redirects, DNS records, and deployment settings.
Phase 3: Prepare the Astro architecture
Choose static or on-demand rendering for each route type. Use Astro's static output by default unless a page genuinely needs request-time data.
Select the hosting platform and Astro adapter. Confirm runtime, environment-variable, image-processing, and redirect support.
Define content schemas. Validate titles, descriptions, dates, slugs, canonical URLs, images, and draft states during the build.
Create reusable layouts before individual pages. Build the document head, header, navigation, footer, article layout, and common content sections first.
Confirm the required Node version. Match local, CI, and production environments to the Astro version being used.
Avoid copying an existing React or Vue frontend into Astro and hydrating it entirely. Migrate reusable components where helpful, but add a client:* directive only when a component needs browser-side interaction.
Phase 4: Extract and clean content
Choose the correct extraction method. WordPress may use WXR, REST API, or WPGraphQL; Webflow may use collection exports or its API; Wix often requires crawling and manual reconstruction.
Export custom fields separately. WordPress ACF fields and plugin data may not appear in a standard XML export.
Extract SEO-plugin data. Titles, meta descriptions, canonical settings, and social images stored by Yoast or Rank Math need their own migration path.
Find and replace shortcodes. Convert galleries, forms, embeds, and custom shortcodes into Astro components or replacement services.
Download every image and file. Do not hotlink assets from the old platform's CDN.
Preserve content relationships. Keep authors, categories, breadcrumbs, related posts, dates, and localized versions.
Clean imported markup. Remove editor-specific inline styles, empty headings, spacer paragraphs, obsolete classes, and staging-domain links.
Platform behavior differs considerably. Refer to a platform-specific walkthrough when migrating from WordPress, Webflow, or Wix.
Phase 5: Replace platform functionality
Map every plugin or native feature to a replacement. Mark each one as replace, rebuild, or remove.
Rebuild forms as complete workflows. Test validation, spam protection, consent, email delivery, CRM delivery, and confirmation states.
Preserve campaign data. Ensure UTM parameters survive the form journey.
Restore analytics before cutover. Page views and conversion events must work before production traffic arrives.
Load third-party scripts intentionally. Delay non-critical tools and confirm consent choices control them correctly.
Recreate RSS feeds where required. Redirect legacy routes such as /feed/ to the new Astro feed.
A “Thank you” message does not prove the form worked. Submit a traceable lead and verify the inbox, CRM, and analytics event.
Phase 6: Protect SEO
Keep valuable URLs unchanged wherever possible. A framework change does not require a URL change.
Create one-to-one permanent redirects. Send removed URLs to the closest relevant replacement—not automatically to the homepage.
Test for redirect chains and loops. Each old URL should reach its final destination in one step.
Update internal links. The new site should link directly to final URLs rather than relying on redirects.
Preserve titles and meta descriptions. Compare old and new values automatically where possible.
Verify canonical and robots directives. Ensure they use the production domain and reflect the intended indexing state.
Recreate structured data and hreflang where relevant.
Generate a clean sitemap. Include canonical, indexable pages only.
Check robots.txt. It should reference the production sitemap and must not carry staging restrictions.
Astro redirects can be configured in astro.config.mjs:
`import { defineConfig } from "astro/config";
export default defineConfig({
site: "https://example.com",
redirects: {
"/old-service/": "/services/new-service/",
"/feed/": "/rss.xml",
},
});`
Test redirects on the deployed environment because the final response can depend on the build mode and hosting platform.
Phase 7: Validate on staging
Run npm run build successfully. Fix warnings that indicate missing content or routes.
Test the production build, not only the development server. Build-time data and environment variables can behave differently.
Crawl the staging site. Find broken links, missing pages, incorrect canonicals, and orphaned content.
Spot-check priority pages manually. Compare content, layout, metadata, images, and calls to action.
Test every redirect with its actual status code. Browser navigation alone can hide redirect problems.
**Test forms and integrations end to end. **Include valid, invalid, spam, and failure scenarios.
Run accessibility checks. Test keyboard navigation, focus states, headings, labels, contrast, and reduced motion.
Measure representative templates. Run Lighthouse after analytics, forms, embeds, and consent tools are installed.
Check mobile and major browsers.
Verify the custom 404 page. It should return a real 404 status, not 200.
Phase 8: Launch and monitor
Take a final backup and content export.
Reduce DNS TTL before cutover if DNS will change. Do this early enough for the previous value to expire.
Confirm production environment variables and CMS webhooks.
Verify HTTPS, redirects, canonical URLs, sitemap, and robots.txt immediately after deployment.
Submit the new sitemap in Google Search Console.
Confirm analytics and conversions using live traffic.
Keep the old platform available temporarily. It provides a rollback path and a reference for missing content.
Crawl production on launch day. Do not wait for users or Google to identify errors.
Monitor 404s, indexing, traffic, forms, and logs daily during the first two weeks.
Compare results page by page. Site-wide traffic can hide a problem affecting one valuable template.
The five checks that should block launch
Do not launch if any of these remain incomplete:
Every priority URL is preserved or redirected correctly.
Production pages are indexable and use correct canonicals.
Forms reach their final inbox or CRM destination.
Analytics records primary conversion events once.
The previous version can be restored if a critical failure occurs.
Final thought
Astro provides a strong technical foundation, but the framework cannot decide which URLs matter, whether metadata was lost, or whether a lead reached the sales team. That is why successful migrations depend on disciplined auditing and validation as much as development.
Top comments (0)