Upgrade to Astro v4

This content is not available in your language yet.

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

Upgrade Astro

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.

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.

Astro v4.0 Experimental Flags Removed

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: {
      defaultLocale: "en",
      locales: ["en", "fr", "pt-br", "es"],
    }
  },
  i18n: {
    defaultLocale: "en",
    locales: ["en", "fr", "pt-br", "es"],
  },
})

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!

Upgrades

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

Upgraded: Vite 5.0

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.

What should I do?

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.

Upgraded: unified, remark, and rehype dependencies

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.

What should I do?

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.

Breaking Changes

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.

Renamed: `entrypoint` (Integrations API)

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.

What should I do?

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

Changed: `app.render` signature in Integrations API

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.

What should I do?

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

Changed: adapters must now specify supported features

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.

What should I do?

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'
          }
        });
      },
    },
  };
}

Removed: Shiki language `path` property

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.

What should I do?

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

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: `handleForms` for View Transitions `submit` events

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.

What should I do?

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>

Previously deprecated features now removed

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.

Removed: returning simple objects from endpoints

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.

What should I do?

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

Removed: `build.split` and `build.excludeMiddleware`

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.

What should I do?

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.

Removed: `Astro.request.params`

In Astro v3.0, the Astro.request.params API was deprecated, but preserved for backwards compatibility.

Astro v4.0 removes this option entirely.

What should I do?

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

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

Removed: `markdown.drafts`

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

Astro v4.0 removes this option entirely.

What should I do?

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.

Removed: `getHeaders()`

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

Astro v4.0 removes this option entirely.

What should I do?

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();

Removed: using `rss` in `getStaticPaths()`

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

Astro v4.0 removes this helper entirely.

What should I do?

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

Removed: lowercase HTTP method names

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.

What should I do?

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.

Removed: 301 redirects when missing a `base` prefix

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.

What should I do?

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="">

Removed: `astro/client-image` auto-conversion

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.

What should I do?

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" />

Community Resources

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

Known Issues

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

Upgrade to Astro v4

Upgrade Astro

Astro v4.0 Experimental Flags Removed

Upgrades

Upgraded: Vite 5.0

What should I do?

Upgraded: unified, remark, and rehype dependencies

What should I do?

Breaking Changes

Renamed: entrypoint (Integrations API)

What should I do?

Changed: app.render signature in Integrations API

What should I do?

Changed: adapters must now specify supported features

What should I do?

Removed: Shiki language path property

What should I do?

Deprecated

Deprecated: handleForms for View Transitions submit events

What should I do?

Previously deprecated features now removed

Removed: returning simple objects from endpoints

What should I do?

Removed: build.split and build.excludeMiddleware

What should I do?

Removed: Astro.request.params

What should I do?

Removed: markdown.drafts

What should I do?

Removed: getHeaders()

What should I do?

Removed: using rss in getStaticPaths()

What should I do?

Removed: lowercase HTTP method names

What should I do?

Removed: 301 redirects when missing a base prefix

What should I do?

Removed: astro/client-image auto-conversion

What should I do?

Community Resources

Known Issues

Renamed: `entrypoint` (Integrations API)

Changed: `app.render` signature in Integrations API

Removed: Shiki language `path` property

Deprecated: `handleForms` for View Transitions `submit` events

Removed: `build.split` and `build.excludeMiddleware`

Removed: `Astro.request.params`

Removed: `markdown.drafts`

Removed: `getHeaders()`

Removed: using `rss` in `getStaticPaths()`

Removed: 301 redirects when missing a `base` prefix

Removed: `astro/client-image` auto-conversion