Notes from upgrading this site to Astro 6

Astro 6 shipped on March 10. We moved this site over a few weeks later, once the early 6.0.x patches settled. Short post on what changed, what broke, and the one feature that was genuinely worth the upgrade.

Context

aurabyt.com is a small Astro site. A dozen or so pages, a blog collection, a portfolio collection, hosted on Netlify in SSR mode. Not a stress test, but a realistic example of what a small business site on Astro looks like.

We were on 5.x before. The upgrade was mostly a matter of bumping the version, running the build, and fixing what yelled.

What was painless

Most things. The adapter updated cleanly, the content collections still work the same way, MDX still renders, and the build finished green on the first proper pass. Astro has taken backwards compatibility seriously across major versions and it shows.

The dev server feels noticeably faster. That’s the Vite Environment API refactor doing its job — dev now runs your actual production runtime, so the “works locally, breaks on Netlify” class of bug is genuinely smaller. I ran into that exact bug twice in the last year on 5.x. It was worth an afternoon to stop running into it.

The Fonts API was the real reason to upgrade

The feature we actually cared about was the built-in Fonts API. Before, we were pulling fonts from a CDN — Google Fonts or Bunny Fonts — which meant an extra DNS lookup, an extra TCP handshake, and a request to a third party on every cold visit.

With the new API, you declare your fonts in astro.config.mjs and Astro handles the rest: downloads them at build time, self-hosts them, generates the right @font-face rules, and wires up preload hints for the weights you use above the fold.

Concretely, on this site:

• Two external requests gone.
• A measurable LCP improvement on cold loads from mobile, especially on networks where the third-party font host wasn’t already cached.
• One fewer thing to trust.

The API is also short enough that the whole font configuration is maybe fifteen lines. It’s the kind of feature that should have been built in from the start.

What did break

Two things, both minor:

• A couple of our scroll-reveal animations were using the old view-transition hook signature. Trivial rename.
• A third-party integration for image optimisation hadn’t published an Astro 6 compatible version at the time of upgrade. We were able to swap to Astro’s built-in image handling without much fuss.

Nothing that required rethinking anything structural.

Should you upgrade?

If you’re running a production Astro site in 2026, yes, at your convenience. The dev server improvements alone are worth it, and the Fonts API is a real win. There’s no reason to rush — 5.x is stable and supported — but I’d plan for it within a quarter.

If you’re on 4.x or earlier, the upgrade path is longer because the content collections syntax changed between 4 and 5. That’s a separate afternoon.

The Cloudflare acquisition in January raised some questions about long-term direction. From what’s shipped since then, the framework is still MIT-licensed, still open source, still prioritising the things that make it good at static and hybrid sites. We’re not planning to move off it.

If you’re trying to decide between frameworks for a new small-business site in 2026, Astro remains our default. Send us a note if you want a second opinion on your stack.