Migrating a Legacy WordPress Site to Astro.js

If you’ve been building for the web for a while, you’ve probably inherited a WordPress site that feels like a house of cards. Page builders like Elementor are fantastic for getting a site off the ground quickly, but over time, they leave behind a trail of <div> soup, bloated CSS, and sluggish load times.

Recently, I tackled multiple complete migrations of legacy websites. The goal was always the same: make the website better (performance, security, maintainability, cost). Since I already knew about the blazingly-fast Astro.js, I decided to move multiple of these sites from WordPress to static.

Doing this purely by hand would take days/weeks and nobody will pay me for all that time. Doing this purely with AI results in a messy, disjointed codebase and maybe even more time debugging the issues. My experience is that AI doesn’t handle UI especially well and not when the scope is this large.

How I managed to do this efficiently? The answer is already obvious, by leveraging what AI does well adding that on top of what I do best. Here is my approach to this, some of the technical hurdles I faced, and the blueprint you can use for your own migrations (if you choose to do so).

Some more words on the WHY?

Before diving into the how, let’s talk about the why a little more. WordPress has been the backbone of the web for nearly two decades, and for good reason… It’s accessible, flexible, and has an enormous ecosystem. But in my experience, all of this comes with baggage.

The WordPress Problem

Every WordPress site I’ve inherited shared more or less the same issues:

• Performance degradation over time - Plugins accumulate, database queries multiply, and page load times creep up
• Security complexity - Constant updates, plugin vulnerabilities, and the need for regular backups and monitoring
• Hosting costs - WordPress obviously requires a DB, PHP execution, and regular maintenance. Costs seam small in the beginning but all that can add up quickly
• Maintenance burden - Client sites became my responsibility. A plugin breaks? I fix it. The server crashes? I restore it. For multiple clients and sites this ended taking up more time than I was willing to spend
• Bloated output - Page builders generate deeply nested HTML that’s hard to modify or optimize. Since I am a Software Engineer it’s not hard for me to get into it and some minor changes ended up taking more time than if I would have written it from scratch.

I wanted something different and better. Since I enjoy building websites and web applications I wanted a site that was fast by default, secure by design, and cheap to host. Why not have the best on multiple fronts?

Why Astro (and Not Hugo or Jekyll)?

I guess I don’t need to convince you since if you found this article, you’re probably already thinking about Astro. If not, then this might help you decide, but my goal with this post wasn’t really about the technical comparison.

That said, here’s the quick version: Hugo and Jekyll are excellent static site generators. I’ve tried Hugo an used it for a couple of months but things didn’t quite match as well as I wanted. I couldn’t really put my finger on it but when I heard about Astro and then tried it out, it just felt right. Astro sits in a sweet spot, since it’s modern, component-based, supports multiple frameworks, and generates very little JavaScript by default. It was easy to pick up and using it with bun and some good templates and things I’ve picked up over the years made the process a bliss for me.

One other great advantage? Astro lets you use the tools you already know (React, Vue, Svelte components) while generating pure HTML. If you’ve got some components from somewhere else then you can mix and match them with ease. Although most of the time if I don’t need to combine the site with a CMS then I just stick with pure .astro components.

1. The work strategy and flow

When rebuilding a site, AI can be an incredible force multiplier, but you have to use the right tool for the right job. I didn’t want to burn through my credits too quickly, so I used a two-tier approach.

Step 1: The Architect (High-Tier AI)

First, I prompted a highly capable (and usually more expensive) AI model to perform a deep analysis of the existing WordPress site and the target Astro template chosen for the project. Its only job was to generate a comprehensive, structured Markdown plan.

The more detailed explanations and the more specific context description you can give at this point the better. I usually take the time to really write things down in a structured way here so that the next step is as smooth as possible. I try to give examples, links, specific colors, key things that I want it to consider in terms of layout, architecture, UI and so on.

Here is an example of the prompt we used to create our master plan:

Here is the README for my target Astro.js template:
[Insert Astro Template README]

I want you to replicate an original WP website and recreate it in this Astro.js project. Please plan out the best approach on how to replicate all the pages. Evaluate the CSS, the colors, images, text, files, tables—everything should be the same as the original page.

Write out the best course of action in great detail so that we can pass this to a lesser AI agent that will implement it. Lay down good foundations and wherever it's possible, replicate the original content 100% and adapt this Astro template to match the original site.

[Give more detailed description about the page, the content, the colors, structure, etc.]

Here are the target URLs to analyze:
- https://example.com/
- https://example.com/registration/
- https://example.com/contact/

