Astro v6 Upgrade Guide

Quick Start

1. Check Node version: Astro v6 requires Node 22.12.0+ (

   node -v

   )
2. Run upgrade:

   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

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

LegacyContentConfigError

src/content/config.ts

src/content.config.ts

ContentCollectionMissingALoaderError

loader

ContentCollectionInvalidTypeError

type: 'content'

type: 'data'

GetEntryDeprecationError

getEntryBySlug()

getDataEntryById()

getEntry()

ContentSchemaContainsSlugError

.slug

.id

ViewTransitions

ClientRouter

Astro.glob

import.meta.glob()

Deep Dive Files

Load these only when needed:

.email()

.url()

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