astro-v6-upgrade

Astro v6 Upgrade Guide

This skill is based on the final Astro v6 upgrade guide and the Cloudflare adapter v13 migration.

Quick Start

1. Check Node version: Astro v6 requires Node 22.12.0 or higher. Check with node -v, and update .nvmrc / deployment config if needed. Ensure that you include CI workflows in this update if applicable.
2. Upgrade Astro and official integrations together:

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

3. Check for legacy content collections (see below). v5 supported legacy collections via backwards-compat even without the flag. v6 removes that entirely.
4. If deploying to Cloudflare: the @astrojs/cloudflare v13 upgrade has significant changes. Load cloudflare.md.
5. Fix any errors using this guide.

Check: Legacy Content Collections

Before upgrading, check if the project needs content-collection migration. Many v5 projects silently relied on legacy backwards-compat (no flag required) and will break on v6.

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.
4. Does the code use getEntryBySlug(), getDataEntryById(), entry.slug, or entry.render()?
   • Yes → needs migration.

If any apply, load content-collections.md.

Temporary escape hatch (if migration can't happen immediately):

export default defineConfig({
  legacy: {
    collectionsBackwardsCompat: true,
  },
});

This preserves the v4-style behavior: src/content/config.ts location, type: 'content'/'data' without loaders, entry.slug, entry.render(), path-based IDs. It is explicitly a migration helper and should be removed as soon as the project moves to the Content Layer API.

Note: The old legacy.collections: true flag is removed. Remove it if present.

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 />

Also remove the handleForms prop if present - it is now removed entirely (form handling has been built in by default since v4).

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

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

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

Consider content collections for content, or fast-glob for runtime globbing.

Zod imports

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

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

astro:schema and z from astro:content are deprecated - import z from astro/zod directly. For Zod 4 API changes (string formats, error messages, transforms), see zod.md.

Deprecated APIs

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

// Astro.generator in getStaticPaths → 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';
const result = await emitESMImage(imageId, false, false);

// After
import { emitImageMetadata } from 'astro/assets/utils';
const result = await emitImageMetadata(imageId);

Removed: <ClientRouter /> handleForms prop

Forms are handled automatically since v4. Remove the prop:

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

Removed: prefetch() with option

// Before
prefetch('/about', { with: 'fetch' });
// After
prefetch('/about');

Removed: rewrite() from Actions context

// Inside an Action handler - remove any context.rewrite() calls.
// Use custom endpoints instead if you need redirect/rewrite behavior.

Removed: exposed astro:transitions internals

If imported, remove these or use plain string event names:

// Before
import {
  createAnimationScope,
  isTransitionBeforePreparationEvent,
  TRANSITION_AFTER_SWAP,
} from 'astro:transitions/client';

console.log(isTransitionBeforePreparationEvent(event));
console.log(TRANSITION_AFTER_SWAP);

// After
console.log(event.type === 'astro:before-preparation');
console.log('astro:after-swap');
// createAnimationScope has no replacement - remove it.

Removed: exposed astro:actions internals

serializeActionResult and deserializeActionResult are no longer exported from astro:actions. Use getActionContext() in middleware:

import { defineMiddleware } from 'astro:middleware';
import { getActionContext } from 'astro:actions';

export const onRequest = defineMiddleware(async (context, next) => {
  const { serializeActionResult, deserializeActionResult } = getActionContext(context);
  // ...
});

Also remove imports of: ACTION_ERROR_CODES, ActionInputError, appendForwardSlash, astroCalledServerError, callSafely, formDataToObject, getActionQueryString, type Actions, type ActionAccept, type AstroActionContext, type SerializedActionResult.

Removed: CommonJS config files

astro.config.cjs and astro.config.cts are no longer supported. Rename to .mjs, .js, .ts, or .mts.

Changed: getStaticPaths params must be strings

// Before - numbers were auto-stringified
return [{ params: { id: 1 } }];
// After - must be string or undefined
return [{ params: { id: "1" } }];

Changed: Session driver config

// Before
import { defineConfig } from 'astro/config';

export default defineConfig({
  session: {
    driver: 'redis',
    options: { url: process.env.REDIS_URL },
  },
});

// After
import { defineConfig, sessionDrivers } from 'astro/config';

export default defineConfig({
  session: {
    driver: sessionDrivers.redis({ url: process.env.REDIS_URL }),
  },
});

Removed: Percent-encoding in route filenames

%25 is no longer allowed in filenames. Rename any src/pages/test%25file.astro etc.

Error Quick Reference

Error	Fix
LegacyContentConfigError	Move src/content/config.ts → src/content.config.ts
ContentCollectionMissingALoaderError	Add loader to collection - see content-collections.md
ContentCollectionInvalidTypeError	Remove type: 'content' or type: 'data' from collection
GetEntryDeprecationError	Replace getEntryBySlug()/getDataEntryById() with getEntry()
ContentSchemaContainsSlugError	Replace .slug with .id, use .filePath for filename
Cannot find ViewTransitions	Use ClientRouter (see above)
Cannot find Astro.glob	Use import.meta.glob() (see above)
Node version error	Upgrade to Node 22.12.0+
Zod validation errors	Check zod.md for Zod 4 changes
Cloudflare: Astro.locals.runtime is undefined	See cloudflare.md - access moved

Deep Dive Files

Load these only when needed:

File	When to load
content-collections.md	Legacy content collections need migration
zod.md	Using Zod schemas with .email(), .url(), custom errors, transforms, or .default()
behavior-changes.md	Subtle issues: i18n redirects, script/style order, env vars, image sizing, Vitest, Shiki, SVGs
integration-api.md	Building integrations or adapters
cloudflare.md	Deploying to Cloudflare Workers / Pages, upgrading @astrojs/cloudflare to v13

Experimental Flags to Remove

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

export default defineConfig({
  experimental: {
    // Remove all of these - now stable or default:
    csp: true,                     // stable: use `security.csp`
    fonts: true,                   // stable
    liveContentCollections: true,  // stable
    preserveScriptOrder: true,     // now default - see behavior-changes.md
    staticImportMetaEnv: true,     // now default - see behavior-changes.md
    headingIdCompat: true,         // now default - see behavior-changes.md
    failOnPrerenderConflict: true, // renamed to `prerenderConflictBehavior`
  },
});

Official Adapter Upgrades

All official adapters need a major upgrade alongside Astro v6 (to accompany Vite 7 + Environment API):

• @astrojs/cloudflare → v13 (significant breaking changes - see cloudflare.md)
• @astrojs/netlify
• @astrojs/node
• @astrojs/vercel

Resources

• Astro v6 Upgrade Guide
• Astro v6 Blog Post
• Content Layer Deep Dive
• Cloudflare adapter docs