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 potentially 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.0, the app.render() method accepted routeData and locals as separate, optional arguments.

Astro v4.0 changes the app.render() signature. These two properties are now available in a single object. Both the object and these two properties are still optional.

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 })

In Astro v3.x, adapters were not required to specify the features they support.

Astro 4.0 requires adapters to pass an supportedAstroFeatures property to specify a list of features they support.

Adapter authors need to pass the supportedAstroFeatures option to specify a list of features they support. If this was not set before, you can pass supportedAstroFeatures: {}.

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 was automatically converted to a Shikiji-compatible language. Shikiji is the internal tooling used by Astro for syntax highlighting.

Astro v4.0 removes support for the path property of a Shiki language, which was confusing to configure. It is replaced by an import which can be passed to langs directly.

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 3.0, build.split and build.excludeMiddleware were deprecated.

Astro 4.0 removes these properties entirely.

If you are using the deprecated build.split or build.excludeMiddleware, you must now remove them as these no longer exist.

Please see the v3 migration guide to update these deprecated middleware properties with adapter configurations.

In Astro 3.0, using markdown.drafts to control the building of draft posts was deprecated.

Astro 4.0 removes this option entirely.

If you are using the deprecated markdown.drafts, you must now remove it as it no longer exist.

Please see the v3 migration guide to upgrade to content collections to filter draft posts before building.

In Astro 3.0, the getHeaders() Markdown export was deprecated and replaced with getHeadings().

Astro 4.0 removes this option entirely.

If you are using the deprecated getHeaders(), you must now remove it as it no longer exists. Replace any instances with getHeadings().

In Astro 3.0, using lowercase HTTP request method names (get, post, put, all, del) was deprecated.

Astro 4.0 removes support for lowercase names entirely. All HTTP request methods must now be written using uppercase.

If you are using the deprecated lowercase names, you must now replace them with their uppercase equivalents.

Please see the v3 migration guide for guidance using uppercase HTTP request methods.

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.

<form action="/contact" data-astro-reload>
  <!-- -->
</form>

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

There are currently no known issues.