Add Migration Guide to docs (withastro#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 <[email protected]>

* 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 <[email protected]>
Co-authored-by: Fred K. Schott <[email protected]>

.nvmrc

@@ -1 +1 @@
-14.16.1
+14.18.1

docs/.nvmrc

@@ -0,0 +1 @@
+14.18.1

docs/.stackblitzrc

@@ -0,0 +1,6 @@
+{
+ "startCommand": "npm start",
+ "env": {
+ "ENABLE_CJS_IMPORTS": true
+ }
+}

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',
- },
- },
- },
+ ]
 });

docs/jsconfig.json

@@ -0,0 +1,8 @@
+{
+ "compilerOptions": {
+ "baseUrl": ".",
+ "paths": {
+ "~/*": ["src/*"]
+ }
+ }
+}

docs/package.json

@@ -26,5 +26,8 @@
  },
  "dependencies": {
  "@docsearch/react": "^1.0.0-alpha.27"
+ },
+ "volta": {
+ "node": "14.18.1"
  }
 }

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' },

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

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

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

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

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

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

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

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
 

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