The output usually is a massive, highly detailed Markdown document that mapped out the navigation, the exact color codes, font families, and a breakdown of the DOM structure for every single page.

Step 2: The Builder (Cheaper AI + Manual adjustments)

Once the blueprint is ready, I generally hand it over to an IDE-integrated AI coding assistant (like Cascade, Cursor, or Copilot). Because the AI already had a strict plan to follow (which I already approved!), it didn’t hallucinate features or guess the architecture. It just executed the instructions, step by step, component by component. This is a constant back and forth between checking what he wants to do, how the site looks in the process and making adjustments along the way.

2. The Human Touch: Setting the Foundation

All in all, AI is great at writing loops and scaffolding components, but when it comes to decision making my experience is that it still needs to be helped out. And until it doesn’t, I get to remain an important part of the process, so this has its upsides.

It’s good to define the technical foundations in the beginning, like defining the global CSS variables in Tailwind v4, choosing the architecture for our layouts (<BaseLayout>), and deciding how assets would be handled. It might happen that the AI gets stuck in a loop even though you gave it the right instructions. For example, on one occasion, trying to use deprecated Tailwind @apply directives caused PostCSS parsing errors since the code it generated wasn’t playing well with the template and other parts of the project so it needed some help to diagnose the build failure, and reach a good final solution. The more specific you are with your intent and the more you describe the project and what you want and how everything should fit together, the lower the chances that you will have these issues. *Although these still come up.

I remained in charge and could pay attention to the direction things were going, while the AI did most of the labor. It was a good approach that reduced the number of credits burned (Windsurf’s SWE is free for now, although they are not paying me to say this unfortunately) and kept the project on track.

3. Translating “Div Soup” into Astro Components

One of the most satisfying parts of moving away from a WordPress page builder is cleaning up the DOM. Elementor, for instance, often generates incredibly deep HTML trees just to display a hero image with a dark overlay.

Here is what the original WordPress DOM looked like for a single hero section:

<!-- The WordPress Page Builder Way -->
<section class="elementor-section elementor-top-section elementor-section-full_width">
    <div class="elementor-container elementor-column-gap-no">
        <div class="elementor-column elementor-col-100">
            <div class="elementor-column-wrap elementor-element-populated">
                <div class="elementor-background-overlay"></div>
                <div class="elementor-widget-wrap">
                    <img src="/wp-content/uploads/bg.jpg" class="attachment-full" />
                    <!-- ... 5 more nested divs before the text ... -->
                </div>
            </div>
        </div>
    </div>
</section>

By passing the plan to the AI assistant, we translated most of the bloated mess into clean, highly readable Astro components using Tailwind CSS:

---
// src/components/Hero.astro
---
<section class="relative z-10 flex min-h-lvh w-full">
    <!-- Background image & Elementor-style overlay -->
    <div class="absolute -z-10 h-full w-full overflow-hidden">
        <img src="/images/hero-bg.jpg" class="h-full w-full object-cover" alt="Hero" />
        <div class="absolute inset-0 bg-black/50"></div>
    </div>

    <!-- Content -->
    <div class="site-container relative w-full py-44 text-center">
        <h1 class="font-heading text-4xl text-white">Welcome</h1>
    </div>
</section>

Note: You can also give existing free Tailwind or other components for reference for the agent during the process to get a better end result. Tailwind has this nice advantage in agentic UI development, that the styles are more obvious and are usually right there so the context is smaller and easier to handle.

Usually for the visual output I decided to maintain most of the visual aspects of the original design. When a complete rewrite was required by the client, then of course we did that but for those who wanted the site to keep its original look and feel, we did our best to preserve it in a new and cleaner structure.

4. Rescuing Assets Before the Server Dies

During migrations, legacy servers often get decommissioned at some point in time. Hopefully you can finish the full Astro site before that happens and just point the domain to the new website before taking down the old WP server. Basically, in most cases hotlinking to the old wp-content/uploads folders ins’t an option.

Instead of right-clicking and saving dozens of images, we can once again use the agent to write a quick script to scrape the exact assets we needed straight into our Astro /public or /assets directory. Once you point it to the right direction it should output something like this:

# Bulk downloading WordPress assets via terminal
curl -o ./public/images/hero-bg.jpg "https://oldsite.com/wp-content/uploads/2020/12/hero.jpg" && \
curl -o ./public/images/logo.png "https://oldsite.com/wp-content/uploads/2020/12/logo.png"

