Upgrade to Astro v4

This guide will help you migrate from Astro v3 to Astro v4.

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

Need to see the v3 docs? Visit this older version of the docs site (unmaintained) (random deploy preview lol)

Update your project’s version of Astro and all official integrations to the latest versions 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.

Remove the following experimental flags from astro.config.mjs:

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    // nothing here yet @TODO: check if needed
  },
})

These features are now available by default:

Read more about these two exciting features and more in the 4.0 Blog post!

Astro v4.0 includes some breaking changes, as well as the removal of some previously deprecated features. If your project doesn’t work as expected after upgrading to v4.0, check this guide for an overview of all breaking changes and instructions on how to update your codebase.

See the changelog for full release notes.

In Astro v3.0, Vite 4 was used as the development server and production bundler.

Astro v4.0 upgrades from Vite 4 to Vite 5.

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

In Astro v3.x, unified v10 and its related compatible remark/rehype packages were used to process Markdown and MDX.

Astro v4.0 upgrades unified to v11 and the other remark/rehype packages to latest.

If you used custom remark/rehype packages, update all of them to latest using your package manager to ensure they support unified v11. The packages you are using can be found in astro.config.mjs. There should not be any significant breaking changes if you use actively-updated packages, but some packages may not yet be compatible with unified v11. Visually inspect your Markdown/MDX pages before deploying to ensure your site is functioning as intended.

In Astro v3.x, the property of the injectRoute integrations API that specified the route entry point was named entryPoint.

Astro v4.0 renames this property to entrypoint to be consistent with other Astro APIs. The entryPoint property is deprecated, but will continue to work and logs a warning prompting you to update your code.

If you have integrations that use the injectRoute API, rename the entryPoint property to entrypoint. If you’re a library author who wants to support both Astro 3 and 4, you can specify both entryPoint and entrypoint, in which case, a warning will not be logged.

In Astro v3.x, returning simple objects from endpoints was deprecated, but was still supported to maintain compatibility with Astro v2. A ResponseWithEncoding utility was also provided to ease the migration.

Astro v4.0 removes support for simple objects and requires endpoints to always return a Response. The ResponseWithEncoding utility is also removed in favor of a proper Response type.

Update your endpoints to return a Response object directly.

export async function GET() {
  return { body: { "title": "Bob's blog" }};
  return new Response(JSON.stringify({ "title": "Bob's blog" }));
}

To remove usage of ResponseWithEncoding, refactor your code to use an ArrayBuffer instead:

export async function GET() {
  const file = await fs.readFile('./bob.png');
  return new ResponseWithEncoding(file.toString('binary'), undefined, 'binary');
  return new Response(file.buffer);
}

In Astro v3.x, a Shiki language passed to markdown.shikiConfig.langs will be automatically converted to a Shikiji-compatible language. Shikiji is the internal tooling used by Astro for syntax highlighting.

Astro v4.0 removes partial compatibility support for the path property of a Shiki language. This path property used to resolve from <root>/node_modules/astro which can be confusing to configure, hence its support is removed.

The language JSON file should be imported and passed to the option instead.

 import customLang from './custom.tmLanguage.json'

export default defineConfig({
  markdown: {
    shikiConfig: {
      langs: [
       { path: '../../custom.tmLanguage.json' },
       customLang,
      ],
    },
  },
})

In Astro v3.0, the app.render() method accepted routeData and locals as separate optional arguments.

Astro v4.0 changes the app.render() signature. It’s second argument is now a single optional object with two optional properties: routeData and locals.

If you are maintaining an adapter, the current signature will continue to work until the next major version. To migrate to the new signature, pass routeData and locals as properties of an object instead of as multiple independent arguments.

app.render(request, routeData, locals)
app.render(request, { routeData, locals })

Astro v4.0 adds the astro preferences command to manage user preferences. User preferences are specific to individual Astro users, unlike the astro.config.mjs file which changes behavior for everyone working on a project.

In order to disable the new dev overlay for the current Astro project, run the following command:

astro preferences disable devOverlay

In order to disable the dev overlay for every project on your machine, run the following command:

astro preferences --global disable devOverlay

In order to re-enable the dev overlay, run the following command:

astro preferences enable devOverlay

In Astro v3.x, projects using the <ViewTransitions /> component were required to opt-in to handling submit events for form elements. This was done by passing a handleForms prop.

Astro v4.0 handles submit events for form elements by default when <ViewTransitions /> are used. The handleForms prop has been deprecated and no longer has any effect.

Remove the handleForms property from your ViewTransitions component.

To opt-out of submit event handling, add the data-astro-reload attribute to relevant form elements.

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

There are currently no known issues.