Legacy v0.x Upgrade Guide

This guide will help you upgrade through breaking changes in pre-v1 versions of Astro.

You can update your project's version of Astro to the latest version using your package manager. If you're using Astro integrations, you'll also want to update those to the latest version.

# updates the astro dependency:
npm upgrade astro
# or, to update all dependencies:
npm upgrade

Read the guide below for major highlights and instructions on how to handle breaking changes.

Astro 1.0

Astro v1.0 introduces some changes that you should be aware of when migrating from v0.x and v1.0-beta releases. See below for more details.

Updated: Vite 3

Astro v1.0 has upgraded from Vite 2 to Vite 3. 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.

Deprecated: Astro.canonicalURL

You can now use the new Astro.url helper to construct your own canonical URL from the current page/request URL.

// Before:
const canonicalURL = Astro.canonicalURL;
// After:
const canonicalURL = new URL(Astro.url.pathname, Astro.site);

Changed: Scoped CSS specificity

Specificity will now be preserved in scoped CSS styles. This change will cause most scoped styles to happen to take precedence over global styles. But, this behavior is no longer explicitly guaranteed.

Technically, this is accomplished using the :where() pseudo-class instead of using classes directly in Astro’s CSS output.

Let’s use the following style block in an Astro component as an example:

<style>
  div { color: red; } /* 0-0-1 specificity */
</style>

Previously, Astro would transform this into the following CSS, which has a specificity of 0-1-1 — a higher specificity than the source CSS:

div.astro-XXXXXX { color: red; } /* 0-1-1 specificity */

Now, Astro wraps the class selector with :where(), maintaining the authored specificity:

div:where(.astro-XXXXXX) { color: red; } /* 0-0-1 specificity */

The previous specificity increase made it hard to combine scoped styles in Astro with other CSS files or styling libraries (e.g. Tailwind, CSS Modules, Styled Components, Stitches). This change will allow Astro's scoped styles to work consistently alongside them while still preserving the exclusive boundaries that prevent styles from applying outside the component.

:::caution When upgrading, please visually inspect your site output to make sure everything is styled as expected. If not, find your scoped style and increase the selector specificity manually to match the old behavior. :::

Deprecated: Components and JSX in Markdown

Astro no longer supports components or JSX expressions in Markdown pages by default. For long-term support you should migrate to the @astrojs/mdx integration.

To make migrating easier, a new legacy.astroFlavoredMarkdown flag (removed in v2.0) can be used to re-enable previous Markdown features.

Converting existing .md files to .mdx

If you're not familiar with MDX, here are some steps you can follow to quickly convert an existing "Astro Flavored Markdown" file to MDX. As you learn more about MDX, feel free to explore other ways of writing your pages!

:::tip While you are transitioning to MDX, you may wish to enable the legacy.astroFlavoredMarkdown flag (removed in v2.0) and include both .md and .mdx files, so that your site continues to function normally even before all your files have been converted. Here is one way you can do that:

---
const mdPosts = await Astro.glob('../pages/posts/*.md');
const mdxPosts = await Astro.glob('../pages/posts/*.mdx');
const allPosts = [...mdxPosts, ...mdPosts];
---

:::

<Markdown /> Component Removed

Astro's built-in <Markdown /> component has been moved to a separate package. To continue using this component, you will now need to install @astrojs/markdown-component and update your imports accordingly. For more details, see the @astrojs/markdown README.

:::tip Astro now has support for MDX through our MDX integration. MDX gives you the ability to include both Markdown and imported components in the same file. MDX can be good alternative for the <Markdown /> component due to its large community and stable APIs. :::

Migrate to v1.0.0-beta

On April 4, 2022 we released the Astro 1.0 Beta! 🎉

If you are coming from v0.25 or earlier, make sure you have read and followed the v0.26 Migration Guide below, which contained several major breaking changes.

The v1.0.0-beta.0 release of Astro contained no breaking changes. Below are small changes that were introduced during the beta period.

Changed: RSS Feeds

RSS feeds should now be generated using the @astrojs/rss package, as described in our RSS guide.

Migrate to v0.26

New Configuration API

Our Configuration API has been redesigned to solve a few glaring points of confusion that had built up over the last year. Most of the configuration options have just been moved or renamed, which will hopefully be a quick update for most users. A few options have been refactored more heavily, and may require a few additional changes:

