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 alpha

pnpm

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

Yarn

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

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.

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.

Deprecated: top-level markdown plugin options

Implementation PR: feat: Try a native pipeline for content (#16149)

With the new default Markdown processor, the top-level markdown.remarkPlugins, markdown.rehypePlugins, and markdown.remarkRehype options are deprecated, as are markdown.gfm and markdown.smartypants. These are now configured through the markdown.processor option instead.

The remark / rehype top-level options continue to work for now as long as @astrojs/markdown-remark is installed. They will be removed in a future major version.

What should I do?

If your project sets markdown.remarkPlugins, markdown.rehypePlugins, or markdown.remarkRehype, install @astrojs/markdown-remark, which is no longer included with astro:

npm

npm install @astrojs/markdown-remark

pnpm

pnpm add @astrojs/markdown-remark

Yarn

yarn add @astrojs/markdown-remark

Then, move your plugins into the unified() processor passed to markdown.processor:

astro.config.mjs

import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';
import remarkToc from 'remark-toc';

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkToc],
    processor: unified({ remarkPlugins: [remarkToc] }),
  },
});

To replace the deprecated markdown.gfm and markdown.smartypants options, configure the equivalent features on your processor instead. For example, use satteri({ features: { gfm: false } }) for the default processor.

See Markdown plugins for more about configuring the Markdown processor.

Changed Defaults

Some default behavior has changed in Astro v7.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: default Markdown processor

Implementation PR: feat: Try a native pipeline for content (#16149)

In Astro v6.x, .md and .mdx files were processed with remark and rehype, and @astrojs/markdown-remark was included with astro.

Astro v7.0 replaces remark and rehype as the default Markdown and MDX engine with Sätteri, a performant Markdown / MDX compiler. Both .md and .mdx files now render through Sätteri by default, and @astrojs/markdown-remark is no longer included with astro. The new markdown.processor option controls which processor renders your content.

What should I do?

If your project does not configure any remark or rehype plugins, no action is required. Your content renders through Sätteri, and the output should be unchanged.

If your project depends on the remark / rehype ecosystem, follow the steps for the deprecated top-level markdown plugin options to install @astrojs/markdown-remark and opt back in to the remark / rehype pipeline.

You can also convert your existing plugins into Sätteri plugins to continue using the default processor.

See Markdown plugins for more about configuring the Markdown processor.

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.

Rust Compiler

The Rust-based Astro compiler, previously available as an experimental flag (experimental.rustCompiler), is now the default and only compiler in Astro 7. The Rust compiler delivers significantly faster build times compared to the previous Go-based compiler.

What should I do?

No action is required for most projects. The Rust compiler is a drop-in replacement for the Go-based compiler.

If you had previously opted in to the Rust compiler via the experimental flag, you can now remove it from your configuration:

astro.config.mjs

import { defineConfig } from 'astro/config';

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

If you encounter any issues with the Rust compiler, please report them on GitHub.