Question

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.

• npm
• pnpm
• Yarn

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

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

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

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

Astro 1.0

Section titled 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

Section titled 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

Section titled 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

Section titled 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

Section titled 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

Section titled 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!

1. Install the @astrojs/mdx integration.

2. Change your existing .md file extensions to .mdx

3. Remove any setup: properties from your frontmatter, and write any import statements below the frontmatter instead.

   src/pages/posts/my-post.mdx

   ---
   layout: '../../layouts/BaseLayout.astro'setup: |  import ReactCounter from '../../components/ReactCounter.jsx'
   title: 'Migrating to MDX'
   date: 2022-07-26
   tags: ["markdown", "mdx", "astro"]
   ---import ReactCounter from '../../components/ReactCounter.jsx'
   
   
   # {frontmatter.title}
   
   
   Here is my counter component, working in MDX:
   
   
   <ReactCounter client:load />

4. Update any Astro.glob() statements that currently return .md files so that they will now return your .mdx files.

   Caution

   The object returned when importing .mdx files (including using Astro.glob) differs from the object returned when importing .md files. However, frontmatter, file, and url work identically.

5. Update any use of the <Content /> component to use the default export when importing MDX:

   src/pages/index.astro

   ---
   // Multiple imports with Astro.glob
   const mdxPosts = await Astro.glob('./posts/*.mdx');
   ---
   
   
   {mdxPosts.map(Post => <Post.default />)}

   src/pages/index.astro

   ---
   // Import a single page
   import { default as About } from './about.mdx';
   ---
   
   
   <About />

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

Section titled <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

Section titled 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

Section titled Changed: RSS Feeds

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

Migrate to v0.26

Section titled Migrate to v0.26

New Configuration API

Section titled 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

Section titled 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.25let 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

Section titled 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>

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

Section titled 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
import imgUrl from './penguin.png';
---
<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

Section titled 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

Section titled Migrate to v0.23

Missing Sass Error

Section titled 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

Section titled 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

Section titled Migrate to v0.21

Vite

Section titled 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} */
export default {
  renderers: [],
  vite: {
    plugins: [],
  },
};

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

Vite Plugins

Section titled Vite Plugins

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

import { imagetools } from 'vite-imagetools';


export default {  vite: {    plugins: [imagetools()],  },
};

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

Vite Changes to Renderers

Section titled Vite Changes to Renderers

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

renderer-svelte/index.js

import { svelte } from '@sveltejs/vite-plugin-svelte';


export default {
  name: '@astrojs/renderer-svelte',
  client: './client.js',
  server: './server.js',  snowpackPlugin: '@snowpack/plugin-svelte',  snowpackPluginOptions: { compilerOptions: { hydratable: true } },  viteConfig() {    return {      optimizeDeps: {        include: ['@astrojs/renderer-svelte/client.js', 'svelte', 'svelte/internal'],        exclude: ['@astrojs/renderer-svelte/server.js'],      },      plugins: [        svelte({          emitCss: true,          compilerOptions: { hydratable: true },        }),      ],    };  },
}

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

Note

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

Aliasing

Section titled Aliasing

In Astro v0.21+, import aliases can be added from tsconfig.json or jsconfig.json.

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

These aliases are integrated automatically into VSCode and other editors.

File Extensions in Imports

Section titled 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.

import Div from './Div.jsx' // Astro v0.20import Div from './Div.tsx' // Astro v0.21

This same change applies to a compile-to-css file like Div.scss:

<link rel="stylesheet" href={Astro.resolve('./Div.css')}><link rel="stylesheet" href={Astro.resolve('./Div.scss')}>

Removed: Components in Frontmatter

Section titled Removed: Components in Frontmatter

Previously, you could create mini Astro Components inside of the Astro Frontmatter, using JSX syntax instead of Astro’s component syntax. This was always a bit of a hack, but in the new compiler it became impossible to support. We hope to re-introduce this feature in a future release of Astro using a different, non-JSX API.

To migrate to v0.21+, please convert all JSX Astro components (that is, any Astro components created inside of another component’s frontmatter) to standalone components.

Styling Changes

Section titled Styling Changes

Autoprefixer

Section titled Autoprefixer

Autoprefixer is no longer run by default. To enable:

1. Install the latest version (npm install autoprefixer)

2. Create a postcss.config.cjs file at the root of your project with:

   module.exports = {
     plugins: {
       autoprefixer: {},
     },
   };

Tailwind CSS

Section titled Tailwind CSS

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

1. Install the latest version of postcss (npm install -D postcss)

2. Create a postcss.config.cjs file at the root of your project with:

   module.exports = {
     plugins: {
       tailwindcss: {},
     },
   };

   For more information, read the Tailwind CSS documentation

Known Issues

Section titled Known Issues

Imports on top

Section titled Imports on top

In Astro v0.21+, a bug has been introduced that requires imports inside components to be at the top of your frontmatter.

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

Upgrade Guides