Add Migration Guide to docs (#1751)

* Add Migration Guide to docs

* edit: replace astro.config.js with astro.config.mjs

* edit: use plain object in define:vars example

* edit: improve 'components in markdown' documentation

* edit: use astro resolve in file reference documentation example

* edit: rename 'writing plugins' heading to 'custom renderers'

Co-authored-by: Nate Moore <natemoo-re@users.noreply.github.com>

* edit: fix PUBLIC_ environment variable example

* edit: fix define:vars variable in example

* edit: remove top-level alias documentation

* edit: cleanup "passing variables into scripts and styles" description

* Update migration-guide.md

* Update migration-guide.md

* update deployment config

* update configuration

* fix some errors and write a commit message about it

* move the migration guide

* update documentation

* add migration guide to sidebar

Co-authored-by: Nate Moore <natemoo-re@users.noreply.github.com>
Co-authored-by: Fred K. Schott <fkschott@gmail.com>

16 files changed, 237 insertions, 18 deletions

diff --git a/.nvmrc b/.nvmrc
index 6b17d228d..31102b28d 100644
--- a/.nvmrc
+++ b/.nvmrc
@@ -1 +1 @@
-14.16.1
+14.18.1
diff --git a/docs/.nvmrc b/docs/.nvmrc
new file mode 100644
index 000000000..31102b28d
--- /dev/null
+++ b/docs/.nvmrc
@@ -0,0 +1 @@
+14.18.1
diff --git a/docs/.stackblitzrc b/docs/.stackblitzrc
new file mode 100644
index 000000000..0dfa8f1e0
--- /dev/null
+++ b/docs/.stackblitzrc
@@ -0,0 +1,6 @@
+{
+  "startCommand": "npm start",
+  "env": {
+    "ENABLE_CJS_IMPORTS": true
+  }
+}
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index 4a1bc99f6..4f3e7e688 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -8,13 +8,5 @@ export default /** @type {import('astro').AstroUserConfig} */ ({
     '@astrojs/renderer-preact',
     // Needed for Algolia search component
     '@astrojs/renderer-react',
-  ],
-  vite: {
-    resolve: {
-      alias: {
-        '~': '/src',
-        components: '/src/components',
-      },
-    },
-  },
+  ]
 });
diff --git a/docs/jsconfig.json b/docs/jsconfig.json
new file mode 100644
index 000000000..56c62bf9f
--- /dev/null
+++ b/docs/jsconfig.json
@@ -0,0 +1,8 @@
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "~/*": ["src/*"]
+    }
+  }
+}
diff --git a/docs/package.json b/docs/package.json
index 1272019f6..5920e8b00 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -26,5 +26,8 @@
   },
   "dependencies": {
     "@docsearch/react": "^1.0.0-alpha.27"
+  },
+  "volta": {
+    "node": "14.18.1"
   }
 }
