Upgrade to Astro v6

This guide will help you migrate from Astro v5 to Astro v6.

Need to upgrade an older project to v5 first? See our older migration guide.

Need to see the v5 docs? Visit this older version of the docs site (unmaintained v5.xx snapshot).

Upgrade Astro

Update your project’s version of Astro to the latest version using your package manager:

npm

# Upgrade Astro and official integrations together
npx @astrojs/upgrade

pnpm

# Upgrade Astro and official integrations together
pnpm dlx @astrojs/upgrade

Yarn

# Upgrade Astro and official integrations together
yarn dlx @astrojs/upgrade

You can also upgrade your Astro integrations manually if needed, and you may also need to upgrade other dependencies in your project.

Need to continue?

After upgrading Astro, you may not need to make any changes to your project at all!

But, if you notice errors or unexpected behavior, please check below for what has changed that might need updating in your project.

Astro v6.0 includes potentially breaking changes, as well as the removal and deprecation of some features.

If your project doesn’t work as expected after upgrading to v6.0, check this guide for an overview of all breaking changes and instructions on how to update your codebase.

See the Astro changelog for full release notes.

Dependency Upgrades

Any major upgrades to Astro’s dependencies may cause breaking changes in your project.

Node 22

कार्यान्वयन PR: feat!: drop node 18 and 20 (#14427)

Node 18 reached its End of Life in March 2025 and Node 20 is scheduled to reach its End of Life in April 2026.

Astro v6.0 drops Node 18 and Node 20 support entirely so that all Astro users can take advantage of Node’s more modern features.

What should I do?

Check that both your development environment and your deployment environment are using Node 22.12.0 or higher.

1. Check your local version of Node using:

   node -v

2. Check your deployment environment’s own documentation to verify that they support Node 22.

   You can specify Node 22.12.0 for your Astro project either in a dashboard configuration setting or a .nvmrc file.

   .nvmrc

   22.12.0

Legacy

The following features are now considered legacy features. They should function normally but are no longer recommended and are in maintenance mode. They will see no future improvements and documentation will not be updated. These features will eventually be deprecated, and then removed entirely.

Deprecated

The following deprecated features are no longer supported and are no longer documented. Please update your project accordingly.

Some deprecated features may temporarily continue to function until they are completely removed. Others may silently have no effect, or throw an error prompting you to update your code.

Removed

The following features have now been entirely removed from the code base and can no longer be used. Some of these features may have continued to work in your project even after deprecation. Others may have silently had no effect.

Projects now containing these removed features will be unable to build, and there will no longer be any supporting documentation prompting you to remove these features.

Removed: <ViewTransitions /> component

कार्यान्वयन PR: Remove deprecated ViewTransitions component (#14400)

In Astro 5.0, the <ViewTransitions /> component was renamed to <ClientRouter /> to clarify the role of the component. The new name makes it more clear that the features you get from Astro’s <ClientRouter /> routing component are slightly different from the native CSS-based MPA router. However, a deprecated version of the <ViewTransitions /> component still existed and may have functioned in Astro 5.x.

Astro 6.0 removes the <ViewTransitions /> component entirely and it can no longer be used in your project. Update to the <ClientRouter /> component to continue to use these features.

What should I do?

Replace all occurrences of the ViewTransitions import and component with ClientRouter:

src/layouts/MyLayout.astro

import { ViewTransitions } from 'astro:transitions';
import { ClientRouter } from 'astro:transitions';

<html>
  <head>
    ...
   <ViewTransitions />
   <ClientRouter />
  </head>
</html>

Read more about view transitions and client-side routing in Astro.

Removed: emitESMImage()

कार्यान्वयन PR: feat!: remove emitESMImage() (#14426)

In Astro 5.6.2, the emitESMImage() function was deprecated in favor of emitImageMetadata(), which removes two deprecated arguments that were not meant to be exposed for public use: _watchMode and experimentalSvgEnabled.

Astro 6.0 removes emitESMImage() entirely. Update to emitImageMetadata() to keep your current behavior.

What should I do?

Replace all occurrences of the emitESMImage() with emitImageMetadata() and remove unused arguments:

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

const imageId = '/images/photo.jpg';
const result = await emitESMImage(imageId, false, false);
const result = await emitImageMetadata(imageId);

Read more about emitImageMetadata().

Removed: Astro.glob()

कार्यान्वयन PR: feat!: remove Astro.glob (#14421)

In Astro 5.0, Astro.glob() was deprecated in favor of using getCollection() to query your collections, and import.meta.glob() to query other source files in your project.

Astro 6.0 removes Astro.glob() entirely. Update to import.meta.glob() to keep your current behavior.

What should I do?

Replace all use of Astro.glob() with import.meta.glob(). Note that import.meta.glob() no longer returns a Promise, so you may have to update your code accordingly. You should not require any updates to your glob patterns.

src/pages/blog.astro

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

{posts.map((post) => <li><a href={post.url}>{post.frontmatter.title}</a></li>)}

Where appropriate, consider using content collections to organize your content, which has its own newer, more performant querying functions.

You may also wish to consider using glob packages from NPM, such as fast-glob.

Learn more about importing files with import.meta.glob.

Removed: routes on astro:build:done hook (Integration API)

कार्यान्वयन PR: feat: cleanup integration api (#14446)

In Astro 5.0, accessing routes on the astro:build:done hook was deprecated.

Astro 6.0 removes the routes array passed to this hook entirely. Instead, the astro:routes:resolved hook should be used.

What should I do?

Remove any instance of routes passed to astro:build:done and replace it with the new astro:routes:resolved hook. Access distURL on the newly exposed assets map:

my-integration.mjs

const integration = () => {
    let routes
    return {
        name: 'my-integration',
        hooks: {
            'astro:routes:resolved': (params) => {
                routes = params.routes
            },
            'astro:build:done': ({
                routes
                assets
            }) => {
                for (const route of routes) {
                    const distURL = assets.get(route.pattern)
                    if (distURL) {
                        Object.assign(route, { distURL })
                    }
                }
                console.log(routes)
            }
        }
    }
}

Learn more about the Integration API astro:routes:resolved hook for building integrations.

Removed: entryPoints on astro:build:ssr hook (Integration API)

कार्यान्वयन PR: feat: cleanup integration api (#14446)

In Astro 5.0, functionPerRoute was deprecated. That meant that entryPoints on the astro:build:ssr hook was always empty.

Astro 6.0 removes the entryPoints map passed to this hook entirely.

What should I do?

Remove any instance of entryPoints passed to astro:build:ssr:

my-integration.mjs

const integration = () => {
    return {
        name: 'my-integration',
        hooks: {
            'astro:build:ssr': (params) => {
                someLogic(params.entryPoints)
            },
        }
    }
}

Changed Defaults

Some default behavior has changed in Astro v5.0 and your project code may need updating to account for these changes.

In most cases, the only action needed is to review your existing project’s deployment and ensure that it continues to function as you expect, making updates to your code as necessary. In some cases, there may be a configuration setting to allow you to continue to use the previous default behavior.

Changed: i18n.routing.redirectToDefaultLocale default value

In Astro v5.0, the i18n.routing.redirectToDefaultLocale default value was true. When combined with the i18n.routing.prefixDefaultLocale default value of false, the resulting redirects could cause infinite loops.

In Astro v6.0, i18n.routing.redirectToDefaultLocale now defaults to false. Additionally, it can now only be used if i18n.routing.prefixDefaultLocale is set to true.

What should I do?

Review your Astro i18n config as you may now need to explicitly set values for redirectToDefaultLocale and prefixDefaultLocale to recreate your project’s previous behavior.

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  i18n: {
    routing: {
      prefixDefaultLocale: true,
      redirectToDefaultLocale: true
    }
  }
})

Learn more about Internationalization routing.

Breaking Changes

The following changes are considered breaking changes in Astro v5.0. Breaking changes may or may not provide temporary backwards compatibility. If you were using these features, you may have to update your code as recommended in each entry.

Community Resources

Know a good resource for Astro v5.0? Edit this page and add a link below!

Known Issues

Please check Astro’s issues on GitHub for any reported issues, or to file an issue yourself.