Astro v6 Upgrade Guide

Quick Start

1. Check Node version: Astro v6 requires Node 22.12.0+ (node -v)
2. Run upgrade:
   bashCopy

   npx @astrojs/upgrade    # npm
   pnpm dlx @astrojs/upgrade  # pnpm
   

3. Check for legacy content collections (see below)
4. Fix any errors using this guide

Check: Legacy Content Collections

Before upgrading, check if the project needs content collection migration. Most v5 projects already use the Content Layer API and won't need changes.

Decision tree:

1. Does src/content/config.{js,ts,mjs,mts} exist?

   • Yes → needs migration (legacy config location)

2. Are there content folders in src/content/ but no config file anywhere?

   • Yes → needs migration (implicit legacy collections)

3. Otherwise, check src/content.config.{js,ts,mjs,mts} for:

   • Any collection without a loader property → needs migration
   • Any collection with type: set → needs migration

If any of the above apply, load content-collections.md and follow the migration steps.

Quick Fixes

These are simple renames/replacements. Apply directly:

ViewTransitions → ClientRouter

---
// Before
import { ViewTransitions } from 'astro:transitions';
// After
import { ClientRouter } from 'astro:transitions';
---

<!-- Before -->
<ViewTransitions />
<!-- After -->
<ClientRouter />

Remove handleForms prop if present - it's now default behavior.

Astro.glob() → import.meta.glob()

---
// Before
const posts = await Astro.glob('./posts/*.md');

// After
const posts = Object.values(import.meta.glob('./posts/*.md', { eager: true }));
---

Zod imports

// Before (deprecated)
import { z } from 'astro:content';
import { z } from 'astro:schema';

// After
import { z } from 'astro/zod';

If using Zod validation extensively or if you encounter Zod errors, see zod.md for Zod 4 syntax changes.

Deprecated APIs

// Astro.site in getStaticPaths → import.meta.env.SITE
export function getStaticPaths() {
  const site = import.meta.env.SITE;  // was Astro.site
}

// Astro.generator → just remove it

// import.meta.env.ASSETS_PREFIX → astro:config/server
import { build } from 'astro:config/server';
const prefix = build.assetsPrefix;

Removed: emitESMImage

// Before
import { emitESMImage } from 'astro/assets/utils';
// After
import { emitImageMetadata } from 'astro/assets/utils';

Error Quick Reference

Deep Dive Files

Load these only when needed:

Experimental Flags to Remove

These flags are now stable or default. Remove from config:

export default defineConfig({
  experimental: {
    // Remove all of these:
    liveContentCollections: true,
    preserveScriptOrder: true,
    staticImportMetaEnv: true,
    headingIdCompat: true,
    failOnPrerenderConflict: true,  // Use prerenderConflictBehavior instead
  },
});

Resources

• Astro v6 Blog Post
• Content Layer Deep Dive