Upgrade to Astro v4

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

```diff lang="js"
- 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.

      },
    },
  };
}

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.

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


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