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

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

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.

Variables in Scripts & Styles

In Astro v0.21, serializable server-side variables can be passed into client-side <style> or <script>.

---
// tick.astro
const foregroundColor = "rgb(221 243 228)";
const backgroundColor = "rgb(24 121 78)";
---
<style define:vars={{foregroundColor, backgroundColor}}>
  h-tick {
    background-color: var(--backgroundColor);
    border-radius: 50%;
    color: var(--foregroundColor);
    height: 15px;
    width: 15px;
  }
</style>
<h-tick>✓</h-tick>

Components in Markdown

In Astro v0.21, Components from any framework can be used within Markdown files.

---
Layout: '...'
setup: |
  import MyReactComponent from '../components/MyReactComponent.jsx'
---

# Hydrating on visibility

<MyReactComponent client:visible>

# Hello world!

</MyReactComponent>

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.

Environment Variables

In Astro v0.21, environment variables can be loaded from .env files in your project directory.

.env                # loaded in all cases
.env.local          # loaded in all cases, ignored by git
.env.[mode]         # only loaded in specified mode
.env.[mode].local   # only loaded in specified mode, ignored by git

For security purposes, only variables prefixed with PUBLIC_ are accessible to your code.

SECRET_PASSWORD=password123
PUBLIC_ANYBODY=there

In this example, PUBLIC_ANYBODY will be available as import.meta.env.PUBLIC_ANYBODY in server or client code, while SECRET_PASSWORD will not.

In prior releases, these variables were prefixed with SNOWPACK_PUBLIC_ and required the @snowpack/plugin-env plugin.

File Extensions

In Astro v0.21, files need to be referenced by their actual extension, exactly as it is on disk.

// Div.tsx
export default function Div(props) {
  return <div />;
}

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

// Div.scss
div {
  all: unset;
}

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

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.

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

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

Styling Changes

Autoprefixer

Autoprefixer is no longer run by default. To enable:

1. Install the latest version (npm i autoprefixer)
2. Create a postcss.config.cjs file at the root of your project with:

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

Tailwind CSS

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

1. Intall the latest version of postcss (npm i -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