Astro Framework: Why I Build Everything With It

I have 4 production websites running on Astro right now. Not tutorials, not demos, not “hello world” projects. Real businesses generating real traffic and real revenue. After years of building exclusively with WordPress, migrating to Astro for my content sites was one of the best technical decisions I’ve made. And I say this as someone who still runs two WordPress + WooCommerce stores that do ~60 orders per month combined.

The Astro framework isn’t just another JavaScript framework competing for attention in an oversaturated ecosystem. It’s fundamentally different in philosophy: ship zero JavaScript by default, make HTML the first-class output, and let developers add interactivity only where it’s actually needed. For content-driven websites — blogs, documentation, marketing pages, affiliate sites — this philosophy translates to measurably better performance, lower costs, and zero maintenance headaches.

This guide is everything I’ve learned building with Astro in production across multiple projects, including what nobody tells you about the tradeoffs.

What is Astro framework and why does it matter

Astro is a web framework created by the Astro team (led by Fred K. Schott) that takes a fundamentally different approach to building websites. While most modern frameworks (Next.js, Nuxt, SvelteKit) ship JavaScript to the browser by default, Astro ships pure HTML. Zero kilobytes of JavaScript unless you explicitly opt in.

This isn’t a technical limitation — it’s a deliberate design decision. Most content websites don’t need JavaScript. A blog post doesn’t need React to render. A product description doesn’t need Vue to display text. By removing unnecessary JavaScript, Astro achieves page load speeds that are physically impossible with JavaScript-heavy frameworks.

The island architecture explained

Astro’s “island architecture” is its most innovative feature. Instead of hydrating an entire page with JavaScript (like Next.js does), Astro lets you designate specific interactive components as “islands” of JavaScript in a sea of static HTML.

A practical example from this very site: the entire page you’re reading is static HTML — zero JavaScript. But the search component in the navigation loads JavaScript only when needed. The reading progress bar is a tiny island. Everything else is pure HTML and CSS.

This means:

• 90%+ of the page loads instantly as static HTML
• Interactive components load independently without blocking the page
• Total JavaScript payload is a fraction of what a Next.js site would ship
• Core Web Vitals are green across the board, every time

My 4 production websites built with Astro

Let me walk you through the real sites I’ve built and operate with Astro. These aren’t hypothetical — they’re live, generating traffic, and serving real business purposes.

diegoacero.com (this site)

This personal brand site runs on Astro 5 + Tailwind 4, deployed on Cloudflare Pages. It has 40+ pages, 12+ SEO-optimized blog articles, interactive components (search, reading progress, share buttons), and automated deploy via GitHub Actions.

• Lighthouse scores: 100/100/100/100
• Hosting cost: $0/month
• Build time: ~8 seconds
• Monthly maintenance: Zero. No updates, no patches, no compatibility issues.

alimentos-proteinas.com

A Spanish nutrition blog designed as a linkbuilding asset for my supplement e-commerce store. Built with Astro + Cloudflare Pages, it achieves perfect Lighthouse scores and serves as proof that content sites don’t need WordPress.

• Lighthouse scores: 100/100/100/100
• Pages: 8 published articles
• Purpose: SEO + linkbuilding for Suplenet
• Total cost: $0/month (domain is the only expense)

montessoritoys.info

An English-language Amazon affiliate site about Montessori toys. This is the largest Astro project I’ve built: 1,000+ pages, 697 products, 6 interactive tools, all statically generated.

• Pages: 1,000+ (products, categories, tools, blog)
• Build time: ~45 seconds for 1,000+ pages
• Hosting cost: $0/month on Cloudflare Pages
• Interactive tools: Quiz, comparison engine, age finder, gift finder — all Astro islands

Future: Suplenet migration

My supplement e-commerce (currently WordPress + WooCommerce) has a content layer — a 450+ entry scientific dictionary — that would be dramatically better on Astro. The migration plan is to keep WooCommerce for the transactional layer and move all content to Astro for performance.

Astro vs WordPress: an honest comparison from someone who uses both

I run 2 WordPress sites and 4 Astro sites. This comparison comes from daily experience with both, not from reading documentation.

When to choose Astro over WordPress

Choose Astro when:

• Your site is primarily content (blog, docs, marketing, portfolio)
• Performance is a competitive advantage (SEO, user experience)
• You want zero ongoing costs for hosting and maintenance
• You’re comfortable with or willing to learn Git and terminal basics
• You have AI tools like Claude Code that can handle the technical parts

When WordPress is still the better choice

Keep WordPress when:

• You need e-commerce with cart, checkout, payments, and order management
• Non-technical people need to edit content regularly
• You need dynamic features like user accounts, comments, or real-time data
• Your business depends on specific WordPress plugins that have no alternative

I don’t view this as a competition. In my business, Astro handles content and WordPress handles commerce. They serve different purposes and both do their jobs exceptionally well.

Astro vs Next.js: why I chose Astro for content sites

