Migrating to Astro v6

Astro v6 is here with some exciting updates and breaking changes. If you’re running a site on Astro v5 or earlier, here’s what you need to know to make the jump.

What’s New in v6

The biggest changes are the requirement for Node.js 22.12.0 or higher, the upgrade to Vite 7.0, and the mandatory use of Content Collections with the Content Layer API. Astro has also removed support for Astro.glob() in favor of more modern alternatives.

Check Your Node Version

Before you start, make sure you’re running Node.js 22.12.0 or higher. Node 18 and 20 have reached end of life and are no longer supported.

node -v

If you’re below v22, update your Node version before proceeding.

Migration Steps

Update Dependencies

First, update your Astro version and related packages in your package.json:

{
  "dependencies": {
    "astro": "^6.1.3",
    "@astrojs/vercel": "^10.0.4"
  },
  "devDependencies": {
    "@astrojs/tailwind": "^6.0.2"
  }
}

Then run:

pnpm install

Replace Astro.glob() with Content Collections

This is the biggest change. If you were using Astro.glob() to load markdown files, you need to migrate to Content Collections.

Old approach:

const posts = await Astro.glob('../content/blogs/*.md');

New approach:

Create a src/content.config.ts file:

import { defineCollection } from "astro:content";
import { glob } from "astro/loaders";
import { z } from "astro/zod";

const blogs = defineCollection({
  loader: glob({ pattern: "*.md", base: "./src/blogs" }),
  schema: z.object({
    slug: z.string(),
    title: z.string(),
    author: z.string(),
    excerpt: z.string(),
    date: z.coerce.date(),
    image: z.string().optional(),
  }),
});

export const collections = { blogs };

Then move your markdown files from src/content/blogs/ to src/blogs/.

In your pages, replace Astro.glob() with getCollection():

import { getCollection } from "astro:content";

const posts = await getCollection("blogs");

For dynamic routes like [slug].astro:

import { getCollection, render } from "astro:content";

export async function getStaticPaths() {
  const posts = await getCollection("blogs");

  return posts.map((post) => ({
    params: {
      slug: post.data.slug,
    },
    props: {
      post,
    },
  }));
}

const { post } = Astro.props;
const { Content } = await render(post);

Update Vercel Adapter Import

If you’re using the Vercel adapter, update the import in your astro.config.mjs:

Old:

import vercel from "@astrojs/vercel/static";

New:

import vercel from "@astrojs/vercel";

Replace ViewTransitions with ClientRouter

The ViewTransitions component has been replaced with ClientRouter:

Old:

import { ViewTransitions } from "astro:transitions";

<ViewTransitions />

New:

import { ClientRouter } from "astro:transitions";

<ClientRouter />

Fix Deprecated Zod Imports

If you’re using Zod for schema validation, update your imports:

Old:

import { z } from "astro:content";

New:

import { z } from "astro/zod";

Verify Everything Works

Once you’ve made these changes, run your build to make sure everything works:

pnpm build

Check for type errors:

pnpm astro check

If you see 0 errors, you’re good to go!

Final Thoughts

The migration to Astro v6 is straightforward if you follow these steps. The Content Collections API might seem like extra work at first, but the type safety and validation are worth it. Plus, you’ll be ready for future Astro updates that build on this foundation.

If you run into issues, the Astro v6 migration guide has additional details for edge cases.

Happy building!

References

https://docs.astro.build/en/guides/upgrade-to/v6/ https://docs.astro.build/en/guides/content-collections/