Tried Upgrading to Astro 6, Had to Roll Back

33 views

Hey everyone, it’s Cody.

I tried upgrading this site from Astro 5 to Astro 6, and ended up rolling back to Astro 5. Here’s what happened.

Key Changes in Astro 6

  • Upgrade to Vite 7
  • Upgrade to Zod 4 (import path for z changed)
  • Upgrade to Shiki 4
  • Legacy Content Collections API fully removed
  • ViewTransitions renamed to ClientRouter
  • Astro.glob() removed

See the official migration guide for details.

What I Did

1. Deploy semver-range Updates First

Rather than jumping straight to the major upgrade, I first updated within the existing version ranges.

astro            5.16.13 → 5.18.1
wrangler         4.60.0  → 4.72.0
@astrojs/rss     4.0.15  → 4.0.17
@astrojs/sitemap 3.7.0   → 3.7.1

After confirming a successful deploy, I moved on to the next step.

2. Upgrade to Astro 6

Used pnpm dlx @astrojs/upgrade to upgrade everything at once.

astro                5.18.1  → 6.0.2
@astrojs/cloudflare  12.6.13 → 13.0.2
@astrojs/mdx         4.3.14  → 5.0.0

The only code change needed was updating the z import path (from astro:content to astro/zod). The local build passed without issues.

3. 404 on Cloudflare Pages

However, after deploying to Cloudflare Pages, the entire site returned 404.

The root cause was a change in the build output structure of @astrojs/cloudflare 13. In v12, _worker.js and static files were placed directly under dist/. In v13, they’re split into dist/client/ (static files) and dist/server/ (worker).

For Cloudflare Pages to recognize this new structure, pages_build_output_dir needs to be set in wrangler.toml. But adding this causes a build error due to an ASSETS binding name conflict.

The name 'ASSETS' is reserved in Pages projects.
Please use a different name for your Assets binding.

The prerender worker config generated by @astrojs/cloudflare 13 uses an ASSETS binding that clashes with a Pages reserved name. This appears to be a bug in the adapter.

Conclusion

The Astro 6 migration itself was straightforward, but there’s currently a compatibility issue with Cloudflare Pages, so I rolled back to Astro 5.

I plan to try the upgrade again once the @astrojs/cloudflare adapter is fixed.

Thanks for reading!