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 v3.6 snapshot).
Upgrade Astro
Section titled “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 togethernpx @astrojs/upgrade# Upgrade Astro and official integrations togetherpnpm dlx @astrojs/upgrade# Upgrade Astro and official integrations togetheryarn dlx @astrojs/upgradeYou can also upgrade your Astro integrations manually if needed, and you may also need to upgrade other dependencies in your project.
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.
Astro v4.0 Experimental Flags Removed
Section titled “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: { 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!
Upgrades
Section titled “Upgrades”Any major upgrades to Astro’s dependencies may cause breaking changes in your project.
Upgraded: Vite 5.0
Section titled “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?
Section titled “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
Section titled “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?
Section titled “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
Section titled “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)
Section titled “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?
Section titled “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
Section titled “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?
Section titled “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
Section titled “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?
Section titled “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
Section titled “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?
Section titled “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
Section titled “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
Section titled “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?
Section titled “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>