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

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

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.

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);

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.

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.

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.

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

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

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

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

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.

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.

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

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.

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.

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

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} />.

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>

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.

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

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.

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.

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

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.

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

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

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.20
import 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')}>

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.

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: {},
     },
   };

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

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!"
---