Upgrade to Astro v2
This guide will help you migrate from Astro v1 to Astro v2.
Need to upgrade an older project to v1? See our older migration guide.
Upgrade AstroSection titled Upgrade Astro
Update your project’s version of Astro to the latest version using your package manager. If you’re using Astro integrations, please also update those to the latest version.
Astro v2.0 Breaking ChangesSection titled Astro v2.0 Breaking Changes
Astro v2.0 includes some breaking changes, as well as the removal of some previously deprecated features. If your project doesn’t work as expected after upgrading to v2.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.
Removed: Support for Node 14Section titled Removed: Support for Node 14
Node 14 is scheduled to reach its End of Life in April 2023.
Astro v2.0 drops Node 14 support entirely, so that all Astro users can take advantage of Node’s more modern features.
Check that both your development environment and your deployment environment are using Node
16.12.0 or later.
Check your local version of Node using:
If your local development environment needs upgrading, install Node.
Check your deployment environment’s own documentation to verify that they support Node 16.
You can specify Node
16.12.0for your Astro project either in a dashboard configuration setting, or a
Reserved: Section titled Reserved: src/content/
Astro v2.0 now includes the Collections API for organizing your Markdown and MDX files into content collections. This API reserves
src/content/ as a special folder.
Rename an existing
src/content/ folder to avoid conflicts. This folder, if it exists, can now only be used for content collections.
Changed: Section titled Changed: Astro.site trailing slash
Astro.site trailing slash
In v1.x, Astro ensured the URL you set as
astro.config.mjs always had a trailing slash when accessed using
Astro v2.0 no longer modifies the value of
Astro.site will use the exact value defined, and a trailing slash must be specified if desired.
astro.config.mjs, add a trailing slash to the URL set in
Changed: Section titled Changed: _astro/ folder for build assets
_astro/ folder for build assets
In v1.x, assets were built to various locations, including
chunks/, and to the root of the build output.
Astro v2.0 moves and unifies the location of all build output assets to a new
You can control this location with the new
build.assets configuration option.
Update your deployment platform configuration if it relies on the location of these assets.
Changed: Markdown plugin configurationSection titled Changed: Markdown plugin configuration
Removed: Section titled Removed: extendDefaultPlugins
In v1.x, Astro used
markdown.extendDefaultPlugins to re-enable Astro’s default plugins when adding your own Markdown plugins.
Astro v2.0 removes this configuration option entirely because its behavior is now the default.
Applying remark and rehype plugins in your Markdown configuration no longer disables Astro’s default plugins. GitHub-Flavored Markdown and Smartypants are now applied whether or not custom
rehypePlugins are configured.
extendDefaultPlugins in your configuration. This is now Astro’s default behavior in v2.0, and you can delete this line without any replacement.
Added: Section titled Added: gfm and smartypants
In v1.x, you could choose to disable both of Astro’s default Markdown plugins (GitHub-Flavored Markdown and SmartyPants) by setting
Astro v2.0 replaces
markdown.extendDefaultPlugins: false with separate Boolean options to individually control each of Astro’s built-in default Markdown plugins. These are enabled by default and can be set to
extendDefaultPlugins: false and add the flags to disable each plugin individually instead.
markdown.gfm: falsedisables GitHub-Flavored Markdown
markdown.smartypants: falsedisables SmartyPants
Changed: MDX plugin configurationSection titled Changed: MDX plugin configuration
Replaced: Section titled Replaced: extendPlugins changed to extendMarkdownConfig
extendPlugins changed to
In v1.x, the MDX integration’s
extendPlugins option managed how your MDX files should inherit your Markdown configuration: all your Markdown configuration (
markdown), or Astro’s default plugins only (
Astro v2.0 replaces the behavior controlled by
mdx.extendPlugins with three new, independently-configurable options that are
true by default:
mdx.extendMarkdownConfigto inherit all or none of your Markdown configuration
mdx.gfmto enable or disable GitHub-Flavored Markdown in MDX
mdx.smartypantsto enable or disable SmartyPants in MDX
extendPlugins: 'markdown' in your configuration. This is now the default behavior.
extendPlugins: 'defaults' with
extendMarkdownConfig: false and add the separate options for GitHub-Flavored Markdown and SmartyPants to enable these default plugins individually in MDX.
Added: More MDX config options to match MarkdownSection titled Added: More MDX config options to match Markdown
Astro v2.0 allows you to now individually set every available Markdown configuration option (except
drafts) separately in your MDX integration configuration.
Revisit your Markdown and MDX configuration and compare your existing config with the new options available.
Changed: Plugin access to frontmatterSection titled Changed: Plugin access to frontmatter
In v1.x, remark and rehype plugins did not have access to user frontmatter. Astro merged plugin frontmatter with your file’s frontmatter, without passing the file frontmatter to your plugins.
Astro v2.0 gives remark and rehype plugins access to user frontmatter via frontmatter injection. This allows plugin authors to modify a user’s existing frontmatter, or compute new properties based on other properties.
Check any remark and rehype plugins you have written to see whether their behavior has changed. Note that
data.astro.frontmatter is now the complete Markdown or MDX document’s frontmatter, rather than an empty object.
Changed: RSS ConfigurationSection titled Changed: RSS Configuration
In v1.x, Astro’s RSS package allowed you to use
items: import.meta.glob(...) to generate a list of RSS feed items. This usage is now deprecated and will eventually be removed.
Astro v2.0 introduces a
pagesGlobToRssItems() wrapper to the
Import, then wrap your existing function containing
import.meta.glob() with the
Changed: Svelte IDE supportSection titled Changed: Svelte IDE support
Astro v2.0 requires a
svelte.config.js file in your project if you are using the
@astrojs/svelte integration. This is needed to provide IDE autocompletion.
svelte.config.js file to the root of your project:
For new users, this file will be added automatically when running
astro add svelte.
Removed: Section titled Removed: legacy.astroFlavoredMarkdown
In v1.0, Astro moved the old Astro-Flavored Markdown (also known as Components in Markdown) to a legacy feature.
Astro v2.0 removes the
legacy.astroFlavoredMarkdown option completely. Importing and using components in
.md files will no longer work.
Remove this legacy flag. It is no longer available in Astro.
If you were using this feature in v1.x, we recommend using the MDX integration which allows you to combine components and JSX expressions with Markdown syntax.
Removed: Section titled Removed: Astro.resolve()
In v0.24, Astro deprecated
Astro.resolve() for getting resolved URLs to assets that you might want to reference in the browser.
Astro v2.0 removes this option entirely.
Astro.resolve() in your code will cause an error.
Resolve asset paths using
import instead. For example:
Removed: Section titled Removed: Astro.fetchContent()
In v0.26, Astro deprecated
Astro.fetchContent() for fetching data from your local Markdown files.
Astro v2.0 removes this option entirely.
Astro.fetchContent() in your code will cause an error.
Removed: Section titled Removed: Astro.canonicalURL
In v1.0, Astro deprecated
Astro.canonicalURL for constructing a canonical URL.
Astro v2.0 removes this option entirely.
Astro.canonicalURL in your code will cause an error.
Astro.url to construct a canonical URL.
Updated: Vite 4Section titled Updated: Vite 4
Astro v2.0 upgrades from Vite 3 to Vite 4, released in December 2022.
There should be no changes to your code necessary! We’ve handled most of the upgrade for you inside of Astro; however, some subtle Vite behaviors may still change between versions.
Refer to the official Vite Migration Guide if you run into trouble.
Astro v2.0 Experimental Flags RemovedSection titled Astro v2.0 Experimental Flags Removed
Remove the following experimental flags from
These features are now available by default:
- Content collections as a way to manage your Markdown and MDX files with type-safety.
- Prerendering individual pages to static HTML when using SSR to improve speed and cacheability.
- A redesigned error message overlay.
Known IssuesSection titled Known Issues
There are currently no known issues.Upgrade Guides