Upgrade to Astro v7

Este conteúdo não está disponível em sua língua ainda.

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:

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

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

# 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.

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:

import { defineConfig, logHandlers, memoryCache } from 'astro/config';

export default defineConfig({
  experimental: {
    logger: logHandlers.json({ pretty: true }),
    queuedRendering: {
      enabled: true,
    },
    rustCompiler: true,
    advancedRouting: true,
    cache: {
      provider: memoryCache(),
    },
    routeRules: {
      '/blog/[...path]': { maxAge: 300, swr: 60 },
    },
  },
  cache: {
    provider: memoryCache(),
  },
  routeRules: {
    '/blog/[...path]': { maxAge: 300, swr: 60 },
  },
})

Experimental features now stable:

logger: The new logging system is now stable and the experimental flag is no longer needed to use it. If you were using this flag, you can now set your logger directly in the top-level logger field of your Astro config.
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. See Rust compiler for details on behavior changes that may affect your project.
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.
cache: Route caching is now stable. If you were using this feature, update your config to move cache and routeRules out of the experimental block.

Rust compiler

Implementation PR: feat!: make Rust compiler the default and only compiler (#16462)

Astro v7.0 replaces the previous Go-based compiler with a new Rust-based compiler. The new compiler is faster, but is also stricter about invalid HTML syntax. Templates that previously built without errors may now fail.

The Rust compiler enforces two key changes:

Unclosed tags now produce errors. The previous compiler silently accepted unclosed HTML and component tags. The Rust compiler requires all non-void elements to have a matching closing tag.
Semantically invalid HTML is no longer auto-corrected. The previous compiler would silently reorder or restructure invalid HTML to match the HTML parsing specification (e.g. moving elements out of <p> tags where block elements are not allowed). The Rust compiler does not attempt to correct your markup and instead passes it through as-is, leaving the browser to handle it. This may cause different rendered output for previously “tolerated” invalid markup.

What should I do?

Run your build after upgrading. If you see compiler errors about unexpected tokens or unclosed tags, add the missing closing tags:

<!-- Before: unclosed tags that the Go compiler silently accepted -->
<p>Hello world
<p>Hello world</p>

<!-- Void elements like <br>, <img>, <input>, and <hr> do not need closing tags -->

---
import Layout from '../layouts/Layout.astro';
---
<Layout>
  <p>Content here

<Layout>
  <p>Content here</p>
</Layout>

If your rendered HTML output has changed after upgrading, inspect your templates for invalid HTML nesting that the previous compiler was silently correcting. For example, placing a <div> inside a <p> is invalid HTML. The previous compiler would restructure this for you, but the Rust compiler will not:

<!-- Invalid nesting: <div> is not allowed inside <p> -->
<!-- The browser will close the <p> early, which may break your layout -->
<p>
  <div>This will not be inside the paragraph</div>
</p>

<!-- Fix: use a valid container instead -->
<div>
  <div>This is correctly nested</div>
</div>

CSS output differences

The Rust compiler processes CSS differently, which may cause minor visual differences in your built output:

Color values may be serialized differently. Named colors like rebeccapurple may become hex values like #639 in the built CSS. This does not change the visual appearance of your site.
url() values may gain or lose quotes. For example, url(/path) may become url('/path') or vice versa. This does not affect functionality.

These differences are cosmetic and do not require any action unless you have tests or tools that rely on exact CSS string matching.

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:

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.

New default Markdown processor: Sätteri

Implementation PR: feat: make Sätteri the default Markdown pipeline (#16966)

Astro now renders your .md and .mdx files with Sätteri, its native Markdown pipeline, instead of the remark/rehype pipeline. As a result, @astrojs/markdown-remark is no longer installed by default.

What should I do?

If you don’t use remark or rehype plugins, you don’t need to do anything. Your Markdown and MDX will now be rendered by Sätteri, which applies GitHub-Flavored Markdown and SmartyPants just like before.

If you depend on remark and rehype plugins, you can port them to Sätteri MDAST or HAST plugins. If you depend on recma plugins, or if you are not yet ready or able to port your remark and rehype plugins, you can stay on the unified() pipeline.

To keep using unified plugins:

Install @astrojs/markdown-remark:

npm install @astrojs/markdown-remark

pnpm add @astrojs/markdown-remark

yarn add @astrojs/markdown-remark

Set unified() as your Markdown processor:

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

export default defineConfig({
  markdown: {
    processor: unified(),
  },
});

The deprecated markdown.remarkPlugins, markdown.rehypePlugins, and markdown.remarkRehype options still work, but now also require @astrojs/markdown-remark to be installed.

New default whitespace handling: `compressHTML: 'jsx'`

Implementation PR: feat: make jsx whitespace handling the default (#16965)

In Astro v6.x, whitespace handling used HTML-aware compression by default. This means that Astro would preserve a single space between inline elements, following HTML rules.

In Astro v7.0, the default value of compressHTML has changed from true to 'jsx'. Now, Astro strips whitespace from your HTML using JSX rules by default, the same way frameworks like React do.

The following example would render as helloworld in Astro v7.0, instead of hello world in Astro v6.x:

<span>hello</span>
<em>world</em>

What should I do?

Visually inspect your website to ensure that the spaces between elements are rendered as expected. You may not need to take any further action.

If you notice that some spaces are missing, identify the components and pages where you are using inline elements. Then, update them to add an explicit space between these elements using {" "}:

<span>hello</span>
<em>world</em>
<span>hello</span> <em>world</em>

If you prefer to keep the previous behavior, set compressHTML to true. You can also use compressHTML: false to preserve all whitespace.

import { defineConfig } from 'astro/config';

export default defineConfig({
  compressHTML: true,
});

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: `getContainerRenderer()` from integration package roots

Implementation PR: fix(integrations): Export container renderers from a dedicated export path to fix bundling issues (#17093)

In Astro 6.x, the getContainerRenderer() helper used with the Container API was imported from an official integration’s package root (e.g. @astrojs/react). This could cause bundlers to pull in unrelated, build-time-only exports from the package root when only the Container API was needed.

Astro 7.0 deprecates importing getContainerRenderer() from an integration’s package root in favor of a dedicated container-renderer entrypoint.

What should I do?

Update your Container API imports to use the new container-renderer entrypoint for each official integration:

import { getContainerRenderer } from '@astrojs/react';
import { getContainerRenderer } from '@astrojs/react/container-renderer';

This entrypoint is available for @astrojs/react, @astrojs/preact, @astrojs/solid-js, @astrojs/svelte, @astrojs/vue, and @astrojs/mdx.

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: `@astrojs/db`

The @astrojs/db package has been removed in Astro v7.0 and is no longer maintained.

What should I do?

Remove @astrojs/db from your project’s dependencies and replace it with one of the following alternatives:

Node.js built-in SQLite: Node.js now includes a built-in node:sqlite module (available since Node.js v22.5.0). This is a good option if you are using the Node.js adapter and were using @astrojs/db for local SQLite storage.
Drizzle ORM: If you were using @astrojs/db for its Drizzle-based schema and query API, you can use Drizzle directly with any supported database.
Other database libraries: Use any database library that suits your deployment platform (e.g. Turso, PlanetScale, Neon).

Removed: exposed `astro:transitions` internals

Implementation PR: 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.

Contribua Comunidade Sponsor

Upgrade to Astro v7

Upgrade Astro

Breaking Changes

Dependency Upgrades

Vite 8

What should I do?

Experimental Flags

Experimental features now stable:

Rust compiler

What should I do?

CSS output differences

Reserved file name: src/fetch.ts

What should I do?

New default Markdown processor: Sätteri

What should I do?

New default whitespace handling: compressHTML: 'jsx'

What should I do?

Deprecated

Deprecated: getContainerRenderer() from integration package roots

What should I do?

Removed

Removed: @astrojs/db

What should I do?

Removed: exposed astro:transitions internals

What should I do?

Reserved file name: `src/fetch.ts`

New default whitespace handling: `compressHTML: 'jsx'`

Deprecated: `getContainerRenderer()` from integration package roots

Removed: `@astrojs/db`

Removed: exposed `astro:transitions` internals