• .buildOptions.site has been replaced with .site (your deployed domain) and a new .base (your deployed subpath) option.
• .markdownOptions has been replaced with .markdown, a mostly similar config object with some small changes to simplify Markdown configuration.
• .sitemap has been moved into the @astrojs/sitemap integration.

If you run Astro with legacy configuration, you will see a warning with instructions on how to update. See our updated Configuration Reference for more information on upgrading.

Read RFC0019 for more background on these changes.

New Markdown API

Astro v0.26 releases a brand new Markdown API for your content. This included three major user-facing changes:

• You can now import/import() markdown content directly using an ESM import.
• A new Astro.glob() API, for easier glob imports (especially for Markdown).
• BREAKING CHANGE: Astro.fetchContent() has been removed and replaced by Astro.glob()
• BREAKING CHANGE: Markdown objects have an updated interface.

// v0.25
let allPosts = Astro.fetchContent('./posts/*.md');
// v0.26+
let allPosts = await Astro.glob('./posts/*.md');

When migrating, be careful about the new Markdown object interface. Frontmatter, for example, has been moved to the .frontmatter property, so references like post.title should change to post.frontmatter.title.

This should solve many issues for Markdown users, including some nice performance boosts for larger sites.

Read RFC0017 for more background on these changes.

New Default Script Behavior

<script> tags in Astro components are now built, bundled and optimized by default. This completes a long-term move to make our Astro component syntax more consistent, matching the default-optimized behavior our <style> tags have today.

This includes a few changes to be aware of:

• BREAKING: <script hoist> is the new default <script> behavior. The hoist attribute has been removed. To use the new default behaviour, make sure there are no other attributes on the <script> tag. For example, remove type="module" if you were using it before.
• New <script is:inline> directive, to revert a <script> tag to previous default behavior (unbuilt, unbundled, untouched by Astro).
• New <style is:inline> directive, to leave a style tag inline in the page template (similar to previous <script> behavior).
• New <style is:global> directive to replace <style global> in a future release.

// v0.25
<script hoist type="module">
// v0.26+
<script>

See how to use client-side scripts in Astro for full details.

Read RFC0016 for more background on these changes.

Updated Astro.request API

Astro.request has been changed from our custom object to a standard Request object. This is part of a project to use more web standard APIs, especially where SSR is concerned.

This includes a few changes to be aware of:

• Change Astro.request to become a Request object.
• Move Astro.request.params to Astro.params.
• Move Astro.request.canonicalURL to Astro.canonicalURL.

Read RFC0018 for more background on these changes.

Other Changes

• Improve Astro.slots API to support passing arguments to function-based slots. This allows for more ergonomic utility components that accept a callback function as a child.
• Update CLI output formatting, especially around error reporting.
• Update @astrojs/compiler, fixing some bugs related to RegExp usage in frontmatter

Migrate to v0.25

Astro Integrations

The renderers config has been replaced by a new, official integration system! This unlocks some really exciting new features for Astro. You can read our Using Integrations guide for more details on how to use this new system.

Integrations replace our original renderers concept, and come with a few breaking changes and new defaults for existing users. These changes are covered below.

Removed: Built-in Framework Support

Previously, React, Preact, Svelte, and Vue were all included with Astro by default. Starting in v0.25.0, Astro no longer comes with any built-in renderers. If you did not have a renderers configuration entry already defined for your project, you will now need to install those frameworks yourself.

Read our step-by-step walkthrough to learn how to add a new Astro integration for the framework(s) that you currently use.

Deprecated: Renderers

:::note Read this section if you have custom "renderers" already defined in your configuration file. :::

The new integration system replaces the previous renderers system, including the published @astrojs/renderer-* packages on npm. Going forward, @astrojs/renderer-react becomes @astrojs/react, @astrojs/renderer-vue becomes @astrojs/vue, and so on.

To migrate: update Astro to v0.25.0 and then run astro dev or astro build with your old configuration file containing the outdated "renderers" config. You will immediately see a notice telling you the exact changes you need to make to your astro.config.mjs file, based on your current config. You can also update your packages yourself, using the table below.

For a deeper walkthrough, read our step-by-step guide to learn how to replace existing renderers with a new Astro framework integration.

# Install your new integrations and frameworks:
# (Read the full walkthrough: https://docs.astro.build/en/guides/integrations-guide)
npm install @astrojs/lit lit
npm install @astrojs/react react react-dom

// Then, update your `astro.config.mjs` file:
// (Read the full walkthrough: https://docs.astro.build/en/guides/integrations-guide)