Next.js is an excellent framework. I use it — my custom ERP (Textti Desk) is built with Next.js + Supabase. But for content sites, choosing Next.js over Astro makes no sense in 2026, and here’s why.

The fundamental difference: Next.js is a React framework that can generate static pages. Astro is a content framework that can use React (or Vue, or Svelte, or anything) when needed. The orientation matters.

With Next.js, you’re paying the React tax on every page — even if that page is a simple blog post that needs zero interactivity. The client-side JavaScript bundle might be 80KB+ before you add a single component. With Astro, a blog post ships exactly 0 bytes of JavaScript unless you choose to add an interactive island.

For my ERP dashboard (Next.js): this makes perfect sense. Every page needs authentication, real-time data, complex forms, and state management. React is justified.

For this blog (Astro): shipping React to display static text would be absurd. The content doesn’t change. The components don’t need state. The page is done when the HTML arrives.

My rule of thumb: if the majority of your pages are static content, use Astro. If the majority are dynamic applications, use Next.js. Don’t let framework popularity drive architecture decisions.

How Astro achieves 100/100 Lighthouse scores consistently

Getting a perfect Lighthouse score with most frameworks requires extensive optimization: code splitting, lazy loading, image compression, critical CSS extraction, and dozens of other techniques. With Astro, 100/100 is the default.

Why Astro is fast by default

1. Zero JavaScript: No framework runtime, no hydration script, no router — just HTML and CSS
2. Image optimization built in: astro:assets automatically resizes, compresses, and serves modern formats (AVIF, WebP)
3. CSS scoping: Styles are scoped per component and automatically bundled — no unused CSS
4. HTML minification: Output is clean, minimal HTML with no framework cruft
5. No client-side routing: Each page is a fresh HTML document — no SPA overhead

Real Lighthouse results from my sites

These aren’t cherry-picked scores from a perfect test run. These are consistent, reproducible scores across all my Astro sites. The WordPress comparison is from my own WordPress sites, which are well-optimized with FlyingPress, Perfmatters, and aggressive caching. They score well for WordPress — but they can’t match zero JavaScript.

MDX: the content format that makes Astro perfect for technical blogs

MDX is Markdown with JSX components. It’s the reason I can write long-form technical content (like this article) and still include interactive comparison tables, score cards, charts, and callout boxes without touching HTML.

How MDX works in Astro

A standard blog post is written in .mdx files with frontmatter (metadata) at the top and content below. You write in Markdown — headings, paragraphs, lists, links — and import custom components where needed.

The workflow for writing an article:

1. Create a new .mdx file in the content directory
2. Add frontmatter (title, description, date, tags, FAQs, etc.)
3. Write content in Markdown
4. Import and use components where you need rich formatting
5. Push to GitHub — deploy is automatic

Why MDX beats WordPress block editor

The WordPress block editor (Gutenberg) is visual and intuitive. But for technical content with strict conventions, MDX is superior:

• Version control: Every article is a Git commit. You can diff, revert, and track changes
• Consistency: Components enforce structure — a comparison table always looks the same
• Speed: Writing in Markdown is faster than clicking through blocks
• Portability: MDX files work in any framework. WordPress content is locked in its database
• AI-friendly: Claude Code can write and edit MDX files directly, understanding the full project context

I’ve written over 400 content entries in WordPress and 40+ pages in Astro/MDX. For structured, convention-driven content, MDX wins decisively.

Deploying Astro on Cloudflare Pages: free hosting that scales

One of the most compelling arguments for Astro is cost. My 4 Astro sites have a combined hosting cost of $0 per month. Not “low cost” — zero.

Cloudflare Pages offers free hosting for static sites with:

• Unlimited bandwidth — no overage charges, ever
• Global CDN — your site is served from 300+ data centers worldwide
• Automatic deploys — push to GitHub, site updates in ~30 seconds
• Custom domains — connect your domain, free SSL
• Preview deployments — every pull request gets its own URL

The deployment workflow I use

My deploy process is fully automated:

1. Write/edit content locally or via Claude Code
2. Commit and push to GitHub
3. GitHub Actions triggers the build
4. Cloudflare Pages deploys the result
5. Site is live globally in ~30 seconds

No server management. No database backups. No SSH access needed. No security patches. No PHP version compatibility issues. The site is static HTML files served from Cloudflare’s edge network.

Compare this to my WordPress sites: ScalaHosting costs $20-50/month, I manage server configurations, worry about plugin compatibility, run backup routines, and spend time on security hardening. Worth it for e-commerce. Unnecessary for content sites.

Building with Astro when you’re not a developer

Here’s the honest truth: Astro requires more technical knowledge than WordPress. You need to be comfortable with a terminal, Git, and basic code editing. But “more technical” doesn’t mean “developer-level” anymore.

I’m not a developer. My JavaScript is a 1-2 out of 10. My PHP is the same. What I have is a clear vision of what I want to build and AI tools that can write the code for me.

