Should I upgrade to Astro 4 to 5 Upgrade now?
Plan Astro upgrades that must absorb Vite 6 and Astro 5 behavior changes without breaking integrations and build plugins.
Blockers
- Astro 5 upgrades the framework to Vite 6.
- If you use .mdx, Astro 5 requires @astrojs/mdx v4.0.0.
- Astro 5 introduces the new Content Layer API and changes legacy collection behavior.
- Astro 5 removes or changes adapter-facing features including functionPerRoute and supportedAstroFeatures.assets.
- Astro 5 changes integration APIs, including the old routes access pattern on astro:build:done.
Who this is for
- small-team
- monorepo
Candidates
One-step Astro 5 upgrade with synchronized official integrations
Astro 5 upgrades the framework to Vite 6 and the official migration guide recommends upgrading Astro and official integrations together with `@astrojs/upgrade`. As of 2026-04-03, Astro and Vite are open-source projects with no framework license cost; deployment pricing depends on the adapter target, so check official hosting docs. This path fits projects that mostly use official adapters and integrations and can absorb the Vite 6 jump in one release window. The main blocker-level checks are Vite-specific plugins or config, `@astrojs/mdx` compatibility, and deprecated Astro APIs such as `Astro.glob()`.
When to choose
Use this when you want the shortest path off Astro 4 and your stack is mostly official Astro packages plus standard Vite plugins. The decisive factor is whether you can audit and update all Vite-specific plugins and official integrations in the same change set.
Tradeoffs
Fastest migration and least time spent on temporary compatibility layers, but it concentrates framework, bundler, and integration risk into one release.
Cautions
If you use `.mdx`, Astro 5 requires `@astrojs/mdx` v4.0.0. Vite 6 changed low-level behavior around `resolve.conditions`, Sass uses the modern API by default, TypeScript PostCSS configs now need `tsx` or `jiti`, and custom `resolve.conditions` values must include the new defaults. Deprecated Astro APIs like `Astro.glob()` and integration hooks such as `routes` on `astro:build:done` should be removed before cutover.
Two-phase Astro 5 adoption using legacy content-collection compatibility first
Astro 5 introduces the new Content Layer API but still allows a transitional path for old collections, including a `legacy.collections` flag and backward compatibility for many existing `src/content` setups. As of 2026-04-03, Astro and Vite remain open-source with no framework license fee; the cost is migration effort and possible adapter or CI retesting. This path is designed for teams whose main upgrade blocker is content collections rather than the Vite 6 core bump itself. It lets you land Astro 5 first, then move collection definitions to `src/content.config.ts`, replace `slug` assumptions with `id`, and switch from entry `.render()` to `render()` later.
When to choose
Use this when the Vite 6 jump is acceptable but your content model would otherwise delay the Astro 5 upgrade. The decisive factor is whether content collections are the dominant migration risk and you need a staged rollout.
Tradeoffs
Reduces immediate migration scope and lowers content-model risk, but it preserves technical debt because legacy collections are in maintenance mode and slated for eventual removal.
Cautions
Legacy collection behavior is not identical: underscore-prefixed filenames no longer suppress route building, generated collection ordering can be non-deterministic, `image().refine()` is not supported, and some `getEntry()` typing becomes less strict. You should also replace `Astro.glob()` with `import.meta.glob()` or collection queries because `Astro.glob()` is deprecated in Astro 5.
Custom adapter and plugin hardening before the Astro 5 cutover
Astro 5 is manageable for application code, but custom adapters and deep Vite integrations are the highest-risk area because Astro 5 changes adapter and integration APIs while Vite 6 refactors internals around the Environment API and replaces the old experimental Vite Runtime API with the Module Runner API. As of 2026-04-03, there is no framework pricing impact to this path; the cost is engineering time spent on plugin and adapter validation. This approach treats the Astro 4 to 5 move as an ecosystem-compatibility exercise first and an application upgrade second. It is the safest route for teams with bespoke deployment adapters, build hooks, or Vite plugin logic.
When to choose
Use this when custom adapters, integration hooks, SSR behavior, or low-level Vite APIs are part of your stack. The decisive factor is whether your release can tolerate application churn but not a broken build pipeline or adapter contract.
Tradeoffs
Best for reducing unknown build-time regressions, but slower than a straightforward app upgrade because you must validate plugin and adapter contracts before cutting over.
Cautions
Astro 5 removes or changes adapter-facing features including `functionPerRoute`, `supportedAstroFeatures.assets`, and the old `routes` access pattern on `astro:build:done`. Vite 6 also changes SSR-related behavior and custom condition handling, so plugins that depend on internal Vite behavior or deprecated runtime APIs need explicit review.
Try with your AI agent
$ npm install -g pocketlantern $ pocketlantern init # Restart Claude Code, Cursor, or your MCP client, then ask: # "Should I upgrade to Astro 4 to 5 Upgrade now?"