"We took over an Astro site built by another agency, but the version is so old we're afraid to touch it." This is an extraordinarily common inquiry in client maintenance. Opening package.json reveals an Astro installation frozen several major versions back, with dependencies locked into outdated versions alongside it. While it runs for now, attempting an upgrade leaves the blast radius completely unpredictable, so time slips by with no one taking the first step. With the arrival of Astro 7.0, these sites are forced to make a definitive decision.
Version 7.0 is far more than an incremental update. The compiler in .astro has migrated from Go to Rust, meaning unclosed tags and unquoted attributes that previously passed silently now trigger fatal build errors. The bundler has also transitioned to Vite 8 (Rolldown); while builds are substantially faster, neglected legacy sites will run into more roadblocks during migration. In this article, building on our work handling successive client upgrades across 6.2, 6.3, and 6.4, we examine how to decide whether to upgrade an inherited Astro site to 7.0 or rebuild it on a modern SSG foundation.
What breaks in 7.0
In client development, breaking changes demand attention long before shiny new features. When updating inherited sites, this is invariably where teams hit a wall.
The most significant change is that the Rust-based compiler enforces strict HTML syntax. The previous Go-based compiler silently tolerated and auto-corrected malformed markup such as <div>Hello (missing closing tags) or <div class="Hello > (unclosed attributes). In 7.0, these cause build errors, making matching closing tags mandatory for all elements except void elements (such as <br>). The older and larger a site, the more likely such "malformed but previously functional HTML" lurks inside markdown content or templates, surfacing simultaneously during migration.
| Change | Consequence | Impact on custom development |
|---|---|---|
| Rust-based compiler | Missing closing tags and unclosed attributes trigger build errors | Older templates require more code adjustments |
| Vite 8 / Rolldown | Bundler consolidated into Rolldown | Custom configurations and plugins assuming esbuild or Rollup must be verified |
Removal of @astrojs/db | CLI commands such as astro db removed entirely | Sites using databases must migrate to SQLite or Drizzle |
Another easily overlooked change is the complete removal of @astrojs/db. Deprecated in 6.4.5, it has been formally eliminated in 7.0 alongside CLI commands like astro db, astro login, and astro link. Sites relying on it must transition to Node.js's built-in SQLite (available from Node v22.5.0 onward) or Drizzle ORM. On inherited projects, clients often do not even know whether Astro DB was implemented, meaning work begins with auditing existing dependencies.
Additionally, in Vite 8, the Rust-based Rolldown bundler unifies and replaces esbuild and Rollup. Standard configurations reap immediate performance rewards, but sites with custom Vite plugins or settings tailored to Rollup require individual verification. Because inherited sites frequently contain bespoke setups left behind by predecessors, testing them against actual builds is essential.
A practical motivation: upgrading brings speed
While breaking changes can feel daunting, there is a compelling reason to upgrade to 7.0: performance.
The Rust-based .astro compiler, overhauled Markdown and MDX processing, a queue-based rendering engine, and Vite 8 with Rolldown combine to produce visibly faster build times. For content-heavy media sites or sprawling corporate portals, shorter build times directly improve developer and editor experience. Shortening deployments that once took minutes lowers the friction for publishing content, boosting update frequency. While distinct from runtime rendering metrics like Core Web Vitals, faster development turnaround is a substantial operational asset in client maintenance. For guidance on defining page performance metrics, see our Core Web Vitals guide.
Regarding routing, Advanced Routing—introduced experimentally in 6.3—is now enabled by default in 7.0. Placing an entry point at src/fetch.ts lets you control Astro's entire request pipeline with the same familiarity as src/middleware.ts. Furthermore, route caching flags from the 6.x series have stabilized, joined by CDN cache providers (some in private beta) that pass cache headers directly to edge hosts across Netlify, Vercel, and Cloudflare. That said, for corporate sites deployed as pure static sites (SSG), these features may offer little direct benefit. In client engagements, isolating which features your site actually uses before deciding on adoption is the most practical path forward.
Upgrading versus rebuilding
Here lies the central question: when facing an inherited site, should you upgrade it to 7.0 or rebuild it on a modern SSG? The decision involves more than just how many versions behind it sits.
Upgrading smoothly is realistic when a site is only one or two versions behind, does not depend on custom Vite setups or Astro DB, and has relatively clean template HTML. In such cases, upgrading incrementally through intermediate major versions without skipping is the safest approach. Across our own engagements, we have methodically stepped through migrating to 6.2, updating to 6.3 alongside Starlight 0.39, and advancing to 6.4. Addressing breaking changes step by step per official upgrade guides, verifying that builds pass and visual output matches before moving forward, minimizes project risk.
Conversely, there are telltale signs that you should consider rebuilding. If custom Vite plugins from previous vendors are deeply intertwined with no guarantee of running on Rolldown, if business data resides in Astro DB requiring migration planning, or if templates are riddled with malformed HTML throwing hundreds of Rust compiler errors, rebuilding may prove far more cost-effective. Keeping the existing design and content while rebuilding on a clean architecture often saves money over forcing an upgrade. When the cost to upgrade approaches the cost to rebuild, it is time to evaluate a complete rebuild.
On a B2B corporate site GleamHub inherited last year (client name withheld), Astro had stalled several generations back, tangled in bespoke Vite settings and custom Markdown pipelines. An initial test build on the latest version unleashed a torrent of compiler errors and plugin incompatibilities, where fixing one issue triggered another. Ultimately, we preserved the content collections and image assets, rebuilding only the layouts and build configuration on a clean Astro setup. This delivered predictable engineering hours and left behind a clean foundation that future maintainers could easily navigate. Recognizing that we shouldn't force everything into a single upgrade, and choosing to rebuild broken foundations, paid off.
Start by building 7.0 locally
Whichever path you take, the first step must be measurement, not speculation. Test existing dependencies and templates against 7.0 with an actual build to quantify errors. Deciding a project is dangerous because it is old or safe because it still runs invariably skews project estimates.
Specifically, create a verification branch, update Astro to 7.0, and run npm run build. Observe how many unclosed tag errors the Rust compiler reports, check if Vite 8 fails on plugins, and verify whether @astrojs/db dependencies remain. Viewing error counts and categories replaces guesswork with hard data to decide whether to fix issues incrementally or start fresh. Because Node.js runtime requirements have also advanced, make sure your build pipeline (such as Cloud Build or CI) runs on an active even-numbered LTS release.
If you are dealing with an inherited Astro site that has fallen behind, want to upgrade but fear breaking changes, or need an objective assessment on whether to rebuild, please reach out via GleamHub's contact form. We will run test builds against 7.0, diagnose error volumes and causes, and deliver an estimate outlining whether an incremental upgrade, a partial refactor, or a complete rebuild offers the most cost-effective path.
Sources
- Upgrade to Astro v7 － Astro Docs
- Astro 7.0 － Astro Blog
- Route caching － Astro Docs
- feat: remove @astrojs/db (#17010) － withastro/astro
- feat: make the Rust compiler the only option (#16462) － withastro/astro
- Astro 7.0 brings Vite 8, performance boost, advanced routing, route caching & AI features － AlternativeTo