How I use Claude Code with Astro

Claude Code is my development environment for Astro projects. The workflow:

1. I describe what I want in plain language (“add a bar chart component that takes items and renders them as horizontal bars”)
2. Claude Code reads my existing project structure and conventions
3. It writes the component, respecting my naming patterns, styling conventions, and file structure
4. I review, test, and commit

The 1-million-token context window is crucial here. Claude Code reads my entire Astro project — layout files, existing components, content schemas, config files — and writes code that fits seamlessly. With a smaller context window, you’d need to explain your project structure in every conversation.

The practical barrier

You need to be comfortable with:

• Terminal: Running npm run dev, npm run build, git push
• File editing: Working with .astro and .mdx files in a code editor
• Git: Basic commit, push, and branch operations
• Troubleshooting: Reading error messages and asking AI for fixes

If these feel intimidating, WordPress is still the right choice. But if you’re willing to spend a weekend learning the basics, Astro becomes accessible — especially with AI assistance.

From experience: I built my first Astro site knowing almost no JavaScript. What I did know was exactly what I wanted the site to do. With AI coding tools, that clarity of vision matters far more than technical depth. The framework handles the complexity; you handle the decisions.

Astro content collections: the type-safe content layer

Astro’s content collections system is what transforms it from a generic static site generator into a content management powerhouse. You define a schema for your content, and Astro validates every piece of content against that schema at build time.

Why content collections matter

In WordPress, there’s nothing stopping you from publishing a blog post without a meta description, without FAQs, or with a broken category slug. In Astro, the build fails if required fields are missing. This means:

• Every article has a title under 45 characters
• Every article has exactly 5 key takeaways
• Every article has 6+ FAQs with the correct format
• Every article has a valid category from a predefined list

This is invaluable when you have strict content conventions (like I do for my sites). The system catches errors before they reach production. For the 1,000+ pages on montessoritoys.info, this validation prevented dozens of formatting issues that would have been invisible in WordPress until a user reported them.

When not to use Astro: honest limitations

Astro is excellent at what it does, but it’s not the right tool for everything. Here are the legitimate limitations:

Specific scenarios where Astro is wrong

1. Full e-commerce with cart and checkout: Use WordPress + WooCommerce or Shopify. I run two WooCommerce stores for this exact reason.

2. Apps with user accounts: Login, dashboards, personalized content — use Next.js or SvelteKit with a backend like Supabase.

3. Sites edited by non-technical people: If your marketing team needs to publish blog posts without touching code, WordPress with a visual editor is still the most practical choice.

4. Real-time features: Chat, notifications, live data — these need WebSockets and server-side logic. Astro can integrate with these via islands, but it’s not built for this.

The custom solution angle: Astro as a SaaS replacement

This is where the Astro framework story connects to a broader business strategy. Every site I build with Astro replaces what would otherwise be a paid hosting plan, a CMS subscription, or a website builder fee.

The savings matter for a solo operator. But the real value is expertise: every Astro site I build teaches me patterns I can apply to client projects. When someone asks “can you build me a fast, SEO-optimized content site?” the answer is yes — in days, not weeks — because I’ve done it four times already.

If you’re considering Astro for your next project, I’ve documented my complete approach in my cases section. And if you’d rather have someone build it for you, my build sprint services include Astro site development with the same 100/100 Lighthouse performance I achieve on my own projects.

Getting started with Astro in 2026: the practical path

If you’ve read this far and want to try Astro, here’s the path I’d recommend:

Week 1: The basics

1. Install Node.js and a code editor (VS Code or similar)
2. Run npm create astro@latest and explore the starter template
3. Understand .astro files: frontmatter (---) for logic, HTML below for markup
4. Create 3-4 static pages to get comfortable with the syntax
5. Deploy to Cloudflare Pages or Vercel (free)

Week 2: Content and components

1. Set up content collections with a blog schema
2. Write your first MDX post with custom components
3. Add Tailwind CSS for styling
4. Create reusable components (header, footer, card, etc.)
5. Build a working blog with 5+ posts

Week 3: Production readiness

1. Add SEO meta tags, Open Graph images, and sitemap
2. Implement RSS feed
3. Set up GitHub Actions for automatic deployment
4. Add search functionality (Pagefind works great with Astro)
5. Optimize images with astro:assets

The AI accelerator

With Claude Code or a similar AI coding tool, you can compress these three weeks into three days. I built the first version of diegoacero.com in a single intensive session with Claude Code. Not because I’m fast — because the AI understands the framework, reads the documentation, and writes valid Astro code on the first attempt.

The Astro framework represents a genuine shift in how content websites should be built. Not because it’s trendy or new, but because it aligns with what actually matters: speed, cost, and maintainability. In 2026, shipping 200KB of JavaScript to display a blog post is not just unnecessary — it’s competitive disadvantage. Astro eliminates that disadvantage by default, and for content-driven businesses, that’s a meaningful edge.