This ensured that when I flipped the switch, our Astro site was 100% independent and self-contained.

The Real Benefits: Why This Migration Was Worth It

Beyond the cleaner code and modern tech stack, the migration delivered tangible, measurable improvements that directly impact both our clients and our business.

Performance Gains That Actually Matter

The performance difference was dramatic. Our site loading improved between 50-150% on average.

But the real win wasn’t just the numbers. It was the user experience. First Contentful Paint, Time to Interactive, and our Lighthouse Performance Score all improved dramatically. We usually pull 95-100% on all categories after the rework and all that without all the image processing WP plugins, caching plugins and so on that comes with making WP sites performant. Most of the lifting in this regard is done by Astro and it’s built in optimizations.

These aren’t vanity metrics. Faster load times mean lower bounce rates, better SEO rankings, and more conversions.

Hosting: Free (or Nearly Free) Forever

WordPress hosting was costing our client a decent amount for decent performance.

With Astro, we deployed multiple clients to Vercel’s free tier. Zero cost. Zero maintenance (mostly). And it handles traffic spikes effortlessly because it’s just static files served from a CDN.

For larger sites that exceed Vercel’s free limits, you have options:

• Netlify: Free tier is generous, paid plans start at $19/month
• Cloudflare Pages: Unlimited bandwidth on the free tier
• AWS S3 + CloudFront: Pennies per month for most small to medium sites

Even if you need forms, you don’t necessarily need WordPress. Modern solutions like:

• Formspree or Tally for simple contact forms
• Serverless functions (Vercel, Netlify) for custom logic
• API-based form providers like Basin or Formspark

These handle 99% of use cases without the overhead of WordPress.

You can evan take a look at some CMS implementations as well if you have to work together with a content management team or need to provide easier access to content editing for the client.

For some lighter use cases you can also sprinkle in something like Stripe or other payment providers for simple payment flows.

Don’t expect to do a full e-commerce site or a complex web application with thousands of concurrent users this way but many businesses can benefit from this approach. Not every business needs WooCommerce, Shopify or a whole custom app built to make a profit or achieve the goals they have in mind.

Security

WordPress powers a very big chunk, which makes it a massive target. Bots constantly scan for /wp-admin and other endpoints, outdated plugins, and theme vulnerabilities.

Our client’s WordPress site was getting multiple attack attempts daily. We had to maintain:

• Security plugins (Wordfence, Sucuri)
• Regular backups
• Plugin/theme updates (and pray nothing breaks)
• Firewall rules
• SSL certificate renewals

With Astro, most or all of that disappeared. There’s no admin panel to attack. No database to inject SQL into. No PHP to exploit. It’s just static HTML, CSS, and JavaScript served from a CDN.

The attack surface decreased significantly. We eliminate backend attack vectors but still use node packages we need to vet our frontend dependencies for security vulnerabilities and keep a look out to supply chain attacks. Still my experience is that staying on top of this is much easier and less of a hassle then maintaining everything that comes with WP.

Maintenance

WordPress maintenance was starting to become a burden:

• Update plugins (and test for conflicts)
• Update themes (and fix broken layouts)
• Update WordPress core (and hold your breath)
• Monitor backups
• Check for security alerts
• Optimize the database

With Astro, maintenance is closer to zero. I generally update dependencies once a quarter or when there’s a critical security update. No database to optimize. No plugins to conflict. Package conflicts can happen but they are usually faster to solve in my experience.

I usually manage to get a friendlier price for our clients and cut down on their costs which was a big plus in some cases.

TLDR

So, should you migrate your WordPress site to Astro? Here’s my take:

The short answer: If your WordPress site is becoming a pain to maintain, slow, or expensive to host, then yeah, probably.

How to do it without going broke or crazy:

• Step 1: Use a fancy AI (the expensive ones) to create a super detailed plan of what needs to be done
• Step 2: Use a cheaper AI assistant in your IDE to actually do the coding work
• Step 3: Stay in charge as you go and set the tone and the foundation, fix the weird stuff, and make sure things don’t explode

Is it worth it? For me, absolutely. The sites I’ve migrated are now faster, more secure, and most of them are basically free to host. Plus, I’m not on a constant lookout because some plugin decided to break everything for one of our clients.

The catch: You still need to know what you’re doing. This isn’t a “push button and get perfect website” situation. But if you’re comfortable with web development and want to spend less time maintaining old WordPress sites, this approach has worked really well for me.

It’s not for everyone and certainly not for everything. Your mileage may vary, but I’ve been pretty happy with the results.