</script>

Note that Astro will bundle this external script with the rest of your client-side JavaScript, and load it in the type="module" script context. Some older JavaScript files may not be written for the module context, in which case they may need to be updated to use this method.

How to Resolve Images & Other Assets

1. Absolute URL Path (Recommended)

Example: <img src="/penguin.png"> When to use this: If your asset lives inside of public/.

If you place your images inside of public/ you can safely reference them by absolute URL path directly in your component templates. This is the simplest way to reference an asset that you can use today, and it is recommended for most users who are getting started with Astro.

2. ESM Import

Example: import imgUrl from './penguin.png' When to use this: If your asset lives inside of the src/ directory, and you want automatic optimization features like filename hashing.

This works inside of any JavaScript or Astro component, and returns a resolved URL to the final image. Once you have the resolved URL, you can use it anywhere inside of the component template.

---
// Example: Astro will include this image file in your final build

---
<img src={imgUrl} />

Similar to how Astro handles CSS, the ESM import allows Astro to perform some simple build optimizations for you automatically. For example, any asset inside of src/ that is imported using an ESM import (ex: import imgUrl from './penguin.png') will have its filename hashed automatically. This can let you cache the file more aggressively on the server, improving user performance. In the future, Astro may add more optimizations like this.

Tip: If you dislike static ESM imports, Astro also supports dynamic ESM imports. We only recommend this option if you prefer this syntax: <img src={(await import('./penguin.png')).default} />.

Deprecated: <script> Default Processing

Previously, all <script> elements were read from the final HTML output and processed + bundled automatically. This behavior is no longer the default. Starting in 0.24, you must opt-in to <script> element processing via the hoist attribute. The type="module" is also required for hoisted modules.

<script>
  // Will be rendered into the HTML exactly as written!
  // ESM imports will not be resolved relative to the file.
</script>
<script type="module" hoist>
  // Processed! Bundled! ESM imports work, even to npm packages.
</script>

Migrate to v0.23

Missing Sass Error

Preprocessor dependency "sass" not found. Did you install it?

In our quest to reduce npm install size, we've moved Sass out to an optional dependency. If you use Sass in your project, you'll want to make sure that you run npm install sass --save-dev to save it as a dependency.

Deprecated: Unescaped HTML

In Astro v0.23+, unescaped HTML content in expressions is now deprecated. In future releases, content within expressions will have strings escaped to protect against unintended HTML injection.

<h1>{title}</h1> <!-- <h1>Hello <strong>World</strong></h1> -->
<h1>{title}</h1> <!-- <h1>Hello &lt;strong&gt;World&lt;/strong&gt;</h1> -->

To continue injecting unescaped HTML, you can now use set:html.

<h1>{title}</h1>
<h1 set:html={title} />

To avoid a wrapper element, set:html can work alongside <Fragment>.

<h1>{title}!</h1>
<h1><Fragment set:html={title}>!</h1>

You can also protect against unintended HTML injection with set:text.

<h1 set:text={title} /> <!-- <h1>Hello &lt;strong&gt;World&lt;/strong&gt;</h1> -->

Migrate to v0.21

Vite

Starting in v0.21, Astro is built with Vite. As a result, configurations written in snowpack.config.mjs should be moved into astro.config.mjs.

// @ts-check

/** @type {import('astro').AstroUserConfig} */

To learn more about configuring Vite, please visit their configuration guide.

Vite Plugins

In Astro v0.21+, Vite plugins may be configured within astro.config.mjs.

To learn more about Vite plugins, please visit their plugin guide.

Vite Changes to Renderers

In Astro v0.21+, plugins should now use viteConfig().

// renderer-svelte/index.js


  },
}

To learn more about Vite plugins, please visit their plugin guide.

:::note In prior releases, these were configured with snowpackPlugin or snowpackPluginOptions. :::

Aliasing

In Astro v0.21+, import aliases can be added in tsconfig.json.

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/components/*": ["src/components/*"]
    }
  }
}

File Extensions in Imports

In Astro v0.21+, files need to be referenced by their actual extension, exactly as it is on disk. In this example, Div.tsx would need to be referenced as Div.tsx, not Div.jsx.

Tailwind CSS

Ensure you have PostCSS installed. This was optional in previous releases, but is required now:

---
import Component from '../components/Component.astro'
const whereShouldIPutMyImports = "on top!"
---