diff --git a/docs/src/config.ts b/docs/src/config.ts
index 95b1b29ff..cd75ac566 100644
--- a/docs/src/config.ts
+++ b/docs/src/config.ts
@@ -6,6 +6,7 @@ export const SIDEBAR = {
     { text: 'Installation', link: 'installation' },
     { text: 'Themes', link: 'themes' },
     { text: 'Astro vs. X', link: 'comparing-astro-vs-other-tools' },
+    { text: 'Migrate to v0.21', link: 'migration/0.21.0' },
 
     { text: 'Basics', header: true },
     { text: 'Project Structure', link: 'core-concepts/project-structure' },
diff --git a/docs/src/pages/es/guides/deploy.md b/docs/src/pages/es/guides/deploy.md
index 3f2226b02..276b80d8e 100644
--- a/docs/src/pages/es/guides/deploy.md
+++ b/docs/src/pages/es/guides/deploy.md
@@ -37,7 +37,7 @@ Por defecto, la salida de la compilación se colocará en `dist/`. Puedes desple
 1. Establece el `buildOptions.site` correcto en `astro.config.mjs`.
 2. Dentro de tu proyecto, crea `deploy.sh` con el siguiente contenido (sin comentar las líneas apropiadas) y ejecútalo para implementar:
 
-   ```bash{13,20,23}
+   ```bash
    #!/usr/bin/env sh
 
    # abortar en errores
diff --git a/docs/src/pages/es/guides/markdown-content.astro b/docs/src/pages/es/guides/markdown-content.astro
index be955b275..562511baf 100644
--- a/docs/src/pages/es/guides/markdown-content.astro
+++ b/docs/src/pages/es/guides/markdown-content.astro
@@ -1,7 +1,7 @@
 ---
 import { Markdown } from 'astro/components';
 import MainLayout from '~/layouts/MainLayout.astro';
-const [content] = Astro.fetchContent('~/pages/guides/markdown-content.md');
+const [content] = Astro.fetchContent('/src/pages/guides/markdown-content.md');
 ---
 
 <MainLayout content="{content}">
diff --git a/docs/src/pages/es/guides/pagination.astro b/docs/src/pages/es/guides/pagination.astro
index 5c0f03be9..65c0fe3c4 100644
--- a/docs/src/pages/es/guides/pagination.astro
+++ b/docs/src/pages/es/guides/pagination.astro
@@ -1,7 +1,7 @@
 ---
 import { Markdown } from 'astro/components';
 import MainLayout from '~/layouts/MainLayout.astro';
-const [content] = Astro.fetchContent('~/pages/guides/pagination.md');
+const [content] = Astro.fetchContent('/src/pages/guides/pagination.md');
 ---
 
 <MainLayout content="{content}">
diff --git a/docs/src/pages/es/guides/publish-to-npm.astro b/docs/src/pages/es/guides/publish-to-npm.astro
index 3518e6694..a1ffac93c 100644
--- a/docs/src/pages/es/guides/publish-to-npm.astro
+++ b/docs/src/pages/es/guides/publish-to-npm.astro
@@ -1,7 +1,7 @@
 ---
 import { Markdown } from 'astro/components';
 import MainLayout from '~/layouts/MainLayout.astro';
-const [content] = Astro.fetchContent('~/pages/guides/publish-to-npm.md');
+const [content] = Astro.fetchContent('/src/pages/guides/publish-to-npm.md');
 ---
 
 <MainLayout content="{content}">
diff --git a/docs/src/pages/es/guides/styling.astro b/docs/src/pages/es/guides/styling.astro
index d2d4f788f..d15e6298f 100644
--- a/docs/src/pages/es/guides/styling.astro
+++ b/docs/src/pages/es/guides/styling.astro
@@ -1,7 +1,7 @@
 ---
 import { Markdown } from 'astro/components';
 import MainLayout from '~/layouts/MainLayout.astro';
-const [content] = Astro.fetchContent('~/pages/guides/styling.md');
+const [content] = Astro.fetchContent('/src/pages/guides/styling.md');
 ---
 
 <MainLayout content="{content}">
diff --git a/docs/src/pages/es/reference/renderer-reference.astro b/docs/src/pages/es/reference/renderer-reference.astro
index 64f41ce24..f3c703a60 100644
--- a/docs/src/pages/es/reference/renderer-reference.astro
+++ b/docs/src/pages/es/reference/renderer-reference.astro
@@ -1,7 +1,7 @@
 ---
 import { Markdown } from 'astro/components';
 import MainLayout from '~/layouts/MainLayout.astro';
-const [content] = Astro.fetchContent('~/pages/reference/renderer-reference.md');
+const [content] = Astro.fetchContent('/src/pages/reference/renderer-reference.md');
 ---
 
 <MainLayout content="{content}">
diff --git a/docs/src/pages/migration/0.21.0.md b/docs/src/pages/migration/0.21.0.md
new file mode 100644
index 000000000..5b7847cb4
--- /dev/null
+++ b/docs/src/pages/migration/0.21.0.md
@@ -0,0 +1,208 @@
+---
+layout: ~/layouts/MainLayout.astro
+title: Migrating to v0.21
+description: How to migrate projects from Astro v0.20.
+---
+
+## 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`.
+
+```js
+// @ts-check
+
+/** @type {import('astro').AstroUserConfig} */ 
+export default ({
+  renderers: [],
+  vite: {
+    plugins: []
+  }
+})
+```
+
+To learn more about configuring Vite, please visit their [configuration guide](https://vitejs.dev/config/).
+
+
+
+## Aliasing
+
+In Astro v0.21, import aliases can be added from `tsconfig.json` or `jsconfig.json`.
+
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/components/*": ["components/*"]
+    }
+  }
+}
+```
+
+_These aliases are integrated automatically into [VSCode](https://code.visualstudio.com/docs/languages/jsconfig) and other editors._
+
+
+
+## Variables in Scripts & Styles
+
+In Astro v0.21, server-side variables can be passed into client-side `<style>` or `<script>`.
+
+```astro
+---
+// tick.astro
+const colors = { foregroundColor: "rgb(221 243 228)", backgroundColor: "rgb(24 121 78)" }
+---
+<style define:vars={colors}>
+  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.
+
+```md
+---
+Layout: '...'
+setup: | 
+  import MyReactComponent from '../components/MyReactComponent.jsx'
+---
+
+# Hydrating on visibility
+
+<MyReactComponent client:visible>
+
+# Hello world!
+
+</MyReactComponent>
+```
+
+
+
+## Environment Variables
+
+In Astro v0.21, environment variables can be loaded from `.env` files in your project directory.
+
+```ini
+.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.
+
+```ini
+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.
+
+```tsx
+// 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`.
+
+```diff
+- import Div from './Div.jsx' // Astro v0.20
++ import Div from './Div.tsx' // Astro v0.21
+```
+
+This same change applies to styles.
+
+```scss
+// Div.scss
+div {
+  all: unset
+}
+```
+
+```diff
+- <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`.
+
+```js
+import { imagetools } from 'vite-imagetools'
+
+export default {
+  vite: {
+    plugins: [
+      imagetools()
+    ]
+  }
+}
+```
+
+To learn more about Vite plugins, please visit their [plugin guide](https://vitejs.dev/guide/using-plugins.html).
+
+
+
+## Custom Renderers
+
+In Astro v0.21, plugins should now use `viteConfig()`.
+
+```diff
+// 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](https://vitejs.dev/guide/using-plugins.html).
+
+> In prior releases, these were configured with `snowpackPlugin` or `snowpackPluginOptions`.
+
+
+
+[Snowpack]: https://www.snowpack.dev
+[Vite]: https://vitejs.dev
diff --git a/docs/src/pages/nl/getting-started.md b/docs/src/pages/nl/getting-started.md
index 6eb108a3b..7c2ee71f6 100644
--- a/docs/src/pages/nl/getting-started.md
+++ b/docs/src/pages/nl/getting-started.md
@@ -35,7 +35,7 @@ Onze gids over [Astro-componenten](/core-concepts/astro-components) helpt je doo
 
 ### API referentie
 
-Deze documentatiesectie is handig als je meer details wilt weten over een bepaalde Astro API. [Configuratie referentie](/reference/configuration-reference) vermeldt bijvoorbeeld alle mogelijke configuratieopties die beschikbaar zijn. [Ingebouwde Componenten Referentie](/reference/builtin-components) geeft een overzicht van alle beschikbare kerncomponenten, zoals <Markdown /> en <Code />.
+Deze documentatiesectie is handig als je meer details wilt weten over een bepaalde Astro API. [Configuratie referentie](/reference/configuration-reference) vermeldt bijvoorbeeld alle mogelijke configuratieopties die beschikbaar zijn. [Ingebouwde Componenten Referentie](/reference/builtin-components) geeft een overzicht van alle beschikbare kerncomponenten, zoals `<Markdown />` en `<Code />`.
 
 ### Documentatie versies
 
diff --git a/docs/src/pages/themes.astro b/docs/src/pages/themes.astro
index 46ee24cec..4042b0eef 100644
--- a/docs/src/pages/themes.astro
+++ b/docs/src/pages/themes.astro
@@ -1,7 +1,7 @@
 ---
 import Layout from '../layouts/MainLayout.astro';
 import Card from '../components/Card.astro';
-import {Markdown} from 'astro/components';
+import { Markdown } from 'astro/components';
 import themes from '../data/themes.json';
 import components from '../data/components.json';
 ---