import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

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 v3.6 snapshot).

Update your project's version of Astro and all official integrations to the latest versions using your package manager.

You can also upgrade your Astro integrations manually if needed, and you may also need to upgrade other dependencies in your project.

:::note[Need to continue?] After upgrading Astro to the latest version, 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 v4.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 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.

Remove the devOverlay experimental flag and move any i18n config to the top level in astro.config.mjs:

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    devOverlay: true,
    i18n: {
      locales: ["en", "fr", "pt-br", "es"],
      defaultLocale: "en",
    }
  },
  i18n: {
    locales: ["en", "fr", "pt-br", "es"],
    defaultLocale: "en",
  },
})

These configurations, i18n and the renamed devToolbar, are now available in Astro v4.0.

Read more about these two exciting features and more in the v4.0 Blog post!

Any major upgrades to Astro's dependencies may cause breaking changes in your project.

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 the latest version.

If you used custom remark/rehype packages, update all of them to the latest version 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.

The following changes are considered breaking changes in Astro. Breaking changes may or may not provide temporary backwards compatibility, and all documentation is updated to refer to only the current, supported code.

If you need to refer to the documentation for a v3.x project, you can browse this (unmaintained) snapshot of the docs from before v4.0 was released.

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.

injectRoute({
  pattern: '/fancy-dashboard',
  entryPoint: '@fancy/dashboard/dashboard.astro'
  entrypoint: '@fancy/dashboard/dashboard.astro'
});

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 v4.0 requires adapters to pass the supportedAstroFeatures{} property to specify a list of features they support. This property is no longer optional.

Adapter authors need to pass the supportedAstroFeatures{} option to specify a list of features they support.

export default function createIntegration() {
  return {
    name: '@matthewp/my-adapter',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@matthewp/my-adapter',
          serverEntrypoint: '@matthewp/my-adapter/server.js',
          supportedAstroFeatures: {
              staticOutput: 'stable'
          }
        });
      },
    },
  };
}

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.

// astro.config.js
  import customLang from './custom.tmLanguage.json'

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

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.

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. It is no longer necessary.

---
import { ViewTransitions } from "astro:transitions";
---
<html>
  <head>
    <ViewTransitions handleForms />
  </head>
  <body>
    <!-- stuff here -->
  </body>
</html>

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

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

The following deprecated 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.

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.0, build.split and build.excludeMiddleware build config options were deprecated and replaced with adapter configuration options to perform the same tasks.

Astro v4.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 v3.0, the Astro.request.params API was deprecated, but preserved for backwards compatibility.

Astro v4.0 removes this option entirely.

Update all occurrences to Astro.params, which is the supported replacement.

const { id } = Astro.request.params;
const { id } = Astro.params;

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

Astro v4.0 removes this option entirely.

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

To continue to mark some pages in your project as drafts, migrate to content collections and manually filter out pages with the draft: true frontmatter property instead.

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

Astro v4.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(), which is the supported replacement.

const posts = await Astro.glob('../content/blog/*.mdx');
const firstPostHeadings = posts.at(0).getHeaders();
const firstPostHeadings = posts.at(0).getHeadings();

In Astro v3.0, using the deprecated rss helper in getStaticPaths() would throw an error.

Astro v4.0 removes this helper entirely.

If you are using the unsupported method for generating RSS feeds, you must now use the @astrojs/rss integration for a complete RSS setup.

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

Astro v4.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, the Astro preview server returned a 301 redirect when accessing public directory assets without a base path.

Astro v4.0 returns a 404 status without a base path prefix for public directory assets when the preview server is running, matching the behavior of the dev server.

When using the Astro preview server, all of your static asset imports and URLs from the public directory must have the base value prefixed to the path.

The following example shows the src attribute required to display an image from the public folder when base: '/docs' is configured:

// To access public/images/my-image.png:

<img src="/docs/images/my-image.png" alt="">

In Astro v3.x, the astro/client-image type (used for the deprecated image integration) was removed but was auto-converted to the default Astro type astro/client if found in your env.d.ts file.

Astro v4.0 ignores astro/client-image and will no longer update env.d.ts for you automatically.

If you had types configured for @astrojs/image in src/env.d.ts and upgrading to v3.0 did not automatically convert the type for you, replace the astro/client-image type manually with astro/client.

  /// <reference types="astro/client-image" />
  /// <reference types="astro/client" />

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

Please check Astro's issues on GitHub for any reported issues, or to file an issue yourself.