Upgrade to Astro v7

Using a coding agent?

Copy this prompt to upgrade your project:

Upgrade my Astro project to v7. Follow the migration guide at
https://v7.docs.astro.build/en/guides/upgrade-to/v7/

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

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

Need to see the v6 docs? Visit this older version of the docs site (unmaintained v6 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 beta

pnpm

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

Yarn

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

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 v7.0 includes potentially breaking changes, as well as the removal of some previously deprecated features.

If your project doesn’t work as expected after upgrading to v7.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.

Breaking Changes

Dependency Upgrades

Vite 8

Astro v7.0 upgrades to Vite 8 as the development server and production bundler.

What should I do?

If you are using Vite-specific plugins, configuration, or APIs, check the Vite 8 migration guide for their breaking changes and upgrade your project as needed.

Most Astro users should be able to upgrade without any changes to their project code. This is primarily a breaking change for Astro integrations and plugins that depend on Vite internals.

Experimental Flags

Experimental flags allow you to opt in to features while they are in early development. The following experimental flags have been removed in Astro 7.0 and are now stable, or the new default behavior.

Remove these experimental flags from your Astro config if you were previously using them:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    queuedRendering: {
      enabled: true,
    },
    rustCompiler: true,
    advancedRouting: true,
  },
});

Experimental features now stable:

• queuedRendering: Queued rendering is now the default behavior, and the experimental flag has been removed. No action is required to enable this feature in your project. All projects now benefit from the improved performance.

• rustCompiler: The Rust-based Astro compiler is now the default and only compiler, replacing the previous Go-based compiler. No action is required for most projects. If you encounter any issues, please report them on GitHub.

• advancedRouting: Advanced routing is now enabled by default. See the advanced routing guide for more information. Note that src/fetch.ts is now a reserved file name.

Reserved file name: src/fetch.ts

Astro v7.0 introduces advanced routing, which uses src/fetch.ts (or src/fetch.js) as a special file name, similar to src/middleware.ts. Astro will automatically import this file to configure routing behavior.

If your project already has a src/fetch.ts file used for other purposes, Astro will attempt to process it as an advanced routing configuration, which may cause unexpected errors.

What should I do?

If you have an existing src/fetch.ts file that is not related to advanced routing, you have two options:

• Configure fetchFile: you can specify a different filename or null to disable advanced routing. This is useful if you want to keep using src/fetch.ts for another purpose, or don’t need advanced routing features:

  astro.config.mjs

  import { defineConfig } from 'astro/config';
  
  export default defineConfig({
    // specify a different file for advanced routing configuration:
    fetchFile: './src/router.ts',
    // or disable advanced routing entirely:
    // fetchFile: null,
  });

• Rename your file to something else (e.g. src/fetcher.ts, src/main.ts), and update any imports that reference it.

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: exposed astro:transitions internals

طلب دمج التنفيذ: feat: remove deprecated astro:transitions internals (#16725)

In Astro 6.x, some helpers available in astro:transitions and astro:transitions/client were deprecated.

In Astro 7.0, the following APIs can no longer be used in your project:

• TRANSITION_BEFORE_PREPARATION
• TRANSITION_AFTER_PREPARATION
• TRANSITION_BEFORE_SWAP
• TRANSITION_AFTER_SWAP
• TRANSITION_PAGE_LOAD
• isTransitionBeforePreparationEvent()
• isTransitionBeforeSwapEvent()
• createAnimationScope()

What should I do?

Remove any occurrence of createAnimationScope():

import { createAnimationScope } from 'astro:transitions';

Replace any occurrence of the other APIs using the lifecycle event names directly:

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

console.log(isTransitionBeforePreparationEvent(event));
console.log(event.type === 'astro:before-preparation');

console.log(TRANSITION_AFTER_SWAP);
console.log('astro:after-swap');

Learn more about all utilities available in the View Transitions Router API Reference.