From f399b687a44e5de782e269bafa86f9596a5fb309 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Thu, 10 Aug 2023 12:27:24 +0000 Subject: [PATCH 01/58] initial page --- src/content/docs/en/guides/upgrade-to/v3.mdx | 76 ++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 src/content/docs/en/guides/upgrade-to/v3.mdx diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx new file mode 100644 index 0000000000000..1b9d83b9537d6 --- /dev/null +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -0,0 +1,76 @@ +--- +title: Upgrade to Astro v3 +description: How to upgrade your project to the latest version of Astro. +i18nReady: false +--- +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import FileTree from '~/components/FileTree.astro' + + +This guide will help you migrate from Astro v2 to Astro v3. + +Need to upgrade an older project to v2? See our [older migration guide](/en/guides/upgrade-to/v2/). + +## Upgrade Astro + +Update your project's version of Astro to the latest version using your package manager. If you're using Astro integrations, please also update those to the latest version. + + + + ```shell + # Upgrade to Astro v3.x + npm install astro@latest + + # Example: upgrade React and Tailwind integrations + npm install @astrojs/react@latest @astrojs/tailwind@latest + ``` + + + ```shell + # Upgrade to Astro v3.x + pnpm install astro@latest + + # Example: upgrade React and Tailwind integrations + pnpm install @astrojs/react@latest @astrojs/tailwind@latest + ``` + + + ```shell + # Upgrade to Astro v3.x + yarn add astro@latest + + # Example: upgrade React and Tailwind integrations + yarn add @astrojs/react@latest @astrojs/tailwind@latest + ``` + + + +## Astro v3.0 Breaking Changes + +Astro v3.0 includes some breaking changes, as well as the removal of some previously deprecated features. If your project doesn't work as expected after upgrading to v3.0, check this guide for an overview of all breaking changes and instructions on how to update your codebase. + +See [the changelog](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md) for full release notes. + +### Removed: Support for Node 16 + +Node 16 is scheduled to reach its End of Life in September 2023. + +Astro v3.0 drops Node 16 support entirely, so that all Astro users can take advantage of Node's more modern features. + +#### What should I do? + + Check that both your development environment and your deployment environment are using **Node `18.14.1` or later**. + +1. Check your local version of Node using: + + ```sh + node -v + ``` + + If your local development environment needs upgrading, [install Node](https://nodejs.org/en/download/). + + +2. Check your [deployment environment's](/en/guides/deploy/) own documentation to verify that they support Node 18. + + You can specify Node `18.14.1` for your Astro project either in a dashboard configuration setting, or a `.nvmrc` file. + From 1f7eeba2b218a2894d29d3068f616c259fcf60f0 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Thu, 10 Aug 2023 13:00:44 +0000 Subject: [PATCH 02/58] a few entries to get us started --- src/content/docs/en/guides/upgrade-to/v3.mdx | 92 ++++++++++++++++++++ 1 file changed, 92 insertions(+) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 1b9d83b9537d6..2856d3888aa26 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -74,3 +74,95 @@ Astro v3.0 drops Node 16 support entirely, so that all Astro users can take adva You can specify Node `18.14.1` for your Astro project either in a dashboard configuration setting, or a `.nvmrc` file. +### Reserved: `src/assets/` + +Astro v3.0 now includes the new image services API for optimizing your image assets. This API reserves `src/assets/` as a special folder, with a built-in import alias: `~/assets` for referencing assets located here. + +#### What should I do? + +No change is required, and there will be no conflicts with an existing `src/assets/` folder. However, you will now have access to the built-in import alias and can choose to rename your asset imports within your files. This folder is not required, and your assets may continued to be located anywhere. + +### Changed: automatic flattening of `getStaticPaths()`'s return value + +:::note[Example needed] +Find an example of returning an array of an array +::: + +In Astro v2.x, we would magically flatten the result of `getStaticPaths()` automatically for the user, so if you returned an array of array, it would still work + +Astro v3.0 we changed this in favour of the user doing it themselves when they need to, in line with how we typically prefer for users to do explicit things. + +Removed automatic flattening of getStaticPaths result. .flatMap and .flat should now be used to ensure that you’re returning a flat array. + +#### What should I do? + +If you're returning an array of arrays instead of an array of object (as you should), please flatten it using .flat(), or if you're using a .map(), use .flatMap() instead + +A [error message indicating that `getStaticPath()`'s return value must be an array of objects](/en/reference/errors/invalid-get-static-paths-entry/#what-went-wrong) will be provided if you need to update your code. + +### Changed: `build.excludeMiddleware` and `build.split` options have been moved to adapter config + +In Astro v2.x, `build.excludeMiddleware` and `build.split` could be used to change how specific files were emitted. + +Astro v3.0, these build config options have been replaced with new adapter configuruation options. + +#### What should I do? + +Update the config file to use the option **in the adapter**. + +```diff +import { defineConfig } from "astro/config"; +import vercel from "@astrojs/vercel/serverless"; + +export default defineConfig({ +- build: { +- excludeMiddleware: true +- }, + adapter: vercel({ ++ edgeMiddleware: true + }), +}); +``` + +```diff +import { defineConfig } from "astro/config"; +import vercel from "@astrojs/vercel/serverless"; + +export default defineConfig({ +- build: { +- split: true +- }, + adapter: vercel({ ++ functionPerRoute: true + }), +}); +``` + +```diff +import { defineConfig } from "astro/config"; +import netlify from "@astrojs/netlify/functions"; + +export default defineConfig({ +- build: { +- excludeMiddleware: true +- }, + adapter: netlify({ ++ edgeMiddleware: true + }), +}); +``` + +```diff +import { defineConfig } from "astro/config"; +import netlify from "@astrojs/netlify/functions"; + +export default defineConfig({ +- build: { +- split: true +- }, + adapter: netlify({ ++ functionPerRoute: true + }), +}); +``` + From ef1325ce62021c74552cea1de4eeb57d1b553fed Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Thu, 10 Aug 2023 13:23:33 +0000 Subject: [PATCH 03/58] added some more entries --- src/content/docs/en/guides/upgrade-to/v3.mdx | 98 +++++++++++++++----- 1 file changed, 76 insertions(+), 22 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 2856d3888aa26..066144f9a2b71 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -110,59 +110,113 @@ Astro v3.0, these build config options have been replaced with new adapter confi Update the config file to use the option **in the adapter**. -```diff +```astro title="astro.mjs.config" del={5-7} ins={9} import { defineConfig } from "astro/config"; import vercel from "@astrojs/vercel/serverless"; export default defineConfig({ -- build: { -- excludeMiddleware: true -- }, - adapter: vercel({ -+ edgeMiddleware: true - }), + build: { + excludeMiddleware: true + }, + adapter: vercel({ + edgeMiddleware: true + }), }); ``` -```diff +```astro title="astro.mjs.config" del={5-7} ins={9} import { defineConfig } from "astro/config"; import vercel from "@astrojs/vercel/serverless"; export default defineConfig({ -- build: { -- split: true -- }, + build: { + split: true + }, adapter: vercel({ -+ functionPerRoute: true + functionPerRoute: true }), }); ``` -```diff +```astro title="astro.mjs.config" del={5-7} ins={9} import { defineConfig } from "astro/config"; import netlify from "@astrojs/netlify/functions"; export default defineConfig({ -- build: { -- excludeMiddleware: true -- }, + build: { + excludeMiddleware: true + }, adapter: netlify({ -+ edgeMiddleware: true + edgeMiddleware: true }), }); ``` -```diff +```astro title="astro.mjs.config" del={5-7} ins={9} import { defineConfig } from "astro/config"; import netlify from "@astrojs/netlify/functions"; export default defineConfig({ -- build: { -- split: true -- }, + build: { + split: true + }, adapter: netlify({ -+ functionPerRoute: true + functionPerRoute: true }), }); ``` +### Changed: default image service to Sharp instead of Squoosh + +In Astro v2.x, Squoosh was the default image service. + +Astro v3.0, Sharp is now the default image service. + +#### What should I do? + +Sharp is now the default image service used for Astro. + +You no longer need to install the dependency locally in your project. + +Uninstall Sharp using your package manager, or by removing manually from your `package.json`. + +If you would prefer to continue to use Squoosh to transform your images, update your config with the following: + +```ts title="astro.config.mjs" ins={4-6} +import { defineConfig, squooshImageService } from "astro/config"; + +export default defineConfig({ + image: { + service: squooshImageService(), + } +}) +``` + +### Changed: casing in function endpoints + +In Astro v2.x, endpoints were defined using lowercase function names: `get`, `post`, `put`, `all`, and `del`. + +Astro v3.0, uses uppercase function names. + +#### What should I do? + +Rename functions to uppercase equivalent: + +- `get` to `GET` +- `post` to `POST` +- `put` to `PUT` +- `all` to `ALL` +- `del` to `DELETE` + +:::note[Confirm with Ema] +Does `del` also become `DEL` and / or `DELETE`? + +Sarah prefers showing `DEL` only (for consistency) +::: + +```ts title="endpoint.ts" del={1} ins={2} +export function get() { +export function GET() { + return new Response(JSON.stringify({ "title": "Bob's blog" })); +} +``` From a6a08e621a6f095692100821d9bdb510c39bad29 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Thu, 10 Aug 2023 13:55:58 +0000 Subject: [PATCH 04/58] document Astro.cookies, compressHTML and default port --- src/content/docs/en/guides/upgrade-to/v3.mdx | 55 ++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 066144f9a2b71..7142508a11064 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -220,3 +220,58 @@ export function GET() { return new Response(JSON.stringify({ "title": "Bob's blog" })); } ``` + +### Changed: Behaviour when `Astro.cookies.get(key)` doesn't exist + +In Astro v2.x, `Astro.cookies.get(key)` would always return a `AstroCookie` object, even if the cookie did not exist. To check for the existence you needed to use `Astro.cookies.has(key)`. + +Astro v3.0 `Astro.cookies.get(key)` will return `undefined` if the cookie does not exist. + +#### What should I do? + +This change will not break existing code that checks for the existance of the `Astro.cookie` object before using `Astro.cookies.get(key)`, but is now no longer required. You can safely remove this code. + +You can safely skip `has()` and check if the value is `undefined`: + +```ts +// before: +if (Astro.cookies.has(id)) { + const id = Astro.cookies.get(id)!; +} + +//after: +const id = Astro.cookies.get(id); +if (id) { + // TypeScript knows id is an AstroCookie +} +``` + +### Changed: the default value of `compressHTML` + +In Astro v2.x, Astro only compressed the emitted HTML by explicitly setting the configuration to `true`. + +Astro v3.0 now compresses emitted HTML by default. + +#### What should I do? + +You can now remove `compressHTML: true` from your configuration as this is now the default behavior. + +```ts title="astro.config.mjs" del={4} +import { defineConfig } from "astro/config"; + +export default defineConfig({ + compressHTML: true +}) +``` + +You must now set `compressHTML: false` to opt out of HTML compression. + +### Changed: default port used + +In Astro v2.x, Astro ran on port `3000` by default. + +Astro v3.0 changes the default port to `4321`. + +#### What should I do? + +Update any existing references to `localhost:3000`, for example in tests or in your `README` to reflect the new port `localhost:4321`. From 58c0d693f389aa52540429f7a18071fc8f322b07 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Tue, 15 Aug 2023 15:53:42 +0000 Subject: [PATCH 05/58] updates sidebar entry and adds more items to guide --- src/content/docs/en/guides/upgrade-to/v3.mdx | 55 ++++++++++++++++++++ src/i18n/en/nav.ts | 2 +- 2 files changed, 56 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 7142508a11064..eb6b6e5689b3a 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -275,3 +275,58 @@ Astro v3.0 changes the default port to `4321`. #### What should I do? Update any existing references to `localhost:3000`, for example in tests or in your `README` to reflect the new port `localhost:4321`. + +### Changed: TypeScript minimum version + +In Astro v2.x, the `tsconfig.json` presets include support for both TypeScript 4.x and 5.x. + +Astro v3.0 updates the `tsconfig.json` presets to only support TypeScript 5.x. Astro now assumes that you use TypeScript 5.0 (March 2023), or that your editor includes it (e.g. VS Code 1.77) + +#### What should I do? + +Update your TypeScript version to at least v5.0. + +```bash +npm install typescript@latest --save-dev +``` + +### Changed `astro check` is now an external package + +In Astro v2.x, `astro check` was included in Astro by default and its dependencies were bundled in Astro. This meant a larger package whether or not you ever used `astro check` and also prevented you from having control over the version of TypeScript and the Astro Language Server to use. + + +Astro v3.0 moves the `astro check` command out of Astro core and now requires an external package `@astrojs/check`. Additionally, you must install `typescript` in your project. + +#### What should I do? + +Run the `astro check` command after upgrading to Astro v3.0 and follow the prompts to install the required dependencies, or manually install `@astrojs/check` and `typescript` into your project. + +### Added: simple asset support for Cloudflare, Deno, Vercel Edge and Netlify Edge + In Astro v2.x, using the assets feature in Cloudflare, Deno, Vercel Edge and Netlify Edge errors in runtime as the environments do not support Astro's builtin Squoosh and Sharp image optimization. + + Astro v3.0 allows these environments to work without errors, but does not perform any image transformation and processing. However, you would still get benefits, e.g. no Cumulative Layout Shift (CLS), enforced alt attribute, etc. + + What should I do? + If you previously avoided the assets feature due these constraints, you can now use them without issues. You can also use the no-op image service to explicitly opt-in to this behaviour: + + ``` + // astro.config.mjs + export default { + image: { + service: { + entrypoint: 'astro/assets/services/noop' + } + } + } + ``` + +In Astro v2.x, you would get an error log in development. When building a project, the build would fail. + +Astro V3 still displays the error log, but now you can build the project. + +When using an adapter that supports neither Squoosh or Sharp, Astro will now automatically use an image service that does not support processing, but still provides the other benefits of `astro:assets` such as enforcing `alt`, no CLS etc to users. Should be noted that it does no transformations or processing, but you still get all the other benefits (no CLS, alt enforced, etc). All of those benefits are part of the image service, if you make your own, you lose those benefits unless you make it yourself + + +## Known Issues + +There are currently no known issues. diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts index 559771988165c..15ab74e540e29 100644 --- a/src/i18n/en/nav.ts +++ b/src/i18n/en/nav.ts @@ -12,7 +12,7 @@ export default [ { text: 'Getting Started', slug: 'getting-started', key: 'getting-started' }, { text: 'Installation', slug: 'install/auto', key: 'install' }, { text: 'Editor Setup', slug: 'editor-setup', key: 'editor-setup' }, - { text: 'Upgrade to v2', slug: 'guides/upgrade-to/v2', key: 'guides/upgrade-to/v2' }, + { text: 'Upgrade to v3', slug: 'guides/upgrade-to/v3', key: 'guides/upgrade-to/v3' }, { text: 'Core Concepts', header: true, type: 'learn', key: 'coreConcepts' }, { text: 'Why Astro', slug: 'concepts/why-astro', key: 'concepts/why-astro' }, From d8700434434cc7db107cd7feaf87cca6bee324de Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Tue, 15 Aug 2023 17:21:01 +0000 Subject: [PATCH 06/58] update sidebar in international versions --- src/i18n/es/nav.ts | 2 +- src/i18n/it/nav.ts | 2 +- src/i18n/ja/nav.ts | 2 +- src/i18n/ko/nav.ts | 2 +- src/i18n/pl/nav.ts | 2 +- src/i18n/pt-br/nav.ts | 2 +- src/i18n/ru/nav.ts | 2 +- src/i18n/zh-cn/nav.ts | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/i18n/es/nav.ts b/src/i18n/es/nav.ts index 3a8fa07b7dfda..dfa351d531712 100644 --- a/src/i18n/es/nav.ts +++ b/src/i18n/es/nav.ts @@ -3,7 +3,7 @@ export default [ { text: 'Cómo Empezar', slug: 'getting-started', key: 'getting-started' }, { text: 'Instalación', slug: 'install/auto', key: 'install' }, { text: 'Configuración del Editor', slug: 'editor-setup', key: 'editor-setup' }, - { text: 'Actualizar a v2', slug: 'guides/upgrade-to/v2', key: 'guides/upgrade-to/v2' }, + { text: 'Actualizar a v3', slug: 'guides/upgrade-to/v3', key: 'guides/upgrade-to/v3' }, { text: 'Conceptos Básicos', header: true, type: 'learn', key: 'coreConcepts' }, { text: 'Por qué Astro', slug: 'concepts/why-astro', key: 'concepts/why-astro' }, diff --git a/src/i18n/it/nav.ts b/src/i18n/it/nav.ts index ca7d48777af32..28c53cf8e7859 100644 --- a/src/i18n/it/nav.ts +++ b/src/i18n/it/nav.ts @@ -3,7 +3,7 @@ export default [ { text: 'Per Iniziare', slug: 'getting-started', key: 'getting-started' }, { text: 'Installazione', slug: 'install/auto', key: 'install' }, { text: 'Setup dell’Editor', slug: 'editor-setup', key: 'editor-setup' }, - { text: 'Aggiorna a v2', slug: 'guides/upgrade-to/v2', key: 'guides/upgrade-to/v2' }, + { text: 'Aggiorna a v3', slug: 'guides/upgrade-to/v3', key: 'guides/upgrade-to/v3' }, { text: 'Concetti Chiave', header: true, type: 'learn', key: 'coreConcepts' }, { text: 'Perché Astro', slug: 'concepts/why-astro', key: 'concepts/why-astro' }, diff --git a/src/i18n/ja/nav.ts b/src/i18n/ja/nav.ts index 1137b17cdbe09..af267c3671f93 100644 --- a/src/i18n/ja/nav.ts +++ b/src/i18n/ja/nav.ts @@ -6,7 +6,7 @@ export default NavDictionary({ 'getting-started': 'はじめに', install: 'インストール', 'editor-setup': 'エディタのセットアップ', - 'guides/upgrade-to/v2': 'v2へのアップグレード', + 'guides/upgrade-to/v3': 'v3へのアップグレード', // Core Concepts coreConcepts: 'コアコンセプト', diff --git a/src/i18n/ko/nav.ts b/src/i18n/ko/nav.ts index 0728a85b0d555..036a8fd4a57d0 100644 --- a/src/i18n/ko/nav.ts +++ b/src/i18n/ko/nav.ts @@ -7,7 +7,7 @@ export default NavDictionary({ coreConcepts: '핵심 개념', 'concepts/why-astro': '왜 Astro인가', 'editor-setup': '에디터 설정하기', - 'guides/upgrade-to/v2': 'v2로 업그레이드 하기', + 'guides/upgrade-to/v3': 'v3로 업그레이드 하기', basics: '기본', 'core-concepts/project-structure': '프로젝트 구조', 'guides/aliases': '별칭', diff --git a/src/i18n/pl/nav.ts b/src/i18n/pl/nav.ts index 4531bf69c2792..86772e32cf2bc 100644 --- a/src/i18n/pl/nav.ts +++ b/src/i18n/pl/nav.ts @@ -6,7 +6,7 @@ export default NavDictionary({ install: 'Instalacja', 'editor-setup': 'Konfiguracja edytora', 'guides/migrate-to-astro': 'Migracja do Astro', - 'guides/upgrade-to/v2': 'Aktualizacja do Astro 2.0', + 'guides/upgrade-to/v3': 'Aktualizacja do Astro 3.0', //migrate: 'Przewodnik migracji', tutorials: 'Samouczki', 'blog-tutorial': 'Zbuduj bloga', diff --git a/src/i18n/pt-br/nav.ts b/src/i18n/pt-br/nav.ts index 42ae83011bada..af4748507b33c 100644 --- a/src/i18n/pt-br/nav.ts +++ b/src/i18n/pt-br/nav.ts @@ -5,7 +5,7 @@ export default NavDictionary({ 'getting-started': 'Introdução', install: 'Instalação', 'editor-setup': 'Configuração do Editor', - 'guides/upgrade-to/v2': 'Atualize para a v2', + 'guides/upgrade-to/v3': 'Atualize para a v3', coreConcepts: 'Principais Conceitos', 'concepts/why-astro': 'Por que Astro?', 'concepts/islands': 'Ilhas Astro', diff --git a/src/i18n/ru/nav.ts b/src/i18n/ru/nav.ts index 5ccb91966f67f..17621f74d5ebc 100644 --- a/src/i18n/ru/nav.ts +++ b/src/i18n/ru/nav.ts @@ -51,7 +51,7 @@ export default NavDictionary({ 'guides/content-collections': 'Коллекции контента', 'guides/migrate-to-astro': 'Перейти на Astro', 'guides/testing': 'Тестирование', - 'guides/upgrade-to/v2': 'Обновление до v2', + 'guides/upgrade-to/v3': 'Обновление до v3', 'reference/error-reference': 'Справочник по ошибкам', tutorials: 'Обучение', examples: 'Рецепты', diff --git a/src/i18n/zh-cn/nav.ts b/src/i18n/zh-cn/nav.ts index 0a56350e8052d..9a1a3afd3c1a7 100644 --- a/src/i18n/zh-cn/nav.ts +++ b/src/i18n/zh-cn/nav.ts @@ -5,7 +5,7 @@ export default NavDictionary({ 'getting-started': '入门指南', install: '安装', 'editor-setup': '编辑器设置', - 'guides/upgrade-to/v2': '升级到 v2', + 'guides/upgrade-to/v3': '升级到 v3', coreConcepts: '核心理念', 'concepts/why-astro': '为什么选择Astro', From 95448d0658c6f41e0f7e86c16bc9929ab5ebd61f Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Tue, 15 Aug 2023 14:58:31 -0300 Subject: [PATCH 07/58] add more entries --- src/content/docs/en/guides/upgrade-to/v3.mdx | 42 ++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index eb6b6e5689b3a..6585fd3bd60a2 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -327,6 +327,48 @@ Astro V3 still displays the error log, but now you can build the project. When using an adapter that supports neither Squoosh or Sharp, Astro will now automatically use an image service that does not support processing, but still provides the other benefits of `astro:assets` such as enforcing `alt`, no CLS etc to users. Should be noted that it does no transformations or processing, but you still get all the other benefits (no CLS, alt enforced, etc). All of those benefits are part of the image service, if you make your own, you lose those benefits unless you make it yourself +### Removed: `` component + +In Astro v2.x, Astro deprecated the `` component and moved it to an external package. + +Astro v3.0 comletely removes the package `@astrojs/markdown-component`, so Astro's `` component will no longer work in your project. + +#### What should I do? + +Uninstall the `@astrojs/markdown-component` package. To continue using a similar `` component in your code, consider using [community integrations](https://astro.build/integrations/) that provide a similar component like https://github.com/natemoo-re/astro-remote, and be sure to update your component imports and attributes as necessary according to the integration's own documentation. Otherwise, delete all references to importing Astro's `` component and the component itself in your `.astro` files. You will need to rewrite your content as HTML directly or [import Markdown](/en/guides/markdown-content/#importing-markdown) from an `.md` file. + +### Removed: camelCase transformations + +In Astro 2.x, Astro automatically transformed camelCase CSS variable names passed to the `style` attribute of an HTML element. + +Astro 3.0 removes backwards-compatible kebab-case transform for these camelCase CSS variable names. + +#### What should I do? + +If you were relying on Astro to transform kebab-case in your styles, update your existing styles to use the camelCase version to prevent missing styles. For example: + +```astro +--- +const myValue = "red" +--- + +
+ +
+ +
+``` + +```diff + +``` + ## Known Issues There are currently no known issues. + From 61a35a55e1491abf78da9037228c8cd58939ac90 Mon Sep 17 00:00:00 2001 From: Elian Van Cutsem Date: Wed, 16 Aug 2023 13:57:07 +0200 Subject: [PATCH 08/58] typo: fix `astro.mjs.config` to `astro.config.mjs` --- src/content/docs/en/guides/upgrade-to/v3.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 6585fd3bd60a2..b212fe18f0721 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -110,7 +110,7 @@ Astro v3.0, these build config options have been replaced with new adapter confi Update the config file to use the option **in the adapter**. -```astro title="astro.mjs.config" del={5-7} ins={9} +```astro title="astro.config.mjs" del={5-7} ins={9} import { defineConfig } from "astro/config"; import vercel from "@astrojs/vercel/serverless"; @@ -124,7 +124,7 @@ export default defineConfig({ }); ``` -```astro title="astro.mjs.config" del={5-7} ins={9} +```astro title="astro.config.mjs" del={5-7} ins={9} import { defineConfig } from "astro/config"; import vercel from "@astrojs/vercel/serverless"; @@ -138,7 +138,7 @@ export default defineConfig({ }); ``` -```astro title="astro.mjs.config" del={5-7} ins={9} +```astro title="astro.config.mjs" del={5-7} ins={9} import { defineConfig } from "astro/config"; import netlify from "@astrojs/netlify/functions"; @@ -152,7 +152,7 @@ export default defineConfig({ }); ``` -```astro title="astro.mjs.config" del={5-7} ins={9} +```astro title="astro.config.mjs" del={5-7} ins={9} import { defineConfig } from "astro/config"; import netlify from "@astrojs/netlify/functions"; From edfe8a9d4a0653ac8f92a4d87436b5749a93de17 Mon Sep 17 00:00:00 2001 From: Elian Van Cutsem Date: Wed, 16 Aug 2023 14:23:29 +0200 Subject: [PATCH 09/58] refactor: endpoint methods to uppercase variants --- .../docs/en/core-concepts/endpoints.mdx | 30 +++++++++---------- .../en/guides/backend/google-firebase.mdx | 12 ++++---- .../docs/en/guides/content-collections.mdx | 2 +- src/content/docs/en/guides/rss.mdx | 10 +++---- .../docs/en/guides/server-side-rendering.mdx | 4 +-- .../docs/en/recipes/build-forms-api.mdx | 4 +-- .../docs/en/recipes/call-endpoints.mdx | 8 ++--- src/content/docs/en/recipes/captcha.mdx | 4 +-- .../docs/en/reference/api-reference.mdx | 16 +++++----- .../en/reference/image-service-reference.mdx | 2 +- .../docs/en/tutorial/5-astro-api/4.mdx | 2 +- 11 files changed, 47 insertions(+), 47 deletions(-) diff --git a/src/content/docs/en/core-concepts/endpoints.mdx b/src/content/docs/en/core-concepts/endpoints.mdx index 157444ea56bf6..f0894ef2677d6 100644 --- a/src/content/docs/en/core-concepts/endpoints.mdx +++ b/src/content/docs/en/core-concepts/endpoints.mdx @@ -17,7 +17,7 @@ Endpoints export a `get` function (optionally `async`) that receives a [context ```ts // Example: src/pages/builtwith.json.ts // Outputs: /builtwith.json -export async function get({params, request}) { +export async function GET({params, request}) { return { body: JSON.stringify({ name: 'Astro', @@ -30,7 +30,7 @@ export async function get({params, request}) { The return object can also have an `encoding` property. It can be any valid [`BufferEncoding`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/bdd02508ddb5eebcf701fdb8ffd6e84eabf47885/types/node/buffer.d.ts#L169) accepted by Node.js' `fs.writeFile` method. For example, to produce a binary png image: ```ts title="src/pages/astro-logo.png.ts" {6} -export async function get({ params, request }) { +export async function GET({ params, request }) { const response = await fetch("https://docs.astro.build/assets/full-logo-light.png"); const buffer = Buffer.from(await response.arrayBuffer()); return { @@ -45,7 +45,7 @@ You can also type your endpoint functions using the `APIRoute` type: ```ts import type { APIRoute } from 'astro'; -export const get: APIRoute = async ({ params, request }) => { +export const GET: APIRoute = async ({ params, request }) => { ... ``` @@ -58,7 +58,7 @@ import type { APIRoute } from 'astro'; const usernames = ["Sarah", "Chris", "Dan"] -export const get: APIRoute = ({ params, request }) => { +export const GET: APIRoute = ({ params, request }) => { const id = params.id; return { body: JSON.stringify({ @@ -84,7 +84,7 @@ All endpoints receive a `request` property, but in static mode, you only have ac ```ts title="src/pages/request-path.json.ts" import type { APIRoute } from 'astro'; -export const get: APIRoute = ({ params, request }) => { +export const GET: APIRoute = ({ params, request }) => { return { body: JSON.stringify({ path: new URL(request.url).pathname @@ -109,7 +109,7 @@ Server endpoints can access `params` without exporting `getStaticPaths`, and the ```js title="src/pages/[id].json.js" import { getProduct } from '../db'; -export async function get({ params }) { +export async function GET({ params }) { const id = params.id; const product = await getProduct(id); @@ -134,7 +134,7 @@ This will respond to any request that matches the dynamic route. For example, if In SSR mode, certain providers require the `Content-Type` header to return an image. In this case, use a `Response` object to specify a `headers` property. For example, to produce a binary `.png` image: ```ts title="src/pages/astro-logo.png.ts" -export async function get({ params, request }) { +export async function GET({ params, request }) { const response = await fetch("https://docs.astro.build/assets/full-logo-light.png"); const buffer = Buffer.from(await response.arrayBuffer()); return new Response(buffer, { @@ -144,16 +144,16 @@ export async function get({ params, request }) { ``` ### HTTP methods -In addition to the `get` function, you can export a function with the name of any [HTTP method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). When a request comes in, Astro will check the method and call the corresponding function. +In addition to the `GET` function, you can export a function with the name of any [HTTP method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). When a request comes in, Astro will check the method and call the corresponding function. -You can also export an `all` function to match any method that doesn't have a corresponding exported function. If there is a request with no matching method, it will redirect to your site's [404 page](/en/core-concepts/astro-pages/#custom-404-error-page). +You can also export an `ALL` function to match any method that doesn't have a corresponding exported function. If there is a request with no matching method, it will redirect to your site's [404 page](/en/core-concepts/astro-pages/#custom-404-error-page). :::note Since `delete` is a reserved word in JavaScript, export a `del` function to match the delete method. ::: ```ts title="src/pages/methods.json.ts" -export const get: APIRoute = ({ params, request }) => { +export const GET: APIRoute = ({ params, request }) => { return { body: JSON.stringify({ message: "This was a GET!" @@ -161,7 +161,7 @@ export const get: APIRoute = ({ params, request }) => { } }; -export const post: APIRoute = ({ request }) => { +export const POST: APIRoute = ({ request }) => { return { body: JSON.stringify({ message: "This was a POST!" @@ -169,7 +169,7 @@ export const post: APIRoute = ({ request }) => { } } -export const del: APIRoute = ({ request }) => { +export const DEL: APIRoute = ({ request }) => { return { body: JSON.stringify({ message: "This was a DELETE!" @@ -177,7 +177,7 @@ export const del: APIRoute = ({ request }) => { } } -export const all: APIRoute = ({ request }) => { +export const ALL: APIRoute = ({ request }) => { return { body: JSON.stringify({ message: `This was a ${request.method}!` @@ -192,7 +192,7 @@ export const all: APIRoute = ({ request }) => { In SSR mode, the `request` property returns a fully usable [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) object that refers to the current request. This allows you to accept data and check headers: ```ts title="src/pages/test-post.json.ts" -export const post: APIRoute = async ({ request }) => { +export const POST: APIRoute = async ({ request }) => { if (request.headers.get("Content-Type") === "application/json") { const body = await request.json(); const name = body.name; @@ -212,7 +212,7 @@ The endpoint context exports a `redirect()` utility similar to `Astro.redirect`: ```js title="src/pages/links/[id].js" {14} import { getLinkUrl } from '../db'; -export async function get({ params, redirect }) { +export async function GET({ params, redirect }) { const { id } = params; const link = await getLinkUrl(id); diff --git a/src/content/docs/en/guides/backend/google-firebase.mdx b/src/content/docs/en/guides/backend/google-firebase.mdx index 6f2da2c3c847e..0fbe235e267ac 100644 --- a/src/content/docs/en/guides/backend/google-firebase.mdx +++ b/src/content/docs/en/guides/backend/google-firebase.mdx @@ -190,7 +190,7 @@ import type { APIRoute } from "astro"; import { app } from "../../../firebase/server"; import { getAuth } from "firebase-admin/auth"; -export const get: APIRoute = async ({ request, cookies, redirect }) => { +export const GET: APIRoute = async ({ request, cookies, redirect }) => { const auth = getAuth(app); /* Get token from request headers */ @@ -235,7 +235,7 @@ This is a basic implementation of the login endpoint. You can add more logic to ```ts title="src/pages/api/auth/signout.ts" import type { APIRoute } from "astro"; -export const get: APIRoute = async ({ redirect, cookies }) => { +export const GET: APIRoute = async ({ redirect, cookies }) => { cookies.delete("session", { path: "/", }); @@ -254,7 +254,7 @@ import type { APIRoute } from "astro"; import { getAuth } from "firebase-admin/auth"; import { app } from "../../../firebase/server"; -export const post: APIRoute = async ({ request, redirect }) => { +export const POST: APIRoute = async ({ request, redirect }) => { const auth = getAuth(app); /* Get form data */ @@ -586,7 +586,7 @@ import type { APIRoute } from "astro"; import { app } from "../../../firebase/server"; import { getFirestore } from "firebase-admin/firestore"; -export const post: APIRoute = async ({ request, redirect }) => { +export const POST: APIRoute = async ({ request, redirect }) => { const formData = await request.formData(); const name = formData.get("name")?.toString(); const age = formData.get("age")?.toString(); @@ -628,7 +628,7 @@ import { getFirestore } from "firebase-admin/firestore"; const db = getFirestore(app); const friendsRef = db.collection("friends"); -export const post: APIRoute = async ({ params, redirect, request }) => { +export const POST: APIRoute = async ({ params, redirect, request }) => { const formData = await request.formData(); const name = formData.get("name")?.toString(); const age = formData.get("age")?.toString(); @@ -660,7 +660,7 @@ export const post: APIRoute = async ({ params, redirect, request }) => { return redirect("/dashboard"); }; -export const del: APIRoute = async ({ params, redirect }) => { +export const DEL: APIRoute = async ({ params, redirect }) => { if (!params.id) { return new Response("Cannot find friend", { status: 404, diff --git a/src/content/docs/en/guides/content-collections.mdx b/src/content/docs/en/guides/content-collections.mdx index f3f451906fae0..5997732577d05 100644 --- a/src/content/docs/en/guides/content-collections.mdx +++ b/src/content/docs/en/guides/content-collections.mdx @@ -706,7 +706,7 @@ This guide shows you how to convert an existing Astro project with Markdown file import rss from "@astrojs/rss"; import { getCollection } from "astro:content"; - export async function get() { + export async function GET() { const posts = await getCollection('posts'); return rss({ title: 'Astro Learner | Blog', diff --git a/src/content/docs/en/guides/rss.mdx b/src/content/docs/en/guides/rss.mdx index ed5d221fc82fb..20915062a0dd8 100644 --- a/src/content/docs/en/guides/rss.mdx +++ b/src/content/docs/en/guides/rss.mdx @@ -47,7 +47,7 @@ The example file below `src/pages/rss.xml.js` will create an RSS feed at `site/r ```js title="src/pages/rss.xml.js" import rss from '@astrojs/rss'; -export function get(context) { +export function GET(context) { return rss({ // `` field in output xml title: 'Buzz’s Blog', @@ -81,7 +81,7 @@ To create an RSS feed of pages managed in [content collections](/en/guides/conte import rss from '@astrojs/rss'; import { getCollection } from 'astro:content'; -export async function get(context) { +export async function GET(context) { const blog = await getCollection('blog'); return rss({ title: 'Buzz’s Blog', @@ -128,7 +128,7 @@ This function assumes, but does not verify, that all necessary feed properties a ```js title="src/pages/rss.xml.js" "pagesGlobToRssItems" "await pagesGlobToRssItems(" import rss, { pagesGlobToRssItems } from '@astrojs/rss'; -export async function get(context) { +export async function GET(context) { return rss({ title: 'Buzz’s Blog', description: 'A humble Astronaut’s guide to the stars', @@ -166,7 +166,7 @@ import sanitizeHtml from 'sanitize-html'; import MarkdownIt from 'markdown-it'; const parser = new MarkdownIt(); -export async function get(context) { +export async function GET(context) { const blog = await getCollection('blog'); return rss({ title: 'Buzz’s Blog', @@ -188,7 +188,7 @@ When using glob imports with Markdown, you may use the `compiledContent()` helpe import rss from '@astrojs/rss'; import sanitizeHtml from 'sanitize-html'; -export function get(context) { +export function GET(context) { const postImportResult = import.meta.glob('../posts/**/*.md', { eager: true }); const posts = Object.values(postImportResult); return rss({ diff --git a/src/content/docs/en/guides/server-side-rendering.mdx b/src/content/docs/en/guides/server-side-rendering.mdx index 7b225bf73cb61..89a06dd874257 100644 --- a/src/content/docs/en/guides/server-side-rendering.mdx +++ b/src/content/docs/en/guides/server-side-rendering.mdx @@ -172,7 +172,7 @@ And for an endpoint: ```js title="src/pages/myendpoint.js" {1} export const prerender = true; -export async function get() { +export async function GET() { return { body: JSON.stringify({ message: `This is my static endpoint` }), }; @@ -186,7 +186,7 @@ For a mostly static site configured as `output: hybrid`, add `export const prere ```js title="src/pages/randomnumber.js" {1} export const prerender = false; -export async function get() { +export async function GET() { let number = Math.random(); return { body: JSON.stringify({ number, message: `Here's a random number: ${number}` }), diff --git a/src/content/docs/en/recipes/build-forms-api.mdx b/src/content/docs/en/recipes/build-forms-api.mdx index b2c5d02211e51..0edebd6c232f2 100644 --- a/src/content/docs/en/recipes/build-forms-api.mdx +++ b/src/content/docs/en/recipes/build-forms-api.mdx @@ -133,14 +133,14 @@ This recipe shows you how to send form data to an API endpoint and handle that d </UIFrameworkTabs> - 2. Create the `post` API endpoint that will receive the form data. Use `request.formData()` to process it. Be sure to validate the form values before you use them. + 2. Create the `POST` API endpoint that will receive the form data. Use `request.formData()` to process it. Be sure to validate the form values before you use them. This example sends a JSON object with a message back to the client. ```ts title="src/pages/api/feedback.ts" "request.formData()" "post" import type { APIRoute } from "astro"; - export const post: APIRoute = async ({ request }) => { + export const POST: APIRoute = async ({ request }) => { const data = await request.formData(); const name = data.get("name"); const email = data.get("email"); diff --git a/src/content/docs/en/recipes/call-endpoints.mdx b/src/content/docs/en/recipes/call-endpoints.mdx index 7492a747fb77e..cbd498869139a 100644 --- a/src/content/docs/en/recipes/call-endpoints.mdx +++ b/src/content/docs/en/recipes/call-endpoints.mdx @@ -18,7 +18,7 @@ Endpoints can be used to serve many kinds of data. This recipe calls a server en ```ts title="src/pages/api/hello.ts" import type { APIRoute } from 'astro' - export const get: APIRoute = () => { + export const GET: APIRoute = () => { return new Response( JSON.stringify({ greeting: 'Hello', @@ -27,13 +27,13 @@ Endpoints can be used to serve many kinds of data. This recipe calls a server en } ``` -2. On any Astro page, import the `get()` method from the endpoint. Call it with the [`Astro` global](/en/reference/api-reference/#astro-global) to provide the request context, and use the response on the page: +2. On any Astro page, import the `GET()` method from the endpoint. Call it with the [`Astro` global](/en/reference/api-reference/#astro-global) to provide the request context, and use the response on the page: ```astro title="src/pages/index.astro" --- - import { get } from './api/hello.ts' + import { GET } from './api/hello.ts' - let response = await get(Astro) + let response = await GET(Astro) const data = await response.json() --- diff --git a/src/content/docs/en/recipes/captcha.mdx b/src/content/docs/en/recipes/captcha.mdx index a684d3f1a7482..a587d3327ccfb 100644 --- a/src/content/docs/en/recipes/captcha.mdx +++ b/src/content/docs/en/recipes/captcha.mdx @@ -14,10 +14,10 @@ In this recipe, an API route is used to verify Google reCAPTCHA v3 without expos ## Recipe -1. Create a `post` endpoint that accepts recaptcha data, then verifies it with reCAPTCHA's API. Here, you can safely define secret values or read environment variables. +1. Create a `POST` endpoint that accepts recaptcha data, then verifies it with reCAPTCHA's API. Here, you can safely define secret values or read environment variables. ```js title="src/pages/recaptcha.js" - export async function post({ request }) { + export async function POST({ request }) { const data = await request.json(); const recaptchaURL = 'https://www.google.com/recaptcha/api/siteverify'; diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index bd6ec80ea9e77..2f57df4ceb56f 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -459,7 +459,7 @@ const orders = Array.from(Astro.locals.orders.entries()); ```ts title="endpoint.json.ts" import type { APIContext } from 'astro'; -export function get(context: APIContext) { +export function GET(context: APIContext) { // ... } ``` @@ -483,7 +483,7 @@ export function getStaticPaths() { ]; } -export function get({ params }: APIContext) { +export function GET({ params }: APIContext) { return { body: JSON.stringify({ id: params.id }) }; @@ -507,7 +507,7 @@ export function getStaticPaths() { ]; } -export function get({ props }: APIContext) { +export function GET({ props }: APIContext) { return { body: JSON.stringify({ author: props.author }), }; @@ -523,7 +523,7 @@ A standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) o ```ts import type { APIContext } from 'astro'; -export function get({ request }: APIContext) { +export function GET({ request }: APIContext) { return { body: `Hello ${request.url}` } @@ -551,7 +551,7 @@ Specifies the [IP address](https://en.wikipedia.org/wiki/IP_address) of the requ ```ts import type { APIContext } from 'astro'; -export function get({ clientAddress }: APIContext) { +export function GET({ clientAddress }: APIContext) { return { body: `Your IP address is: ${clientAddress}` } @@ -574,7 +574,7 @@ See also: [Astro.site](#astrosite) ```ts title="src/pages/site-info.json.ts" import type { APIContext } from 'astro'; -export function get({ generator, site }: APIContext) { +export function GET{ generator, site }: APIContext) { const body = JSON.stringify({ generator, site }); return new Response(body); } @@ -589,7 +589,7 @@ See also: [Astro.generator](#astrogenerator) ```ts import type { APIContext } from 'astro'; -export function get({ redirect }: APIContext) { +export function GET({ redirect }: APIContext) { return redirect('/login', 302); } ``` @@ -618,7 +618,7 @@ API endpoints can only read information from `context.locals`: ```ts title="src/pages/hello.ts" import type { APIContext } from 'astro'; -export function get({ locals }: APIContext) { +export function GET({ locals }: APIContext) { return { body: locals.title // "Default Title" } diff --git a/src/content/docs/en/reference/image-service-reference.mdx b/src/content/docs/en/reference/image-service-reference.mdx index b4eab6eb54852..cbfee55af0af8 100644 --- a/src/content/docs/en/reference/image-service-reference.mdx +++ b/src/content/docs/en/reference/image-service-reference.mdx @@ -133,7 +133,7 @@ If you implement your own endpoint as an Astro endpoint, you can use `getConfigu import type { APIRoute } from "astro"; import { getConfiguredImageService, imageServiceConfig } from 'astro:assets'; -export const get: APIRoute = async ({ request }) => { +export const GET: APIRoute = async ({ request }) => { const imageService = await getConfiguredImageService(); const imageTransform = imageService.parseURL(new URL(request.url), imageServiceConfig); diff --git a/src/content/docs/en/tutorial/5-astro-api/4.mdx b/src/content/docs/en/tutorial/5-astro-api/4.mdx index b964d81fd4052..ffea42e081416 100644 --- a/src/content/docs/en/tutorial/5-astro-api/4.mdx +++ b/src/content/docs/en/tutorial/5-astro-api/4.mdx @@ -78,7 +78,7 @@ Individuals can subscribe to your feed in a feed reader, and receive a notificat import rss, { pagesGlobToRssItems } from '@astrojs/rss'; - export async function get() { + export async function GET() { return rss({ title: 'Astro Learner | Blog', description: 'My journey learning Astro', From 2f4983c36a592eb1cec6d2192cc5507190c4ba53 Mon Sep 17 00:00:00 2001 From: Elian Van Cutsem <hello@elian.codes> Date: Wed, 16 Aug 2023 14:43:07 +0200 Subject: [PATCH 10/58] chore: update DEL to DELETE --- src/content/docs/en/core-concepts/endpoints.mdx | 6 +----- src/content/docs/en/guides/backend/google-firebase.mdx | 2 +- src/content/docs/en/guides/upgrade-to/v3.mdx | 6 ------ 3 files changed, 2 insertions(+), 12 deletions(-) diff --git a/src/content/docs/en/core-concepts/endpoints.mdx b/src/content/docs/en/core-concepts/endpoints.mdx index f0894ef2677d6..f03e7cb7352cf 100644 --- a/src/content/docs/en/core-concepts/endpoints.mdx +++ b/src/content/docs/en/core-concepts/endpoints.mdx @@ -148,10 +148,6 @@ In addition to the `GET` function, you can export a function with the name of an You can also export an `ALL` function to match any method that doesn't have a corresponding exported function. If there is a request with no matching method, it will redirect to your site's [404 page](/en/core-concepts/astro-pages/#custom-404-error-page). -:::note -Since `delete` is a reserved word in JavaScript, export a `del` function to match the delete method. -::: - ```ts title="src/pages/methods.json.ts" export const GET: APIRoute = ({ params, request }) => { return { @@ -169,7 +165,7 @@ export const POST: APIRoute = ({ request }) => { } } -export const DEL: APIRoute = ({ request }) => { +export const DELETE: APIRoute = ({ request }) => { return { body: JSON.stringify({ message: "This was a DELETE!" diff --git a/src/content/docs/en/guides/backend/google-firebase.mdx b/src/content/docs/en/guides/backend/google-firebase.mdx index 0fbe235e267ac..5f18ea4bc89c7 100644 --- a/src/content/docs/en/guides/backend/google-firebase.mdx +++ b/src/content/docs/en/guides/backend/google-firebase.mdx @@ -660,7 +660,7 @@ export const POST: APIRoute = async ({ params, redirect, request }) => { return redirect("/dashboard"); }; -export const DEL: APIRoute = async ({ params, redirect }) => { +export const DELETE: APIRoute = async ({ params, redirect }) => { if (!params.id) { return new Response("Cannot find friend", { status: 404, diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index b212fe18f0721..515d89c1f9e17 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -208,12 +208,6 @@ Rename functions to uppercase equivalent: - `all` to `ALL` - `del` to `DELETE` -:::note[Confirm with Ema] -Does `del` also become `DEL` and / or `DELETE`? - -Sarah prefers showing `DEL` only (for consistency) -::: - ```ts title="endpoint.ts" del={1} ins={2} export function get() { export function GET() { From 09f569f31925f08d311354507814a9c31fdd51ec Mon Sep 17 00:00:00 2001 From: Elian Van Cutsem <hello@elian.codes> Date: Thu, 17 Aug 2023 06:49:56 +0200 Subject: [PATCH 11/58] chore: remove `<Markdown />` component --- src/content/docs/en/reference/api-reference.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index 2f57df4ceb56f..5c82a9238c198 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -1046,10 +1046,6 @@ export default function () { Astro includes several built-in components for you to use in your projects. All built-in components are available in `.astro` files via `import {} from 'astro/components';`. -### `<Markdown />` - -The Markdown component is no longer built into Astro. See how to [import Markdown into your Astro files](/en/guides/markdown-content/#importing-markdown) on our Markdown page. - ### `<Code />` ```astro 'theme="dark-plus"' /wrap\b/ /(inline) \/>/ From 6b0b53df00b3bc6e3cf7d446987fb6890bc50d5c Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Fri, 18 Aug 2023 21:16:54 +0000 Subject: [PATCH 12/58] all beta 0 and 1 placeholders entered --- src/content/docs/en/guides/upgrade-to/v3.mdx | 90 ++++++++++++++++++++ 1 file changed, 90 insertions(+) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 515d89c1f9e17..9c96267062d4d 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -362,6 +362,96 @@ const myValue = "red" </style> ``` +### Changed: default `scopedStyleStrategy` + +In Astro v2.x, the default value of `scopedStyleStrategy` was `"where"`. + +Astro v3.0, the default value is `"attribute"`. By default, styles are now applied using data-* attributes. + +#### What should I do? + +To retain your project's current style scoping, update the configuration file to the previous default value: + +```diff +export default defineConfig({ ++ scopedStyleStrategy: "where" +}) +``` + +### Changed: import.meta.env.BASE_URL default `trailingSlash` behaviour + +In Astro v2.x, `import.meta.env.BASE_URL`, which derives from `base` config, is always appended a trailingSlash by default or when `trailingSlash: "ignore"` is set. + +Astro v3.0 `import.meta.env.BASE_URL` is not appended with a trailingSlash by default or when `trailingSlash: "ignore"` is set. The existing behavior of `base` in combination with `trailingSlash: "always"` or `trailingSlash: "never"` is unchanged. + +#### What should I do? + +If your `base` already has a trailing slash, no change is needed. + + If your `base` does not have a trailing slash, add one to preserve the previous behaviour: + + ```diff + // astro.config.mjs + - base: 'my-base', + + base: 'my-base/', +``` + +### Changed: Multiple JSX framework configuration + +In Astro v2.x, you could use multiple JSX framework integrations (React, Solid, Preact) in the same project and Astro without having to identify which files belonged to which framework. + +Astro v3.0, in order to better support single-framework usage, now requires that you specify which files are included in each integrations config. This change is only needed if using more than one of these frameworks; otherwise no configuration is needed. + +#### What should I do? + +When using multiple JSX frameworks in the same project, use the `include` and/or `exclude` configuration options to specify which files belong to which framework. We recommend having common framework components in the same folder; for ex. `components/react/` and `components/solid/`. This is not required but makes configuration easier: + +```js +import { defineConfig } from 'astro/config'; +import preact from '@astrojs/preact'; +import react from '@astrojs/react'; +import svelte from '@astrojs/svelte'; +import vue from '@astrojs/vue'; +import solid from '@astrojs/solid-js'; + +export default defineConfig({ + // Enable many frameworks to support all different kinds of components. + integrations: [ + preact({ include: ['**/preact/*'] }), + solid({ include: ['**/solid/*'] }), + react({ include: ['**/react/*'] }), + ], +}); +``` + +DUPLICATE FOR COMBINING + +Astro's JSX handling has been refactored with better support for each framework. + +Previously, Astro automatically scanned your components to determine which framework-specific transformations should be used. In practice, supporting advanced features like Fast Refresh with this approach proved difficult. + +Now, Astro determines which framework to use with `include` and `exclude` config options where you can specify files and folders on a per-framework basis. When using multiple JSX frameworks in the same project, users should manually control which files belong to each framework using the `include` and `exclude` options. + +```js +export default defineConfig({ + // The `include` config is only needed in projects that use multiple JSX frameworks; + // if only using one no extra config is needed. + integrations: [ + preact({ + include: ['**/preact/*'] + }), + react({ + include: ['**/react/*'] + }), + solid({ + include: ['**/solid/*'], + }), + ] +}); +``` + + + ## Known Issues There are currently no known issues. From 5c87a8e1a6138aae6905443ab1234492f8ae990c Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Fri, 18 Aug 2023 21:41:54 +0000 Subject: [PATCH 13/58] edit JSX entry --- src/content/docs/en/guides/upgrade-to/v3.mdx | 31 ++++---------------- 1 file changed, 6 insertions(+), 25 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 9c96267062d4d..a2fd539f8181d 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -398,13 +398,15 @@ If your `base` already has a trailing slash, no change is needed. ### Changed: Multiple JSX framework configuration -In Astro v2.x, you could use multiple JSX framework integrations (React, Solid, Preact) in the same project and Astro without having to identify which files belonged to which framework. +In Astro v2.x, you could use multiple JSX framework integrations (React, Solid, Preact) in the same project and Astro without having to identify which files belonged to which framework. Astro automatically scanned your components to determine which framework-specific transformations should be used, but at a performance cost. -Astro v3.0, in order to better support single-framework usage, now requires that you specify which files are included in each integrations config. This change is only needed if using more than one of these frameworks; otherwise no configuration is needed. +Astro v3.0 determines which framework to use with `include` and `exclude` integration config options where you can specify files and folders on a per-framework basis. This allows Astro to better support single-framework usage, as well as advanced features like Fast Refresh. #### What should I do? -When using multiple JSX frameworks in the same project, use the `include` and/or `exclude` configuration options to specify which files belong to which framework. We recommend having common framework components in the same folder; for ex. `components/react/` and `components/solid/`. This is not required but makes configuration easier: +If you are using multiple JSX frameworks in the same project, use the `include` and/or `exclude` configuration options to specify which files belong to which framework. Provide an array of files and/or folders. Wildcards may be used to include multiple file paths. + +We recommend placing common framework components in the same folder (e.g. `/components/react/` and `/components/solid/`) to make specifying your includes easier, but this is not required: ```js import { defineConfig } from 'astro/config'; @@ -416,26 +418,7 @@ import solid from '@astrojs/solid-js'; export default defineConfig({ // Enable many frameworks to support all different kinds of components. - integrations: [ - preact({ include: ['**/preact/*'] }), - solid({ include: ['**/solid/*'] }), - react({ include: ['**/react/*'] }), - ], -}); -``` - -DUPLICATE FOR COMBINING - -Astro's JSX handling has been refactored with better support for each framework. - -Previously, Astro automatically scanned your components to determine which framework-specific transformations should be used. In practice, supporting advanced features like Fast Refresh with this approach proved difficult. - -Now, Astro determines which framework to use with `include` and `exclude` config options where you can specify files and folders on a per-framework basis. When using multiple JSX frameworks in the same project, users should manually control which files belong to each framework using the `include` and `exclude` options. - -```js -export default defineConfig({ - // The `include` config is only needed in projects that use multiple JSX frameworks; - // if only using one no extra config is needed. + // No `include` is needed if you are only using a single framework! integrations: [ preact({ include: ['**/preact/*'] @@ -450,8 +433,6 @@ export default defineConfig({ }); ``` - - ## Known Issues There are currently no known issues. From 060607b6916c73b652c0d55d0102753e7d3997ea Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Fri, 18 Aug 2023 23:19:19 +0000 Subject: [PATCH 14/58] all placeholder entries in up to date! --- src/content/docs/en/guides/upgrade-to/v3.mdx | 142 ++++++++++++++++++- 1 file changed, 141 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index a2fd539f8181d..24f320e2bcce6 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -366,7 +366,7 @@ const myValue = "red" In Astro v2.x, the default value of `scopedStyleStrategy` was `"where"`. -Astro v3.0, the default value is `"attribute"`. By default, styles are now applied using data-* attributes. +Astro v3.0, the default value is `"attribute"`. By default, styles are now applied using `data-*` attributes. #### What should I do? @@ -433,6 +433,146 @@ export default defineConfig({ }); ``` +### Removed: `@astrojs/image` +In Astro v2.x, this package existed + +Astro v3.0, it does not anymore, replaced by `astro:assets` + +#### What should I do? + +Migrate to `astro:assets`. In `.astro` files this is really just a replace `@astrojs/image` by `astro:assets` in most cases, however if you used the Picture component, you'll need at this time to recreate it using the `getImage` APIs. + +### Removed: kebab-case transform for camelCase CSS variables + +In Astro v2.x, camelCase CSS variables passed to the `style` attribute were rendered as camelCase (original) and kebab-case (incorrect by kept for backwards compatibility). + +Astro v3.0 removes the kebab-case transform, and only the original camelCase CSS variable is rendered. + + ```astro + --- + const myValue = "red" + --- + <!-- input --> + <div style={{ "--myValue": myValue }}></div> + <!-- output (before) --> + <div style="--my-value:var(--myValue);--myValue:red"></div> + <!-- output (after) --> + <div style="--myValue:red"></div> + ``` + +#### What should I do? + +If you were relying on the kebab-case transform in your styles, make sure to use the camelCase version to prevent missing styles. For example: + + ```diff + <style> + div { + - color: var(--my-value); + + color: var(--myValue); + } + </style> + ``` +DUPE TO BE COMBINED + + Remove backwards-compatible kebab-case transform for camelCase CSS variable names passed to the `style` attribute. If you were relying on the kebab-case transform in your styles, make sure to use the camelCase version to prevent missing styles. For example: + +```astro +--- +const myValue = "red" +--- +<!-- input --> +<div style={{ "--myValue": myValue }}></div> +<!-- output (before) --> +<div style="--my-value:var(--myValue);--myValue:red"></div> +<!-- output (after) --> +<div style="--myValue:red"></div> +``` + +```diff +<style> + div { +- color: var(--my-value); ++ color: var(--myValue); + } +</style> +``` + +### Changed entrypoint export paths + +In Astro v2.x, you can import internal Astro APIs from `astro/internal/star` and `astro/runtime/server/star`. + +Astro v3.0 removes the two entrypoints in favour of the existing `astro/runtime/star` entrypoint. + +#### What should I do? + +These are entrypoints for Astro's internal API and should not affect your project, but if you do use these entrypoints, you can migrate like below: + + ```diff + - import 'astro/internal/index.js'; + + import 'astro/runtime/server/index.js'; + + - import 'astro/server/index.js'; + + import 'astro/runtime/server/index.js'; + ``` + +### Small stylesheets now get inlined by default +In Astro v2.x, all project stylesheets were sent lnd u could opt-in to inlining them by using the `build.inlineStylesheets` configuration. + +were sent as link tags by default and you could opt in to inlining them + +Astro v3.0 defaults `inlineStylesheets` to "auto", which means stylesheets smaller than 4kB get included in the initial response. + +#### What should I do? +Nothing, this change does not require any migration. To go back to the old behavior, configure `inlineStylesheets` to "never" + +```diff +export default defineConfig({ + build: { ++ inlineStylesheets: "never" + } +}) +``` + +### Changed implementation of `class:list` directive +In Astro v2.x, `class:list` used a custom implementation inspired by [`clsx`](https://github.com/lukeed/clsx) with a few extra features like deduplication and `Set` support. + +In Astro v3.0, `class:list` uses [`clsx`](https://github.com/lukeed/clsx) directly, which does not support deduplication or `Set` values. + +#### What should I do? + +Replace any `Set` elements passed to the `class:list` directive with a plain `Array`. + +```diff + <Component class:list={[ + 'a', + 'b', +- new Set(['c', 'd']) ++ ['c', 'd'] + ]} /> +``` + +### Changed behavior of `class:list` directive for components + +In Astro v2.x, `class:list` values were sent to components via `Astro.props['class:list']`. + +In Astro v3.0, `class:list` values are normalized into a string before being sent to components via `Astro.props['class']` + +#### What should I do? + +Remove any code that expects to receive the `class:list` prop. + +```diff +--- +- import { clsx } from 'clsx'; +- const { class: className, 'class:list': classList } = Astro.props; ++ const { class: className } = Astro.props; +--- +<div +- class:list={[className, classList]} ++ class={className} +/> +``` + ## Known Issues There are currently no known issues. From 33252d21a6e2ad8dd373d15764120e75bd5d81c6 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 00:10:35 +0000 Subject: [PATCH 15/58] added experimental flags to remove --- src/content/docs/en/guides/upgrade-to/v3.mdx | 63 +++++++++++++------- 1 file changed, 42 insertions(+), 21 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 24f320e2bcce6..f5f625760baa7 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -45,6 +45,31 @@ Update your project's version of Astro to the latest version using your package </Fragment> </PackageManagerTabs> +## Astro v3.0 Experimental Flags Removed + +Remove the following experimental flags from `astro.config.mjs`: + +```js del={5-8} +// astro.config.mjs +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + experimental: { + assets: true, + viewTransitions: true, + }, +}) +``` + +These features are now available by default: + +- [View Transitions](/en/guides/view-transitions/) for animated page transitions and persistent islands. +- [A new image services API `astro:assets`](/en/guides/images/) for optimizing and transforming images through the new `<Image />` component and `getImage()` function. Also unlocks [relative images in Markdown, MDX and Markdoc](/en/guides/images/#update-your-markdown-mdx-and-markdoc-files) using standard `![]()` syntax. + +Read more about these two exciting features and more in the 3.0 Blog post! + + + ## Astro v3.0 Breaking Changes Astro v3.0 includes some breaking changes, as well as the removal of some previously deprecated features. If your project doesn't work as expected after upgrading to v3.0, check this guide for an overview of all breaking changes and instructions on how to update your codebase. @@ -74,13 +99,27 @@ Astro v3.0 drops Node 16 support entirely, so that all Astro users can take adva You can specify Node `18.14.1` for your Astro project either in a dashboard configuration setting, or a `.nvmrc` file. -### Reserved: `src/assets/` +### Removed: `@astrojs/image` +In Astro v2.x, this package existed -Astro v3.0 now includes the new image services API for optimizing your image assets. This API reserves `src/assets/` as a special folder, with a built-in import alias: `~/assets` for referencing assets located here. +Astro v3.0, it does not anymore, replaced by `astro:assets` #### What should I do? -No change is required, and there will be no conflicts with an existing `src/assets/` folder. However, you will now have access to the built-in import alias and can choose to rename your asset imports within your files. This folder is not required, and your assets may continued to be located anywhere. +Migrate to `astro:assets`. In `.astro` files this is really just a replace `@astrojs/image` by `astro:assets` in most cases, however if you used the Picture component, you'll need at this time to recreate it using the `getImage` APIs. + +Please see the full [v3 Image Upgrade Guide](/en/guides/images/#upgrade-to-v30-from-v2x) for details! + + +### Removed: `<Markdown />` component + +In Astro v2.x, Astro deprecated the `<Markdown />` component and moved it to an external package. + +Astro v3.0 comletely removes the package `@astrojs/markdown-component`, so Astro's `<Markdown />` component will no longer work in your project. + +#### What should I do? + +Uninstall the `@astrojs/markdown-component` package. To continue using a similar `<Markdown />` component in your code, consider using [community integrations](https://astro.build/integrations/) that provide a similar component like https://github.com/natemoo-re/astro-remote, and be sure to update your component imports and attributes as necessary according to the integration's own documentation. Otherwise, delete all references to importing Astro's `<Markdown />` component and the component itself in your `.astro` files. You will need to rewrite your content as HTML directly or [import Markdown](/en/guides/markdown-content/#importing-markdown) from an `.md` file. ### Changed: automatic flattening of `getStaticPaths()`'s return value @@ -321,16 +360,6 @@ Astro V3 still displays the error log, but now you can build the project. When using an adapter that supports neither Squoosh or Sharp, Astro will now automatically use an image service that does not support processing, but still provides the other benefits of `astro:assets` such as enforcing `alt`, no CLS etc to users. Should be noted that it does no transformations or processing, but you still get all the other benefits (no CLS, alt enforced, etc). All of those benefits are part of the image service, if you make your own, you lose those benefits unless you make it yourself -### Removed: `<Markdown />` component - -In Astro v2.x, Astro deprecated the `<Markdown />` component and moved it to an external package. - -Astro v3.0 comletely removes the package `@astrojs/markdown-component`, so Astro's `<Markdown />` component will no longer work in your project. - -#### What should I do? - -Uninstall the `@astrojs/markdown-component` package. To continue using a similar `<Markdown />` component in your code, consider using [community integrations](https://astro.build/integrations/) that provide a similar component like https://github.com/natemoo-re/astro-remote, and be sure to update your component imports and attributes as necessary according to the integration's own documentation. Otherwise, delete all references to importing Astro's `<Markdown />` component and the component itself in your `.astro` files. You will need to rewrite your content as HTML directly or [import Markdown](/en/guides/markdown-content/#importing-markdown) from an `.md` file. - ### Removed: camelCase transformations In Astro 2.x, Astro automatically transformed camelCase CSS variable names passed to the `style` attribute of an HTML element. @@ -433,14 +462,6 @@ export default defineConfig({ }); ``` -### Removed: `@astrojs/image` -In Astro v2.x, this package existed - -Astro v3.0, it does not anymore, replaced by `astro:assets` - -#### What should I do? - -Migrate to `astro:assets`. In `.astro` files this is really just a replace `@astrojs/image` by `astro:assets` in most cases, however if you used the Picture component, you'll need at this time to recreate it using the `getImage` APIs. ### Removed: kebab-case transform for camelCase CSS variables From adc2cc43b57e0697d098f430133aff01c7dd12fc Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 12:33:16 +0000 Subject: [PATCH 16/58] deleted the assets page since it won't be in new docs --- src/content/docs/en/guides/assets.mdx | 404 -------------------------- 1 file changed, 404 deletions(-) delete mode 100644 src/content/docs/en/guides/assets.mdx diff --git a/src/content/docs/en/guides/assets.mdx b/src/content/docs/en/guides/assets.mdx deleted file mode 100644 index 96d05cfe90a43..0000000000000 --- a/src/content/docs/en/guides/assets.mdx +++ /dev/null @@ -1,404 +0,0 @@ ---- -title: Assets (Experimental) -description: Learn how to enable experimental asset support in Astro. -i18nReady: false ---- -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' - -**Built-in optimized asset support** is enabled in Astro behind an experimental flag. This built-in feature will eventually replace the optional `@astrojs/image` integration. - -The new assets experience currently features: - -- A new built-in `<Image />` component -- Relative images with automatic optimization in Markdown, [MDX](/en/guides/integrations-guide/mdx/), and [Markdoc](/en/guides/integrations-guide/markdoc/) -- Integration with content collections -- Improved error messages and types - -:::caution -Assets are an experimental Astro feature introduced in v2.1. This API is subject to change before it is marked as stable. -::: - -## Enabling Assets in your Project - -Enabling assets may cause some breaking changes in your project. It may also require some manual changes to take advantage of new features. - -Please check every section below to avoid errors and to get the most out of using the experimental assets option! - -### Update Config - -To enable built-in asset support, add the following lines to your `astro.config.mjs` configuration file: - -```js title="astro.config.mjs" ins={4-6} -import { defineConfig } from 'astro/config'; - -export default defineConfig({ - experimental: { - assets: true - } -}); -``` - -When you next run Astro, it will update your `src/env.d.ts` file to configure types for you. To do this manually, replace the `astro/client` reference with `astro/client-image`: - -```ts title="src/env.d.ts" del={1} ins={2} -/// <reference types="astro/client" /> -/// <reference types="astro/client-image" /> -``` - -### Move your images to `src/assets/` - -Create `src/assets/`, which Astro will recognize as your new assets folder. - -We recommend storing all images to be optimized in the `src/assets/` directory to make use of our official `~/assets` alias, although this location is optional. If you don't know where to put your images, or if you're building a product around Astro (e.g. a CMS), you can put your images there and we promise we won't break them! But, images can be stored anywhere, including alongside your content, if you prefer. - -Your images can be used by components (`.astro`, `.mdx`, and other UI frameworks) and in Markdown files. - -### Update existing `<img>` tags - -Previously, importing an image would return a simple `string` with the path of the image. With the new `image` features enabled, imported image assets now match the following signature: - -```ts -interface ImageMetadata { - src: string; - width: number; - height: number; - format: string; -} -``` - -You must update the `src` attribute of any existing `<img>` tags, and you may also update other attributes that are now available to you from the imported image. - -```astro title="src/components/MyComponent.astro" ".src" ".width" ".height" del={2,5} ins={3,6} ---- -import rocket from '../images/rocket.svg'; -import rocket from '../assets/images/rocket.svg' ---- -<img src={rocket} width="250" height="250" alt="A rocketship in space." /> -<img src={rocket.src} width={rocket.width} height={rocket.height} alt="A rocketship in space." /> -``` - -### Update your Markdown, MDX, and Markdoc files - -Relative images can now be referenced in Markdown, MDX, and Markdoc files. These will automatically be optimized and hashed by Astro's build process. - -This allows you to move your images from the `public/` directory to the new, reserved `src/assets/` directory or move them near your Markdown, MDX, or Markdoc files. (See the URL path of these built images in the example below.) - -Your existing images in `public/` are still valid but are not automatically optimized by Astro's build process. - -```md title="src/pages/posts/post-1.md" "/_astro" ".hash" "../../assets/" -# My Markdown Page - -<!-- Local image stored at src/assets/stars.png --> -![A starry night sky.](../../assets/stars.png) -<img src="/_astro/stars.hash.webp" alt="A starry night sky."> - -<!-- Remote image on another server --> -![Astro logo](https://docs.astro.build/assets/logomark-light.png) -<img src="/_astro/logomark-light.hash.webp" width="25" alt="Astro logo"> - -<!-- Image stored at public/images/stars.png, will not be processed --> -![A starry night sky.](/images/stars.png) -<img src="/images/stars.png" alt="A starry night sky."> -``` - -### Convert from `@astrojs/image` - -**Built-in asset support is incompatible with the `@astrojs/image` integration.** - -:::note[cropping images] -The Assets API does not support image cropping. The current behaviour is to resize images to fit. - -Use the `@astrojs/image` integration if you need support for cropping images. Alternatively, you can use the [`object-fit` CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) to achieve a similar result. -::: - -To avoid errors in your project, complete the following steps: - -1. Remove the `@astrojs/image` integration. - - You must [remove the integration](/en/guides/integrations-guide/#removing-an-integration) by uninstalling and then removing it from your `astro.config.mjs` file. - -2. Migrate any existing `<Image />` components. - - Change all `import` statements from `@astrojs/image/components` to `astro:assets` to use the new built-in `<Image />` component. - - Remove any component attributes that are not [currently supported image asset properties](#properties). - - For example `aspectRatio` is no longer supported, as it is now automatically inferred from the `width` and `height` attributes. - - ```astro title="src/components/MyComponent.astro" del= {2,11} ins={3} - --- - import { Image } from '@astrojs/image/components'; - import { Image } from 'astro:assets' - import localImage from "../assets/logo.png"; - const localAlt = "The Astro Logo"; - --- - - <Image - src={localImage} - width={300} - aspectRatio="16:9" - alt={localAlt} - /> - ``` - - -3. Remove any existing `<Picture />` components - - Currently, the built-in assets feature does not include a `<Picture />` component. - - Instead, you can use the HTML image attributes `srcset` and `sizes` or the `<picture>` tag [for art direction or to create responsive images](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images#art_direction). - - -### Update content collections schemas - -You can now declare images in your frontmatter as their paths relative to the current folder. - -```md title="src/content/blog/my-post.md" ---- -title: "My first blog post" -cover: "./firstpostcover.jpeg" # will resolve to "src/content/blog/firstblogcover.jpeg" -coverAlt: "A photograph of a sunset behind a mountain range" ---- - -This is a blog post -``` - -A new `image` helper for content collections lets you validate the image metadata using Zod. - -```ts title="src/content/config.ts" -import { defineCollection, z } from "astro:content"; - -const blogCollection = defineCollection({ - schema: ({ image }) => z.object({ - title: z.string(), - cover: image().refine((img) => img.width >= 1080, { - message: "Cover image must be at least 1080 pixels wide!", - }), - coverAlt: z.string(), - }), -}); - -export const collections = { - blog: blogCollection, -}; -``` - -The image will be imported and transformed into metadata that matches the signature of imported images, allowing you to pass it as a `src` to `<Image/>` or `getImage()`. A blog index page might render the cover photo and title of each blog post: - -```astro title="src/pages/blog.astro" {10} ---- -import { Image } from "astro:assets"; -import { getCollection } from "astro:content"; -const allBlogPosts = await getCollection("blog"); ---- - -{ - allBlogPosts.map((post) => ( - <div> - <Image src={post.data.cover} alt={post.data.coverAlt} /> - <h2> - <a href={"/blog/" + post.slug}>{post.data.title}</a> - </h2> - </div> - )) -} -``` - -### Allowed domains and remote patterns for remote images - -For security reasons, Astro will not process remote images from all domains by default. You can specify which domains to allow in your `astro.config.mjs` file. - -```js title="astro.config.mjs" -import { defineConfig } from 'astro/config'; - -export default defineConfig({ - image: { - domains: ["astro.build"], - } -}); -``` - -Alternatively, you can specify a pattern to match against the `src` attribute of remote images to allow. This can be useful if you want to allow images from a CDN that uses a wildcard subdomain. - -```js title="astro.config.mjs" -import { defineConfig } from 'astro/config'; - -export default defineConfig({ - image: { - remotePatterns: [{ hostname: "*.akamaihd.net" }], - } -}); -``` - -The protocol, hostname, pathname, and port of the image URL can be checked using this method. For instance, you could allow only images being served from HTTPs using `{ protocol: "https" }`. - -See [`image.domains`](/en/reference/configuration-reference/#imagedomains-experimental) and [`image.remotePatterns`](/en/reference/configuration-reference/#imageremotepatterns-experimental) for detailed configuration instructions. - -## `astro:assets` module - -Enabling asset support allows you to access the `astro:assets` module. This module exposes the following features: - -- `<Image />` (available in `.astro` and `.mdx` files) -- `getImage()` (available in `.astro`, `.mdx`, `.ts`, `.js` on the server) - -:::caution -`<Image />` is an Astro component and [can't be used in framework components](/en/core-concepts/framework-components/#can-i-use-astro-components-inside-my-framework-components). - -`getImage()` relies on server-only APIs and breaks the build when used on the client. -::: - -### `<Image />` (`astro:assets`) - -The `<Image />` component generates an `<img>` tag. - -This component can transform an image's dimensions, file type, and quality to produce an optimized image. The resulting `<img>` tag will include the correct `width` and `height` attributes to avoid Cumulative Layout Shift **(CLS)**. - -:::tip[What is Cumulative Layout Shift?] -CLS is a score that reflects how much content shifted on your page during loading. The ideal number for CLS is as close to zero as possible, which the `Image` component enforces by automatically selecting the correct `width` and `height` for local images. -::: - -Import images from a **relative file path** or [import alias](/en/guides/aliases/) in any component file and then use the import as the `<Image />` component's `src` attribute. - -```astro ---- -import { Image } from 'astro:assets'; -import myImage from "../assets/my_image.png"; // Image is 1600x900 ---- - -<!-- `alt` is mandatory on the Image component --> -<Image src={myImage} alt="A description of my image." /> -``` - -```astro -<!-- Output --> -<!-- Image is optimized, proper attributes are enforced --> -<img - src="/_astro/my_image.hash.webp" - width="1600" - height="900" - decoding="async" - loading="lazy" - alt="A description of my image." -/> -``` - -#### Properties - -##### width and height - -These properties define the dimensions to use for the image. - -When using local images in their original aspect ratio, the `width` and `height` can be automatically inferred from the source file and are optional. However, both of these properties are required for remote images. - -##### format - -You can optionally state the [image file type](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types#common_image_file_types) to be used. The default file format used is `webp`. - -##### quality - -`quality` is an optional property that can either be: -- a preset (`low`, `mid`, `high`, `max`) that is automatically normalized between formats. -- a number from `0` to `100` (interpreted differently between formats). - -##### alt (required) - -Use the `alt` attribute to provide [descriptive alt text](https://www.w3.org/WAI/tutorials/images/) for images. - -This attribute is required for the `<Image />` component. This component will throw an error if no alt text is provided. - -If the image is merely decorative (i.e. doesn't contribute to the understanding of the page), set `alt=""` so that screen readers know to ignore the image. - -##### Additional properties - -In addition to the properties above, the `<Image />` component accepts all properties accepted by the HTML `<img>` tag. - -For example, you can provide a `class` to the final `img` element. - -```astro ---- -import { Image } from 'astro:assets'; -import myImage from "../assets/my_image.png"; ---- - -<!-- `alt` is mandatory on the Image component --> -<Image src={myImage} alt="" class="my-class" /> -``` - -```astro -<!-- Output --> -<img - src="/_astro/my_image.hash.webp" - width="1600" - height="900" - decoding="async" - loading="lazy" - class="my-class" - alt="" -/> -``` - -### `getImage()` (`astro:assets`) - -This function is intended for generating images destined to be used somewhere else than directly in HTML, for example in an [API Route](/en/core-concepts/endpoints/#server-endpoints-api-routes). It also allows you to create your own custom `<Image />` component. - -`getImage()` takes an options object with the same properties as the Image component (except `alt`). - -```astro ---- -import { getImage } from "astro:assets"; -import myBackground from "../background.png" - -const optimizedBackground = await getImage({src: myBackground, format: 'avif'}) ---- - -<div style={`background-image: url(${optimizedBackground.src});`}></div> -``` - -It returns an object with the following properties: - -```js -{ - options: {...} // Original parameters passed, - src: "https//..." // Path to the generated image, - attributes: {...} // Additional HTML attributes needed to render the image (width, height, style, etc..) -} -``` - -## Using sharp - -By default, Astro uses [Squoosh](https://github.com/GoogleChromeLabs/squoosh) to transform your images. - -If you're building a static site or deploying an SSR site to a Node environment, we recommend using [sharp](https://github.com/lovell/sharp), which offers faster performance but requires Node. To use sharp, first install it: - -<PackageManagerTabs> - <Fragment slot="npm"> - ```shell - npm install sharp - ``` - </Fragment> - <Fragment slot="pnpm"> - ```shell - pnpm install sharp - ``` - </Fragment> - <Fragment slot="yarn"> - ```shell - yarn add sharp - ``` - </Fragment> -</PackageManagerTabs> - -Then, enable Astro's sharp image service in your config: - -```js title="astro.config.mjs" -import { defineConfig, sharpImageService } from "astro/config"; - -export default defineConfig({ - experimental: { - assets: true, - }, - image: { - service: sharpImageService(), - }, -}); -``` From 6a32051833327793c9ab43a00c1a8670371d47a0 Mon Sep 17 00:00:00 2001 From: Arsh <69170106+lilnasy@users.noreply.github.com> Date: Sat, 19 Aug 2023 18:20:19 +0530 Subject: [PATCH 17/58] Update CSS Bundle Control for 3.0 (#4253) Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca> --- src/content/docs/en/guides/styling.mdx | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/src/content/docs/en/guides/styling.mdx b/src/content/docs/en/guides/styling.mdx index 129240181a1e8..85f325dcb42d4 100644 --- a/src/content/docs/en/guides/styling.mdx +++ b/src/content/docs/en/guides/styling.mdx @@ -531,24 +531,36 @@ If you are using Tailwind, the [typography plugin](https://tailwindcss.com/docs/ ### Bundle control -When Astro builds your site for production deployment it combines your CSS into chunks. Each page on your site is its own chunk, and additionally, CSS that is shared between multiple pages is further split off into their own chunks for reuse. +When Astro builds your site for production deployment, it minifies and combines your CSS into chunks. Each page on your site gets its own chunk, and additionally, CSS that is shared between multiple pages is further split off into their own chunks for reuse. -In each of your HTML files there will be `<link rel="stylesheet">` tags added, one for each of the chunks that the pages needs. +However, when you have several pages sharing styles, some shared chunks can become really small. If all of them were sent separately, it would lead to many stylesheets requests and affect site performance. Therefore, by default Astro will link only those in your HTML above 4kB in size as `<link rel="stylesheet">` tags, while inlining smaller ones into `<style type="text/css">`. This approach provides a balance between the number of additional requests and the volume of CSS that can be cached between pages. -Sites with a large number of pages and many different shared styles can lead to many stylesheet requests and affect site performance. You can configure the `inlineStylesheets` option to reduce the number of these requests by putting (minimized) stylesheets into a `<style>` tag rather than request them externally. +You can configure the size at which stylesheets will be linked externally (in bytes) using the `assetsInlineLimit` vite build option. Note that this option affects script and image inlining as well. + +```js +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + vite: { + build: { + assetsInlineLimit: 1024, + } + }; +}); +``` + +If you would rather all project styles remain external, you can configure the `inlineStylesheets` build option. ```js import { defineConfig } from 'astro/config'; export default defineConfig({ build: { - inlineStylesheets: 'auto' + inlineStylesheets: 'never' } }); ``` -The `'auto'` option will inline only the stylesheets that are below the `vite.build.assetsInlineLimit` threshold, reducing the number of requests for smaller sheets. Larger stylesheets, such as global ones used by all pages, will still be fetched externally and cached. This option provides a balance between the number of stylesheets loaded and the styles that can be cached between pages. - You can also set this option to `'always'` which will inline all stylesheets. ## Advanced From 0f62bd24ea77f6a6ecfe323c16129fa5d7c6add2 Mon Sep 17 00:00:00 2001 From: Matthew Phillips <matthew@skypack.dev> Date: Sat, 19 Aug 2023 08:51:24 -0400 Subject: [PATCH 18/58] Use astro: namespace modules (#4239) --- src/content/docs/en/guides/middleware.mdx | 6 +++--- src/content/docs/en/guides/troubleshooting.mdx | 4 ++-- src/content/docs/en/reference/api-reference.mdx | 6 +++--- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/content/docs/en/guides/middleware.mdx b/src/content/docs/en/guides/middleware.mdx index d7a6688a4c8b0..4657879ff0a8d 100644 --- a/src/content/docs/en/guides/middleware.mdx +++ b/src/content/docs/en/guides/middleware.mdx @@ -45,7 +45,7 @@ You can import and use the utility function `defineMiddleware()` to take advanta ```ts // src/middleware.ts -import { defineMiddleware } from "astro/middleware"; +import { defineMiddleware } from "astro:middleware"; // `context` and `next` are automatically typed export const onRequest = defineMiddleware((context, next) => { @@ -137,7 +137,7 @@ export const onRequest = async (context, next) => { Multiple middlewares can be joined in a specified order using [`sequence()`](#sequence): ```js title="src/middleware.js" -import { sequence } from "astro/middleware"; +import { sequence } from "astro:middleware"; async function validation(_, next) { console.log("validation request"); @@ -218,4 +218,4 @@ This function can be used by integrations/adapters to programmatically execute t ### `trySerializeLocals` -A low-level API that takes in any value and tries to return a serialized version (a string) of it. If the value cannot be serialized, the function will throw a runtime error. \ No newline at end of file +A low-level API that takes in any value and tries to return a serialized version (a string) of it. If the value cannot be serialized, the function will throw a runtime error. diff --git a/src/content/docs/en/guides/troubleshooting.mdx b/src/content/docs/en/guides/troubleshooting.mdx index 1d80ed7c8edb6..8d51a7beec1f9 100644 --- a/src/content/docs/en/guides/troubleshooting.mdx +++ b/src/content/docs/en/guides/troubleshooting.mdx @@ -198,7 +198,7 @@ To help you debug your Astro components, Astro provides a built-in [`<Debug />`] ```astro {2,7} --- -import { Debug } from 'astro/components'; +import { Debug } from 'astro:components'; const sum = (a, b) => a + b; --- @@ -210,7 +210,7 @@ The Debug component supports a variety of syntax options for even more flexible ```astro {2,7-9} --- -import { Debug } from 'astro/components'; +import { Debug } from 'astro:components'; const sum = (a, b) => a + b; const answer = sum(2, 4); --- diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index 5c82a9238c198..715858b0f2fe2 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -1044,13 +1044,13 @@ export default function () { ## Built-in Components -Astro includes several built-in components for you to use in your projects. All built-in components are available in `.astro` files via `import {} from 'astro/components';`. +Astro includes several built-in components for you to use in your projects. All built-in components are available in `.astro` files via `import {} from 'astro:components';`. ### `<Code />` ```astro 'theme="dark-plus"' /wrap\b/ /(inline) \/>/ --- -import { Code } from 'astro/components'; +import { Code } from 'astro:components'; --- <!-- Syntax highlight some JavaScript code. --> <Code code={`const foo = 'bar';`} lang="js" /> @@ -1112,7 +1112,7 @@ See the [list of languages supported by Prism](https://prismjs.com/#supported-la ```astro --- -import { Debug } from 'astro/components'; +import { Debug } from 'astro:components'; const serverObject = { a: 0, b: "string", From 58e22a8d4f2eadb118aa08853cbb0c17f7b8fef5 Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa <my.burning@gmail.com> Date: Sat, 19 Aug 2023 14:04:23 +0100 Subject: [PATCH 19/58] feat: document astro features (#3924) Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca> --- .../docs/en/reference/adapter-reference.mdx | 92 ++++++++++++++++++- 1 file changed, 91 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index f7ed4c3cdfc17..54974665714f2 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -2,6 +2,8 @@ title: Astro Adapter API i18nReady: true --- +import Since from '~/components/Since.astro'; + Astro is designed to make it easy to deploy to any cloud provider for SSR (server-side rendering). This ability is provided by __adapters__, which are [integrations](/en/reference/integrations-reference/). See the [SSR guide](/en/guides/server-side-rendering/#adding-an-adapter) to learn how to use an existing adapter. @@ -26,7 +28,10 @@ export default function createIntegration() { 'astro:config:done': ({ setAdapter }) => { setAdapter({ name: '@matthewp/my-adapter', - serverEntrypoint: '@matthewp/my-adapter/server.js' + serverEntrypoint: '@matthewp/my-adapter/server.js', + supportedAstroFeatures: { + staticOutput: 'stable' + } }); }, }, @@ -41,6 +46,40 @@ interface AstroAdapter { name: string; serverEntrypoint?: string; exports?: string[]; + supportedAstroFeatures: AstroFeatureMap; +} + +export type SupportsKind = 'unsupported' | 'stable' | 'experimental' | 'deprecated'; + +export type AstroFeatureMap = { + /** + * The adapter is able to serve static pages + */ + staticOutput?: SupportsKind; + /** + * The adapter is able to serve pages that are static or rendered via server + */ + hybridOutput?: SupportsKind; + /** + * The adapter is able to serve SSR pages + */ + serverOutput?: SupportsKind; + /** + * The adapter can emit static assets + */ + assets?: AstroAssetsFeature; +}; + +export interface AstroAssetsFeature { + supportKind?: SupportsKind; + /** + * Whether or not this adapter deploys files in an environment that is compatible with the library `sharp` + */ + isSharpCompatible?: boolean; + /** + * Whether or not this adapter deploys files in an environment that is compatible with the library `squoosh` + */ + isSquooshCompatible?: boolean; } ``` @@ -49,6 +88,7 @@ The properties are: * __name__: A unique name for your adapter, used for logging. * __serverEntrypoint__: The entrypoint for server-side rendering. * __exports__: An array of named exports when used in conjunction with `createExports` (explained below). +* __supportedAstroFeatures__: A map of Astro built-in features. This allows Astro to determine which features an adapter is unable or unwilling to support so appropriate error messages can be provided. ### Server Entrypoint @@ -188,3 +228,53 @@ You can usually call `app.render(request)` without using `.match` because Astro ``` Once you [publish your adapter to npm](https://docs.npmjs.com/cli/v8/commands/npm-publish), running `astro add example` will install your package with any peer dependencies specified in your `package.json`. We will also instruct users to update their project config manually. + + +## Astro features + +<Since v="3.0.0" /> + +Astro features are a way for an adapter to tell Astro whether they are able to support a feature, and also the adapter's level of support. + +When using these properties, Astro will: +- run specific validation; +- emit contextual to the logs; + +These operations are run based on the features supported or not supported, their level of support, and the configuration that the user uses. + +The following configuration tells Astro that this adapter has experimental support for assets, but the adapter is not compatible with the built-in services Sharp and Squoosh: + +```js title="my-adapter.mjs" ins={9-15} +export default function createIntegration() { + return { + name: '@matthewp/my-adapter', + hooks: { + 'astro:config:done': ({ setAdapter }) => { + setAdapter({ + name: '@matthewp/my-adapter', + serverEntrypoint: '@matthewp/my-adapter/server.js', + supportedAstroFeatures: { + assets: { + supportKind: "experimental", + isSharpCompatible: false, + isSquooshCompatible: false + } + } + }); + }, + }, + }; +} +``` + +Astro will log a **warning** to the terminal: + +``` +[@matthewp/my-adapter] The feature is experimental and subject to issues or changes. +``` + +and an error if the service used for assets is not compatible with the adapter: + +``` +[@matthewp/my-adapter] The currently selected adapter `@matthewp/my-adapter` is not compatible with the service "Sharp". Your project will NOT be able to build. +``` From 50a5f9efee534f0ab310aea8f40c4b0599f5a2a6 Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa <my.burning@gmail.com> Date: Sat, 19 Aug 2023 14:18:37 +0100 Subject: [PATCH 20/58] feat: document logger for Astro integrations (#3817) Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca> Co-authored-by: Reuben Tier <64310361+TheOtterlord@users.noreply.github.com> Co-authored-by: Chris Swithinbank <swithinbank@gmail.com> --- .../en/reference/integrations-reference.mdx | 86 +++++++++++++++++-- 1 file changed, 78 insertions(+), 8 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index c1106a7eca069..42cc5d7a98d69 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -32,20 +32,26 @@ interface AstroIntegration { addClientDirective: (directive: ClientDirectiveConfig) => void; injectScript: (stage: InjectedScriptStage, content: string) => void; injectRoute: ({ pattern: string, entryPoint: string }) => void; + logger: AstroIntegrationLogger; }) => void; - 'astro:config:done'?: (options: { config: AstroConfig }) => void | Promise<void>; - 'astro:server:setup'?: (options: { server: vite.ViteDevServer }) => void | Promise<void>; - 'astro:server:start'?: (options: { address: AddressInfo }) => void | Promise<void>; - 'astro:server:done'?: () => void | Promise<void>; - 'astro:build:start'?: () => void | Promise<void>; + 'astro:config:done'?: (options: { config: AstroConfig; logger: AstroIntegrationLogger; }) => void | Promise<void>; + 'astro:server:setup'?: (options: { server: vite.ViteDevServer; logger: AstroIntegrationLogger; }) => void | Promise<void>; + 'astro:server:start'?: (options: { address: AddressInfo; logger: AstroIntegrationLogger; }) => void | Promise<void>; + 'astro:server:done'?: (options: { logger: AstroIntegrationLogger; }) => void | Promise<void>; + 'astro:build:start'?: (options: { logger: AstroIntegrationLogger; }) => void | Promise<void>; 'astro:build:setup'?: (options: { vite: ViteConfigWithSSR; pages: Map<string, PageBuildData>; target: 'client' | 'server'; + logger: AstroIntegrationLogger; }) => void | Promise<void>; - 'astro:build:generated'?: (options: { dir: URL }) => void | Promise<void>; - 'astro:build:ssr'?: (options: { manifest: SerializedSSRManifestm, entryPoints: Map<RouteData, URL> }) => void | Promise<void>; - 'astro:build:done'?: (options: { dir: URL; routes: RouteData[] }) => void | Promise<void>; + 'astro:build:generated'?: (options: { dir: URL; logger: AstroIntegrationLogger; }) => void | Promise<void>; + 'astro:build:ssr'?: (options: { + manifest: SerializedSSRManifestm; + entryPoints: Map<RouteData, URL>; + logger: AstroIntegrationLogger; + }) => void | Promise<void>; + 'astro:build:done'?: (options: { dir: URL; routes: RouteData[]; logger: AstroIntegrationLogger; }) => void | Promise<void>; }; } ``` @@ -71,6 +77,7 @@ interface AstroIntegration { addWatchFile: (path: URL | string) => void; injectScript: (stage: InjectedScriptStage, content: string) => void; injectRoute: ({ pattern: string, entryPoint: string }) => void; + logger: AstroIntegrationLogger; }) => void; ``` @@ -527,6 +534,69 @@ export default defineConfig({ This assumes your integration definition is 1) a `default` export and 2) a function. Ensure this is true before adding the `astro-integration` keyword! ::: +## `AstroIntegrationLogger` + +An instance of the Astro logger, useful to write logs. This logger uses the same [log level](/en/reference/cli-reference/#--verbose) +configured via CLI. + +**Methods available** to write to terminal: +- `logger.info("Messsage")`; +- `logger.warn("Messsage")`; +- `logger.error("Messsage")`; +- `logger.debug("Messsage")`; + +All the messages are prepended with a label that has the same value of the integration. + +```ts title="integration.ts" {8} +import type { AstroIntegration } from "astro"; +export function formatIntegration(): AstroIntegration { + return { + name: "astro-format", + hooks: { + "astro:build:done": (options, { logger }) => { + // do something + logger.info("Integration ready."); + } + } + } +} +``` + +The example above will log a message that includes the provided `info` message: + +```shell +[astro-format] Integration ready. +``` + +To log some messages with a different label, use the `.fork` method to specify an alternative to the default `name`: + +```ts title="integration.ts" ".fork" +import type { AstroIntegration } from "astro"; +export function formatIntegration(): AstroIntegration { + return { + name: "astro-format", + hooks: { + "astro:config:done": ({ logger }) => { + // do something + logger.info("Integration ready."); + }, + "astro:build:done": ({ logger }) => { + const buildLogger = logger.fork("astro-format/build"); + // do something + buildLogger.info("Build finished.") + } + } + } +} +``` + +The example above will produce logs with `[astro-format]` by default, and `[astro-format/build]` when specified: + +```shell +[astro-format] Integration ready. +[astro-format/build] Build finished. +``` + ## Integration Ordering All integrations are run in the order that they are configured. For instance, for the array `[react(), svelte()]` in a user's `astro.config.*`, `react` will run before `svelte`. From e76b7e66b0d4f4efea04bb54185c19eafc707625 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 14:08:11 +0000 Subject: [PATCH 21/58] removed Assets from sidebar since file was deleted --- src/i18n/en/nav.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts index 15ab74e540e29..242a27f371ea4 100644 --- a/src/i18n/en/nav.ts +++ b/src/i18n/en/nav.ts @@ -70,7 +70,6 @@ export default [ key: 'guides/client-side-scripts', }, { text: 'CSS & Styling', slug: 'guides/styling', key: 'guides/styling' }, - { text: 'Assets (Experimental)', slug: 'guides/assets', key: 'guides/assets' }, { text: 'Images', slug: 'guides/images', key: 'guides/images' }, { text: 'Fonts', slug: 'guides/fonts', key: 'guides/fonts' }, { text: 'Imports', slug: 'guides/imports', key: 'guides/imports' }, From 3210dcce116c3519446a29619887c2cf51ec10c0 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 14:35:52 +0000 Subject: [PATCH 22/58] updated image links to point to page we want them to visit --- src/content/docs/en/guides/upgrade-to/v3.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index f5f625760baa7..adff407958dfe 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -64,7 +64,7 @@ export default defineConfig({ These features are now available by default: - [View Transitions](/en/guides/view-transitions/) for animated page transitions and persistent islands. -- [A new image services API `astro:assets`](/en/guides/images/) for optimizing and transforming images through the new `<Image />` component and `getImage()` function. Also unlocks [relative images in Markdown, MDX and Markdoc](/en/guides/images/#update-your-markdown-mdx-and-markdoc-files) using standard `![]()` syntax. +- A new image services API `astro:assets` for [using images in Astro](/en/guides/images/), including a new `<Image />` component and `getImage()` function. Read more about these two exciting features and more in the 3.0 Blog post! From fb9044b77050319aa64c90f6a7bc7a3a5cac91ad Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 14:55:56 +0000 Subject: [PATCH 23/58] edited removed astro image integration --- src/content/docs/en/guides/upgrade-to/v3.mdx | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index adff407958dfe..ae9139a53bf43 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -100,15 +100,18 @@ Astro v3.0 drops Node 16 support entirely, so that all Astro users can take adva You can specify Node `18.14.1` for your Astro project either in a dashboard configuration setting, or a `.nvmrc` file. ### Removed: `@astrojs/image` -In Astro v2.x, this package existed -Astro v3.0, it does not anymore, replaced by `astro:assets` +In Astro v2.x, Astro offered an official image integration that included Astro `<Image />` and `<Picture />` components. + +Astro v3.0 removes this integration from the codebase entirely. Astro's new solution for images is a built-in image services API: `astro:assets`. #### What should I do? -Migrate to `astro:assets`. In `.astro` files this is really just a replace `@astrojs/image` by `astro:assets` in most cases, however if you used the Picture component, you'll need at this time to recreate it using the `getImage` APIs. +Remove the `@astrojs/image` integration from your project. You will need to not only uninstall the integration, but also update or remove any import statements and existing `<Image />` and `<Picture />` components. You might also need to configure a preferred default image processing service. + +You will find [complete, step-by-step instructions for removing the old image integration](/en/guides/images/#remove-astrojsimage) in our Images guide. -Please see the full [v3 Image Upgrade Guide](/en/guides/images/#upgrade-to-v30-from-v2x) for details! +Migrating to `astro:assets` will also bring some new image options and features that you may now wish to use. Please see the full [v3.0 Image Upgrade Advice](/en/guides/images/#upgrade-to-v30-from-v2x) for full details! ### Removed: `<Markdown />` component From d53181cd7b667da3f7a96d2f1c5f8660cd0cf640 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 15:10:00 +0000 Subject: [PATCH 24/58] edited removed markdown component --- src/content/docs/en/guides/upgrade-to/v3.mdx | 27 ++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index ae9139a53bf43..56b38455ba7c7 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -113,16 +113,39 @@ You will find [complete, step-by-step instructions for removing the old image in Migrating to `astro:assets` will also bring some new image options and features that you may now wish to use. Please see the full [v3.0 Image Upgrade Advice](/en/guides/images/#upgrade-to-v30-from-v2x) for full details! +```js del={3,7} +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import image from '@astrojs/image'; + +export default defineConfig({ + integrations: [ + image(), + ] +}) +``` + ### Removed: `<Markdown />` component In Astro v2.x, Astro deprecated the `<Markdown />` component and moved it to an external package. -Astro v3.0 comletely removes the package `@astrojs/markdown-component`, so Astro's `<Markdown />` component will no longer work in your project. +Astro v3.0 completely removes the package `@astrojs/markdown-component`. Astro's `<Markdown />` component will no longer work in your project. #### What should I do? -Uninstall the `@astrojs/markdown-component` package. To continue using a similar `<Markdown />` component in your code, consider using [community integrations](https://astro.build/integrations/) that provide a similar component like https://github.com/natemoo-re/astro-remote, and be sure to update your component imports and attributes as necessary according to the integration's own documentation. Otherwise, delete all references to importing Astro's `<Markdown />` component and the component itself in your `.astro` files. You will need to rewrite your content as HTML directly or [import Markdown](/en/guides/markdown-content/#importing-markdown) from an `.md` file. +Remove all instances of the `@astrojs/markdown-component`. + +```astro del={3} +--- +// astro.config.mjs +import Markdown from '@astrojs/markdown-component'; +--- +``` + +To continue using a similar `<Markdown />` component in your code, consider using [community integrations](https://astro.build/integrations/) such as [`astro-remote`](https://github.com/natemoo-re/astro-remote). Be sure to update your `<Markdown />` component imports and attributes as necessary, according to the integration's own documentation. + +Otherwise, delete all references to importing Astro's `<Markdown />` component and the component itself in your `.astro` files. You will need to rewrite your content as HTML directly or [import Markdown](/en/guides/markdown-content/#importing-markdown) from a `.md` file. ### Changed: automatic flattening of `getStaticPaths()`'s return value From 427f073fadc65e5e802fd7cf0773c244a7414aec Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 15:35:10 +0000 Subject: [PATCH 25/58] edited build config options moved to adapters --- src/content/docs/en/guides/upgrade-to/v3.mdx | 44 ++++++++++---------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 56b38455ba7c7..6246faa38b27f 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -147,33 +147,15 @@ To continue using a similar `<Markdown />` component in your code, consider usin Otherwise, delete all references to importing Astro's `<Markdown />` component and the component itself in your `.astro` files. You will need to rewrite your content as HTML directly or [import Markdown](/en/guides/markdown-content/#importing-markdown) from a `.md` file. -### Changed: automatic flattening of `getStaticPaths()`'s return value - -:::note[Example needed] -Find an example of returning an array of an array -::: - -In Astro v2.x, we would magically flatten the result of `getStaticPaths()` automatically for the user, so if you returned an array of array, it would still work - -Astro v3.0 we changed this in favour of the user doing it themselves when they need to, in line with how we typically prefer for users to do explicit things. - -Removed automatic flattening of getStaticPaths result. .flatMap and .flat should now be used to ensure that you’re returning a flat array. - -#### What should I do? - -If you're returning an array of arrays instead of an array of object (as you should), please flatten it using .flat(), or if you're using a .map(), use .flatMap() instead - -A [error message indicating that `getStaticPath()`'s return value must be an array of objects](/en/reference/errors/invalid-get-static-paths-entry/#what-went-wrong) will be provided if you need to update your code. - -### Changed: `build.excludeMiddleware` and `build.split` options have been moved to adapter config +### Removed: `build.excludeMiddleware` and `build.split` -In Astro v2.x, `build.excludeMiddleware` and `build.split` could be used to change how specific files were emitted. +In Astro v2.x, `build.excludeMiddleware` and `build.split` could be used to change how specific files were emitted when using an adapter in SSR mode. -Astro v3.0, these build config options have been replaced with new adapter configuruation options. +Astro v3.0 replaces these build config options with new adapter configuration options **(CHECK ONLY Netlify, Vercel, and Cloudflare??)** to perform the same tasks: `edgeMiddleware` and `functionPerRoute`. #### What should I do? -Update the config file to use the option **in the adapter**. +Update the Astro config file to now use the new options **in the adapter configuration** directly. ```astro title="astro.config.mjs" del={5-7} ins={9} import { defineConfig } from "astro/config"; @@ -231,6 +213,24 @@ export default defineConfig({ }); ``` +### Changed: automatic flattening of `getStaticPaths()`'s return value + +:::note[Example needed] +Find an example of returning an array of an array +::: + +In Astro v2.x, we would magically flatten the result of `getStaticPaths()` automatically for the user, so if you returned an array of array, it would still work + +Astro v3.0 we changed this in favour of the user doing it themselves when they need to, in line with how we typically prefer for users to do explicit things. + +Removed automatic flattening of getStaticPaths result. .flatMap and .flat should now be used to ensure that you’re returning a flat array. + +#### What should I do? + +If you're returning an array of arrays instead of an array of object (as you should), please flatten it using .flat(), or if you're using a .map(), use .flatMap() instead + +A [error message indicating that `getStaticPath()`'s return value must be an array of objects](/en/reference/errors/invalid-get-static-paths-entry/#what-went-wrong) will be provided if you need to update your code. + ### Changed: default image service to Sharp instead of Squoosh In Astro v2.x, Squoosh was the default image service. From 2635170c428e4b25e24b56372940cafa42e1e3e6 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 17:43:15 +0000 Subject: [PATCH 26/58] remove extra build to adapter code samples --- src/content/docs/en/guides/upgrade-to/v3.mdx | 28 -------------------- 1 file changed, 28 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 6246faa38b27f..d34d4f1fb3909 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -171,34 +171,6 @@ export default defineConfig({ }); ``` -```astro title="astro.config.mjs" del={5-7} ins={9} -import { defineConfig } from "astro/config"; -import vercel from "@astrojs/vercel/serverless"; - -export default defineConfig({ - build: { - split: true - }, - adapter: vercel({ - functionPerRoute: true - }), -}); -``` - -```astro title="astro.config.mjs" del={5-7} ins={9} -import { defineConfig } from "astro/config"; -import netlify from "@astrojs/netlify/functions"; - -export default defineConfig({ - build: { - excludeMiddleware: true - }, - adapter: netlify({ - edgeMiddleware: true - }), -}); -``` - ```astro title="astro.config.mjs" del={5-7} ins={9} import { defineConfig } from "astro/config"; import netlify from "@astrojs/netlify/functions"; From 18c5a640bccfe7831794e30ecdcdb88c99a21ea8 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 17:48:24 +0000 Subject: [PATCH 27/58] updated typescript version entry --- src/content/docs/en/guides/upgrade-to/v3.mdx | 26 +++++++++++--------- 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index d34d4f1fb3909..1a9398427852b 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -99,6 +99,20 @@ Astro v3.0 drops Node 16 support entirely, so that all Astro users can take adva You can specify Node `18.14.1` for your Astro project either in a dashboard configuration setting, or a `.nvmrc` file. +### Removed: Support for TypeScript 4.x + +In Astro v2.x, the `tsconfig.json` presets include support for both TypeScript 4.x and 5.x. + +Astro v3.0 updates the `tsconfig.json` presets to only support TypeScript 5.x. Astro now assumes that you use TypeScript 5.0 (March 2023), or that your editor includes it (e.g. VS Code 1.77). + +#### What should I do? + +If you have installed TypeScript locally, update to at least v5.0. + +```bash +npm install typescript@latest --save-dev +``` + ### Removed: `@astrojs/image` In Astro v2.x, Astro offered an official image integration that included Astro `<Image />` and `<Picture />` components. @@ -307,19 +321,7 @@ Astro v3.0 changes the default port to `4321`. Update any existing references to `localhost:3000`, for example in tests or in your `README` to reflect the new port `localhost:4321`. -### Changed: TypeScript minimum version - -In Astro v2.x, the `tsconfig.json` presets include support for both TypeScript 4.x and 5.x. - -Astro v3.0 updates the `tsconfig.json` presets to only support TypeScript 5.x. Astro now assumes that you use TypeScript 5.0 (March 2023), or that your editor includes it (e.g. VS Code 1.77) - -#### What should I do? - -Update your TypeScript version to at least v5.0. -```bash -npm install typescript@latest --save-dev -``` ### Changed `astro check` is now an external package From 864fc6d9466ed9eda7373d4c7f523ec500d7f909 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 18:10:25 +0000 Subject: [PATCH 28/58] kebab case, astro check entries done; end of REMOVEDs --- src/content/docs/en/guides/upgrade-to/v3.mdx | 145 ++++++------------- 1 file changed, 45 insertions(+), 100 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 1a9398427852b..afabf169e58b3 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -99,7 +99,7 @@ Astro v3.0 drops Node 16 support entirely, so that all Astro users can take adva You can specify Node `18.14.1` for your Astro project either in a dashboard configuration setting, or a `.nvmrc` file. -### Removed: Support for TypeScript 4.x +### Removed: Support for TypeScript 4 In Astro v2.x, the `tsconfig.json` presets include support for both TypeScript 4.x and 5.x. @@ -139,7 +139,6 @@ export default defineConfig({ }) ``` - ### Removed: `<Markdown />` component In Astro v2.x, Astro deprecated the `<Markdown />` component and moved it to an external package. @@ -199,6 +198,50 @@ export default defineConfig({ }); ``` +### Removed: kebab-case transform for camelCase CSS variables + +In Astro v2.x, camelCase CSS variables passed to the `style` attribute were rendered as both camelCase (as written) and kebab-case (kept for backwards compatibility). + +Astro 3.0 removes the kebab-case transform for these camelCase CSS variable names, and only the original camelCase CSS variable is rendered. + +```astro "my-value" +--- +// src/components/MyAstroComponent.astro +const myValue = "red" +--- +<!-- input --> +<div style={{ "--myValue": myValue }}></div> + +<!-- output (Astro 2.x) --> +<div style="--my-value:var(--myValue);--myValue:red"></div> +<!-- output (Astro 3.0) --> +<div style="--myValue:red"></div> +``` + +#### What should I do? + +If you were relying on Astro to transform kebab-case in your styles, update your existing styles to camelCase to prevent missing styles. For example: + +```diff +<style> + div { +- color: var(--my-value); ++ color: var(--myValue); + } +</style> +``` + +### Moved: `astro check` is now an external package + +In Astro v2.x, `astro check` was included in Astro by default and its dependencies were bundled in Astro. This meant a larger package whether or not you ever used `astro check`. This also prevented you from having control over the version of TypeScript and the Astro Language Server to use. + + +Astro v3.0 moves the `astro check` command out of Astro core and now requires an external package `@astrojs/check`. Additionally, you must install `typescript` in your project to use the `astro check` command. + +#### What should I do? + +Run the `astro check` command after upgrading to Astro v3.0 and follow the prompts to install the required dependencies, or manually install `@astrojs/check` and `typescript` into your project. + ### Changed: automatic flattening of `getStaticPaths()`'s return value :::note[Example needed] @@ -321,19 +364,6 @@ Astro v3.0 changes the default port to `4321`. Update any existing references to `localhost:3000`, for example in tests or in your `README` to reflect the new port `localhost:4321`. - - -### Changed `astro check` is now an external package - -In Astro v2.x, `astro check` was included in Astro by default and its dependencies were bundled in Astro. This meant a larger package whether or not you ever used `astro check` and also prevented you from having control over the version of TypeScript and the Astro Language Server to use. - - -Astro v3.0 moves the `astro check` command out of Astro core and now requires an external package `@astrojs/check`. Additionally, you must install `typescript` in your project. - -#### What should I do? - -Run the `astro check` command after upgrading to Astro v3.0 and follow the prompts to install the required dependencies, or manually install `@astrojs/check` and `typescript` into your project. - ### Added: simple asset support for Cloudflare, Deno, Vercel Edge and Netlify Edge In Astro v2.x, using the assets feature in Cloudflare, Deno, Vercel Edge and Netlify Edge errors in runtime as the environments do not support Astro's builtin Squoosh and Sharp image optimization. @@ -360,36 +390,7 @@ Astro V3 still displays the error log, but now you can build the project. When using an adapter that supports neither Squoosh or Sharp, Astro will now automatically use an image service that does not support processing, but still provides the other benefits of `astro:assets` such as enforcing `alt`, no CLS etc to users. Should be noted that it does no transformations or processing, but you still get all the other benefits (no CLS, alt enforced, etc). All of those benefits are part of the image service, if you make your own, you lose those benefits unless you make it yourself -### Removed: camelCase transformations - -In Astro 2.x, Astro automatically transformed camelCase CSS variable names passed to the `style` attribute of an HTML element. - -Astro 3.0 removes backwards-compatible kebab-case transform for these camelCase CSS variable names. - -#### What should I do? - -If you were relying on Astro to transform kebab-case in your styles, update your existing styles to use the camelCase version to prevent missing styles. For example: - -```astro ---- -const myValue = "red" ---- -<!-- input --> -<div style={{ "--myValue": myValue }}></div> -<!-- output (before) --> -<div style="--my-value:var(--myValue);--myValue:red"></div> -<!-- output (after) --> -<div style="--myValue:red"></div> -``` -```diff -<style> - div { -- color: var(--my-value); -+ color: var(--myValue); - } -</style> -``` ### Changed: default `scopedStyleStrategy` @@ -462,62 +463,6 @@ export default defineConfig({ }); ``` - -### Removed: kebab-case transform for camelCase CSS variables - -In Astro v2.x, camelCase CSS variables passed to the `style` attribute were rendered as camelCase (original) and kebab-case (incorrect by kept for backwards compatibility). - -Astro v3.0 removes the kebab-case transform, and only the original camelCase CSS variable is rendered. - - ```astro - --- - const myValue = "red" - --- - <!-- input --> - <div style={{ "--myValue": myValue }}></div> - <!-- output (before) --> - <div style="--my-value:var(--myValue);--myValue:red"></div> - <!-- output (after) --> - <div style="--myValue:red"></div> - ``` - -#### What should I do? - -If you were relying on the kebab-case transform in your styles, make sure to use the camelCase version to prevent missing styles. For example: - - ```diff - <style> - div { - - color: var(--my-value); - + color: var(--myValue); - } - </style> - ``` -DUPE TO BE COMBINED - - Remove backwards-compatible kebab-case transform for camelCase CSS variable names passed to the `style` attribute. If you were relying on the kebab-case transform in your styles, make sure to use the camelCase version to prevent missing styles. For example: - -```astro ---- -const myValue = "red" ---- -<!-- input --> -<div style={{ "--myValue": myValue }}></div> -<!-- output (before) --> -<div style="--my-value:var(--myValue);--myValue:red"></div> -<!-- output (after) --> -<div style="--myValue:red"></div> -``` - -```diff -<style> - div { -- color: var(--my-value); -+ color: var(--myValue); - } -</style> -``` - ### Changed entrypoint export paths In Astro v2.x, you can import internal Astro APIs from `astro/internal/star` and `astro/runtime/server/star`. From 747a91cfa0e49007ffcbca21af7e5cede4f632e6 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 18:22:14 +0000 Subject: [PATCH 29/58] tralingslash default behavior entry --- src/content/docs/en/guides/upgrade-to/v3.mdx | 37 +++++++++++--------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index afabf169e58b3..cbb721bfac99a 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -242,6 +242,27 @@ Astro v3.0 moves the `astro check` command out of Astro core and now requires an Run the `astro check` command after upgrading to Astro v3.0 and follow the prompts to install the required dependencies, or manually install `@astrojs/check` and `typescript` into your project. +### Changed default: import.meta.env.BASE_URL `trailingSlash` behaviour + +In Astro v2.x, `import.meta.env.BASE_URL` appended your `base` setting with a trailing slash by default. `trailingSlash: "ignore"`also appended a trailing slash. + +Astro v3.0 `import.meta.env.BASE_URL` is not appended with a trailing slash by default, nor when `trailingSlash: "ignore"` is set. The existing behavior of `base` in combination with `trailingSlash: "always"` or `trailingSlash: "never"` is unchanged. + +#### What should I do? + +If your `base` already has a trailing slash, no change is needed. + +If your `base` does not have a trailing slash, add one if you wish to preserve the previous default (or `trailingSlash: "ignore"`) behaviour: + +```astro title="astro.config.mjs" del={4} ins={5} +import { defineConfig } from "astro/config"; + +export default defineConfig({ + base: 'my-base', + base: 'my-base/', +}); +``` + ### Changed: automatic flattening of `getStaticPaths()`'s return value :::note[Example needed] @@ -408,23 +429,7 @@ export default defineConfig({ }) ``` -### Changed: import.meta.env.BASE_URL default `trailingSlash` behaviour - -In Astro v2.x, `import.meta.env.BASE_URL`, which derives from `base` config, is always appended a trailingSlash by default or when `trailingSlash: "ignore"` is set. - -Astro v3.0 `import.meta.env.BASE_URL` is not appended with a trailingSlash by default or when `trailingSlash: "ignore"` is set. The existing behavior of `base` in combination with `trailingSlash: "always"` or `trailingSlash: "never"` is unchanged. - -#### What should I do? - -If your `base` already has a trailing slash, no change is needed. - - If your `base` does not have a trailing slash, add one to preserve the previous behaviour: - ```diff - // astro.config.mjs - - base: 'my-base', - + base: 'my-base/', -``` ### Changed: Multiple JSX framework configuration From 7cb56ee43e875941645e22db1b42b09740ce79ac Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 18:27:52 +0000 Subject: [PATCH 30/58] htmlcompress entry --- src/content/docs/en/guides/upgrade-to/v3.mdx | 42 ++++++++++---------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index cbb721bfac99a..bede8068dad5f 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -242,7 +242,7 @@ Astro v3.0 moves the `astro check` command out of Astro core and now requires an Run the `astro check` command after upgrading to Astro v3.0 and follow the prompts to install the required dependencies, or manually install `@astrojs/check` and `typescript` into your project. -### Changed default: import.meta.env.BASE_URL `trailingSlash` behaviour +### Changed default: import.meta.env.BASE_URL `trailingSlash` In Astro v2.x, `import.meta.env.BASE_URL` appended your `base` setting with a trailing slash by default. `trailingSlash: "ignore"`also appended a trailing slash. @@ -263,6 +263,26 @@ export default defineConfig({ }); ``` +### Changed default: `compressHTML` + +In Astro v2.x, Astro only compressed your emitted HTML when `compressHTML` was explicitly set to `true`. The default value was `false`. + +Astro v3.0 now compresses emitted HTML by default. + +#### What should I do? + +You can now remove `compressHTML: true` from your configuration as this is the new default behavior. + +```ts title="astro.config.mjs" del={4} +import { defineConfig } from "astro/config"; + +export default defineConfig({ + compressHTML: true +}) +``` + +You must now set `compressHTML: false` to opt out of HTML compression. + ### Changed: automatic flattening of `getStaticPaths()`'s return value :::note[Example needed] @@ -355,26 +375,6 @@ if (id) { } ``` -### Changed: the default value of `compressHTML` - -In Astro v2.x, Astro only compressed the emitted HTML by explicitly setting the configuration to `true`. - -Astro v3.0 now compresses emitted HTML by default. - -#### What should I do? - -You can now remove `compressHTML: true` from your configuration as this is now the default behavior. - -```ts title="astro.config.mjs" del={4} -import { defineConfig } from "astro/config"; - -export default defineConfig({ - compressHTML: true -}) -``` - -You must now set `compressHTML: false` to opt out of HTML compression. - ### Changed: default port used In Astro v2.x, Astro ran on port `3000` by default. From 68f73163403a005945812e6ace208826fe21acbd Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 18:43:29 +0000 Subject: [PATCH 31/58] scopedStyleStrategy and added links up to here --- src/content/docs/en/guides/upgrade-to/v3.mdx | 50 ++++++++++---------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index bede8068dad5f..e58c02ad77b98 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -164,7 +164,7 @@ Otherwise, delete all references to importing Astro's `<Markdown />` component a In Astro v2.x, `build.excludeMiddleware` and `build.split` could be used to change how specific files were emitted when using an adapter in SSR mode. -Astro v3.0 replaces these build config options with new adapter configuration options **(CHECK ONLY Netlify, Vercel, and Cloudflare??)** to perform the same tasks: `edgeMiddleware` and `functionPerRoute`. +Astro v3.0 replaces these build config options with new [SSR adapter configuration options](/en/guides/integrations-guide/#official-integrations) to perform the same tasks: `edgeMiddleware` and `functionPerRoute`. #### What should I do? @@ -233,7 +233,7 @@ If you were relying on Astro to transform kebab-case in your styles, update your ### Moved: `astro check` is now an external package -In Astro v2.x, `astro check` was included in Astro by default and its dependencies were bundled in Astro. This meant a larger package whether or not you ever used `astro check`. This also prevented you from having control over the version of TypeScript and the Astro Language Server to use. +In Astro v2.x, [`astro check`](/en/reference/cli-reference/#astro-check) was included in Astro by default and its dependencies were bundled in Astro. This meant a larger package whether or not you ever used `astro check`. This also prevented you from having control over the version of TypeScript and the Astro Language Server to use. Astro v3.0 moves the `astro check` command out of Astro core and now requires an external package `@astrojs/check`. Additionally, you must install `typescript` in your project to use the `astro check` command. @@ -244,9 +244,9 @@ Run the `astro check` command after upgrading to Astro v3.0 and follow the promp ### Changed default: import.meta.env.BASE_URL `trailingSlash` -In Astro v2.x, `import.meta.env.BASE_URL` appended your `base` setting with a trailing slash by default. `trailingSlash: "ignore"`also appended a trailing slash. +In Astro v2.x, `import.meta.env.BASE_URL` appended your [`base`](/en/reference/configuration-reference/#base) setting with a [trailingSlash](/en/reference/configuration-reference/#trailingslash) by default. `trailingSlash: "ignore"`also appended a trailing slash. -Astro v3.0 `import.meta.env.BASE_URL` is not appended with a trailing slash by default, nor when `trailingSlash: "ignore"` is set. The existing behavior of `base` in combination with `trailingSlash: "always"` or `trailingSlash: "never"` is unchanged. +Astro v3.0 does not appended `import.meta.env.BASE_URL` with a trailing slash by default, nor when `trailingSlash: "ignore"` is set. The existing behavior of `base` in combination with `trailingSlash: "always"` or `trailingSlash: "never"` is unchanged. #### What should I do? @@ -265,7 +265,7 @@ export default defineConfig({ ### Changed default: `compressHTML` -In Astro v2.x, Astro only compressed your emitted HTML when `compressHTML` was explicitly set to `true`. The default value was `false`. +In Astro v2.x, Astro only compressed your emitted HTML when [`compressHTML`](/en/reference/configuration-reference/#compresshtml) was explicitly set to `true`. The default value was `false`. Astro v3.0 now compresses emitted HTML by default. @@ -283,6 +283,26 @@ export default defineConfig({ You must now set `compressHTML: false` to opt out of HTML compression. +### Changed default: `scopedStyleStrategy` + +In Astro v2.x, the default value of [`scopedStyleStrategy`](/en/reference/configuration-reference/#scopedstylestrategy) was `"where"`. + +Astro v3.0 introduces a new, default value: `"attribute"`. By default, styles are now applied using `data-*` attributes. + +#### What should I do? + +To retain your project's current style scoping, update the configuration file to the previous default value: + + +```ts title="astro.config.mjs" ins={4} +import { defineConfig } from "astro/config"; + +export default defineConfig({ + scopedStyleStrategy: "where" +}) +``` + + ### Changed: automatic flattening of `getStaticPaths()`'s return value :::note[Example needed] @@ -411,26 +431,6 @@ Astro V3 still displays the error log, but now you can build the project. When using an adapter that supports neither Squoosh or Sharp, Astro will now automatically use an image service that does not support processing, but still provides the other benefits of `astro:assets` such as enforcing `alt`, no CLS etc to users. Should be noted that it does no transformations or processing, but you still get all the other benefits (no CLS, alt enforced, etc). All of those benefits are part of the image service, if you make your own, you lose those benefits unless you make it yourself - - -### Changed: default `scopedStyleStrategy` - -In Astro v2.x, the default value of `scopedStyleStrategy` was `"where"`. - -Astro v3.0, the default value is `"attribute"`. By default, styles are now applied using `data-*` attributes. - -#### What should I do? - -To retain your project's current style scoping, update the configuration file to the previous default value: - -```diff -export default defineConfig({ -+ scopedStyleStrategy: "where" -}) -``` - - - ### Changed: Multiple JSX framework configuration In Astro v2.x, you could use multiple JSX framework integrations (React, Solid, Preact) in the same project and Astro without having to identify which files belonged to which framework. Astro automatically scanned your components to determine which framework-specific transformations should be used, but at a performance cost. From 0db35b1ece0bb39d837b6e7362a6df298bf4ea22 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 18:45:19 +0000 Subject: [PATCH 32/58] typo in trailingSlash --- src/content/docs/en/guides/upgrade-to/v3.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index e58c02ad77b98..e356c02dbf8e6 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -246,7 +246,7 @@ Run the `astro check` command after upgrading to Astro v3.0 and follow the promp In Astro v2.x, `import.meta.env.BASE_URL` appended your [`base`](/en/reference/configuration-reference/#base) setting with a [trailingSlash](/en/reference/configuration-reference/#trailingslash) by default. `trailingSlash: "ignore"`also appended a trailing slash. -Astro v3.0 does not appended `import.meta.env.BASE_URL` with a trailing slash by default, nor when `trailingSlash: "ignore"` is set. The existing behavior of `base` in combination with `trailingSlash: "always"` or `trailingSlash: "never"` is unchanged. +Astro v3.0 no longer appends `import.meta.env.BASE_URL` with a trailing slash by default, nor when `trailingSlash: "ignore"` is set. (The existing behavior of `base` in combination with `trailingSlash: "always"` or `trailingSlash: "never"` is unchanged.) #### What should I do? From 736d767c76f6da51cdd07ee57315fb47d07db015 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 18:49:20 +0000 Subject: [PATCH 33/58] scoped style link --- src/content/docs/en/guides/upgrade-to/v3.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index e356c02dbf8e6..94845e30ee4c3 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -291,7 +291,7 @@ Astro v3.0 introduces a new, default value: `"attribute"`. By default, styles ar #### What should I do? -To retain your project's current style scoping, update the configuration file to the previous default value: +To retain your project's current [style scoping](/en/guides/styling/#scoped-styles), update the configuration file to the previous default value: ```ts title="astro.config.mjs" ins={4} From 389d6a3638c4aba3591bb0113a6edcf655dacb56 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 19:16:00 +0000 Subject: [PATCH 34/58] inlineStyleSheets plus code example syntax fixes up to here --- src/content/docs/en/guides/upgrade-to/v3.mdx | 56 ++++++++++---------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 94845e30ee4c3..8b43911f07166 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -149,9 +149,8 @@ Astro v3.0 completely removes the package `@astrojs/markdown-component`. Astro's Remove all instances of the `@astrojs/markdown-component`. -```astro del={3} +```astro del={2} title="src/components/MyAstroComponent.astro" --- -// astro.config.mjs import Markdown from '@astrojs/markdown-component'; --- ``` @@ -170,7 +169,7 @@ Astro v3.0 replaces these build config options with new [SSR adapter configurati Update the Astro config file to now use the new options **in the adapter configuration** directly. -```astro title="astro.config.mjs" del={5-7} ins={9} +```js title="astro.config.mjs" del={5-7} ins={9} import { defineConfig } from "astro/config"; import vercel from "@astrojs/vercel/serverless"; @@ -184,7 +183,7 @@ export default defineConfig({ }); ``` -```astro title="astro.config.mjs" del={5-7} ins={9} +```js title="astro.config.mjs" del={5-7} ins={9} import { defineConfig } from "astro/config"; import netlify from "@astrojs/netlify/functions"; @@ -222,11 +221,11 @@ const myValue = "red" If you were relying on Astro to transform kebab-case in your styles, update your existing styles to camelCase to prevent missing styles. For example: -```diff +```astro del={3} ins={4} title="src/components/MyAstroComponent.astro" <style> div { -- color: var(--my-value); -+ color: var(--myValue); + color: var(--my-value); + color: var(--myValue); } </style> ``` @@ -254,7 +253,7 @@ If your `base` already has a trailing slash, no change is needed. If your `base` does not have a trailing slash, add one if you wish to preserve the previous default (or `trailingSlash: "ignore"`) behaviour: -```astro title="astro.config.mjs" del={4} ins={5} +```js title="astro.config.mjs" del={4} ins={5} import { defineConfig } from "astro/config"; export default defineConfig({ @@ -273,7 +272,7 @@ Astro v3.0 now compresses emitted HTML by default. You can now remove `compressHTML: true` from your configuration as this is the new default behavior. -```ts title="astro.config.mjs" del={4} +```js title="astro.config.mjs" del={4} import { defineConfig } from "astro/config"; export default defineConfig({ @@ -294,7 +293,7 @@ Astro v3.0 introduces a new, default value: `"attribute"`. By default, styles ar To retain your project's current [style scoping](/en/guides/styling/#scoped-styles), update the configuration file to the previous default value: -```ts title="astro.config.mjs" ins={4} +```js title="astro.config.mjs" ins={4} import { defineConfig } from "astro/config"; export default defineConfig({ @@ -302,6 +301,25 @@ export default defineConfig({ }) ``` +### Changed default: `inlineStyleSheets` + +In Astro v2.x, all project stylesheets were sent as link tags by default. You could opt in to `"always"` inlining them into `<style>` tags, or to `"auto"`matically inlining only stylesheets below a certain size by setting the [`build.inlineStylesheets`](/en/reference/configuration-reference/#buildinlinestylesheets) configuration. The default setting was `"never"`. + +Astro v3.0 changes the default value of `inlineStylesheets` to `"auto"`. Stylesheets smaller than `ViteConfig.build.assetsInlineLimit` (default: 4kb) are inlined by default. Otherwise, project styles are sent in external stylesheets. + +#### What should I do? +If you want to keep your project's current behavior, set `build.inlineStylesheets` to the previous default, `"never"`: + + +```js title="astro.config.mjs" ins={4-6} +import { defineConfig } from "astro/config"; + +export default defineConfig({ + build: { + inlineStylesheets: "never" + } +}) +``` ### Changed: automatic flattening of `getStaticPaths()`'s return value @@ -486,24 +504,6 @@ These are entrypoints for Astro's internal API and should not affect your projec + import 'astro/runtime/server/index.js'; ``` -### Small stylesheets now get inlined by default -In Astro v2.x, all project stylesheets were sent lnd u could opt-in to inlining them by using the `build.inlineStylesheets` configuration. - -were sent as link tags by default and you could opt in to inlining them - -Astro v3.0 defaults `inlineStylesheets` to "auto", which means stylesheets smaller than 4kB get included in the initial response. - -#### What should I do? -Nothing, this change does not require any migration. To go back to the old behavior, configure `inlineStylesheets` to "never" - -```diff -export default defineConfig({ - build: { -+ inlineStylesheets: "never" - } -}) -``` - ### Changed implementation of `class:list` directive In Astro v2.x, `class:list` used a custom implementation inspired by [`clsx`](https://github.com/lukeed/clsx) with a few extra features like deduplication and `Set` support. From a0ef058bd50dfe05e98f38ebf5473ad9adb8d7b8 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 19:42:12 +0000 Subject: [PATCH 35/58] class:list entries --- src/content/docs/en/guides/upgrade-to/v3.mdx | 79 ++++++++++---------- 1 file changed, 41 insertions(+), 38 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 8b43911f07166..95f2a0861790f 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -230,6 +230,47 @@ If you were relying on Astro to transform kebab-case in your styles, update your </style> ``` +### Removed: `class:list` features + +In Astro v2.x, the [`class:list` directive](/en/reference/directives-reference/#classlist) used a custom implementation inspired by [`clsx`](https://github.com/lukeed/clsx) with a few extra features like deduplication and `Set` support. + +Astro v3.0 now uses `clsx` directly for `class:list`, which does not support deduplication or `Set` values. + +#### What should I do? + +Replace any `Set` elements passed to the `class:list` directive with a plain `Array`. + +```astro title="src/components/MyAstroComponent.astro" del={4} ins={5} +<Component class:list={[ + 'a', + 'b', + new Set(['c', 'd']) + ['c', 'd'] +]} /> +``` + +### Removed: passing `class:list` as a prop + +In Astro v2.x, [`class:list` values](/en/reference/directives-reference/#classlist) were sent to components via [`Astro.props['class:list']`](/en/reference/api-reference/#astroprops). + +Astro v3.0 normalizes `class:list` values into a string before being sent to components via `Astro.props['class']` + +#### What should I do? + +Remove any code that expects to receive the `class:list` prop. + +```astro title="src/components/MyAstroComponent.astro" del={2,3,7} ins={4,8} "classList" "'class:list': classList" +--- +import { clsx } from 'clsx'; +const { class: className, 'class:list': classList } = Astro.props; +const { class: className } = Astro.props; +--- +<div + class:list={[className, classList]} + class:list={[className]} +/> +``` + ### Moved: `astro check` is now an external package In Astro v2.x, [`astro check`](/en/reference/cli-reference/#astro-check) was included in Astro by default and its dependencies were bundled in Astro. This meant a larger package whether or not you ever used `astro check`. This also prevented you from having control over the version of TypeScript and the Astro Language Server to use. @@ -504,45 +545,7 @@ These are entrypoints for Astro's internal API and should not affect your projec + import 'astro/runtime/server/index.js'; ``` -### Changed implementation of `class:list` directive -In Astro v2.x, `class:list` used a custom implementation inspired by [`clsx`](https://github.com/lukeed/clsx) with a few extra features like deduplication and `Set` support. - -In Astro v3.0, `class:list` uses [`clsx`](https://github.com/lukeed/clsx) directly, which does not support deduplication or `Set` values. - -#### What should I do? - -Replace any `Set` elements passed to the `class:list` directive with a plain `Array`. - -```diff - <Component class:list={[ - 'a', - 'b', -- new Set(['c', 'd']) -+ ['c', 'd'] - ]} /> -``` - -### Changed behavior of `class:list` directive for components - -In Astro v2.x, `class:list` values were sent to components via `Astro.props['class:list']`. -In Astro v3.0, `class:list` values are normalized into a string before being sent to components via `Astro.props['class']` - -#### What should I do? - -Remove any code that expects to receive the `class:list` prop. - -```diff ---- -- import { clsx } from 'clsx'; -- const { class: className, 'class:list': classList } = Astro.props; -+ const { class: className } = Astro.props; ---- -<div -- class:list={[className, classList]} -+ class={className} -/> -``` ## Known Issues From aab8aaa2d9b6b9894b89f3bf105c0e310df16042 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 20:12:03 +0000 Subject: [PATCH 36/58] defalt port --- src/content/docs/en/guides/upgrade-to/v3.mdx | 21 ++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 95f2a0861790f..2cf8a9b8be806 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -282,6 +282,17 @@ Astro v3.0 moves the `astro check` command out of Astro core and now requires an Run the `astro check` command after upgrading to Astro v3.0 and follow the prompts to install the required dependencies, or manually install `@astrojs/check` and `typescript` into your project. +### Changed default: port `3000` + +In Astro v2.x, Astro ran on port `3000` by default. + +Astro v3.0 changes the default port to `4321`. 🚀 + +#### What should I do? + +Update any existing references to `localhost:3000`, for example in tests or in your `README`, to reflect the new port `localhost:4321`. + + ### Changed default: import.meta.env.BASE_URL `trailingSlash` In Astro v2.x, `import.meta.env.BASE_URL` appended your [`base`](/en/reference/configuration-reference/#base) setting with a [trailingSlash](/en/reference/configuration-reference/#trailingslash) by default. `trailingSlash: "ignore"`also appended a trailing slash. @@ -454,16 +465,6 @@ if (id) { } ``` -### Changed: default port used - -In Astro v2.x, Astro ran on port `3000` by default. - -Astro v3.0 changes the default port to `4321`. - -#### What should I do? - -Update any existing references to `localhost:3000`, for example in tests or in your `README` to reflect the new port `localhost:4321`. - ### Added: simple asset support for Cloudflare, Deno, Vercel Edge and Netlify Edge In Astro v2.x, using the assets feature in Cloudflare, Deno, Vercel Edge and Netlify Edge errors in runtime as the environments do not support Astro's builtin Squoosh and Sharp image optimization. From 1717ef375fb277ce8da0524bfc04bbc47b459f14 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 20:25:39 +0000 Subject: [PATCH 37/58] getStaticPaths flattening entry --- src/content/docs/en/guides/upgrade-to/v3.mdx | 100 +++++++++---------- 1 file changed, 49 insertions(+), 51 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 2cf8a9b8be806..81972eb3550b4 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -197,39 +197,6 @@ export default defineConfig({ }); ``` -### Removed: kebab-case transform for camelCase CSS variables - -In Astro v2.x, camelCase CSS variables passed to the `style` attribute were rendered as both camelCase (as written) and kebab-case (kept for backwards compatibility). - -Astro 3.0 removes the kebab-case transform for these camelCase CSS variable names, and only the original camelCase CSS variable is rendered. - -```astro "my-value" ---- -// src/components/MyAstroComponent.astro -const myValue = "red" ---- -<!-- input --> -<div style={{ "--myValue": myValue }}></div> - -<!-- output (Astro 2.x) --> -<div style="--my-value:var(--myValue);--myValue:red"></div> -<!-- output (Astro 3.0) --> -<div style="--myValue:red"></div> -``` - -#### What should I do? - -If you were relying on Astro to transform kebab-case in your styles, update your existing styles to camelCase to prevent missing styles. For example: - -```astro del={3} ins={4} title="src/components/MyAstroComponent.astro" -<style> - div { - color: var(--my-value); - color: var(--myValue); - } -</style> -``` - ### Removed: `class:list` features In Astro v2.x, the [`class:list` directive](/en/reference/directives-reference/#classlist) used a custom implementation inspired by [`clsx`](https://github.com/lukeed/clsx) with a few extra features like deduplication and `Set` support. @@ -271,6 +238,55 @@ const { class: className } = Astro.props; /> ``` +### Removed: kebab-case transform for camelCase CSS variables + +In Astro v2.x, camelCase CSS variables passed to the `style` attribute were rendered as both camelCase (as written) and kebab-case (kept for backwards compatibility). + +Astro 3.0 removes the kebab-case transform for these camelCase CSS variable names, and only the original camelCase CSS variable is rendered. + +```astro "my-value" +--- +// src/components/MyAstroComponent.astro +const myValue = "red" +--- +<!-- input --> +<div style={{ "--myValue": myValue }}></div> + +<!-- output (Astro 2.x) --> +<div style="--my-value:var(--myValue);--myValue:red"></div> +<!-- output (Astro 3.0) --> +<div style="--myValue:red"></div> +``` + +#### What should I do? + +If you were relying on Astro to transform kebab-case in your styles, update your existing styles to camelCase to prevent missing styles. For example: + +```astro del={3} ins={4} title="src/components/MyAstroComponent.astro" +<style> + div { + color: var(--my-value); + color: var(--myValue); + } +</style> +``` + +### Removed: automatic flattening of `getStaticPaths()`'s return value + +:::note[Example maybe?] +Do we want an example of returning an array of an array, requiring flattening? +::: + +In Astro v2.x, the return value of `getStaticPaths()` was automatically flattened to allow you to return an array of array without errors. + +Astro v3.0 removes automatic flattening of `getStaticPaths()`'s result. + +#### What should I do? + +If you're returning an array of arrays instead of an array of _objects_ (as is expected), `.flatMap` and `.flat` should now be used to ensure that you are returning a flat array. + +An [error message indicating that `getStaticPath()`'s return value must be an array of objects](/en/reference/errors/invalid-get-static-paths-entry/#what-went-wrong) will be provided if you need to update your code. + ### Moved: `astro check` is now an external package In Astro v2.x, [`astro check`](/en/reference/cli-reference/#astro-check) was included in Astro by default and its dependencies were bundled in Astro. This meant a larger package whether or not you ever used `astro check`. This also prevented you from having control over the version of TypeScript and the Astro Language Server to use. @@ -373,24 +389,6 @@ export default defineConfig({ }) ``` -### Changed: automatic flattening of `getStaticPaths()`'s return value - -:::note[Example needed] -Find an example of returning an array of an array -::: - -In Astro v2.x, we would magically flatten the result of `getStaticPaths()` automatically for the user, so if you returned an array of array, it would still work - -Astro v3.0 we changed this in favour of the user doing it themselves when they need to, in line with how we typically prefer for users to do explicit things. - -Removed automatic flattening of getStaticPaths result. .flatMap and .flat should now be used to ensure that you’re returning a flat array. - -#### What should I do? - -If you're returning an array of arrays instead of an array of object (as you should), please flatten it using .flat(), or if you're using a .map(), use .flatMap() instead - -A [error message indicating that `getStaticPath()`'s return value must be an array of objects](/en/reference/errors/invalid-get-static-paths-entry/#what-went-wrong) will be provided if you need to update your code. - ### Changed: default image service to Sharp instead of Squoosh In Astro v2.x, Squoosh was the default image service. From b5bead30421b1325190e7a04f0191c4e6acdd24b Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 20:38:08 +0000 Subject: [PATCH 38/58] internal API endpoints entry --- src/content/docs/en/guides/upgrade-to/v3.mdx | 28 +++++++++++++------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 81972eb3550b4..314dd84f8edaa 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -526,22 +526,32 @@ export default defineConfig({ }); ``` -### Changed entrypoint export paths +### Changed: internal Astro API entry point export paths -In Astro v2.x, you can import internal Astro APIs from `astro/internal/star` and `astro/runtime/server/star`. +In Astro v2.x, you could import internal Astro APIs from `astro/internal/*` and `astro/runtime/server/*`. -Astro v3.0 removes the two entrypoints in favour of the existing `astro/runtime/star` entrypoint. +Astro v3.0 removes the two entry points in favour of the existing `astro/runtime/*` entrypoint. Additionally, a new `astro/compiler-runtime` export has been added for compiler-specific runtime code. #### What should I do? -These are entrypoints for Astro's internal API and should not affect your project, but if you do use these entrypoints, you can migrate like below: +These are entry points for Astro's internal API and should not affect your project. But if you do use these entrypoints, update as shown below: - ```diff - - import 'astro/internal/index.js'; - + import 'astro/runtime/server/index.js'; + ```js del={1,4,10} ins={2,5,11} + import 'astro/internal/index.js'; + import 'astro/runtime/server/index.js'; - - import 'astro/server/index.js'; - + import 'astro/runtime/server/index.js'; + import 'astro/server/index.js'; + import 'astro/runtime/server/index.js'; +``` + + ```js ins={5} del={4} +import { transform } from '@astrojs/compiler'; + +const result = await transform(source, { +internalURL: 'astro/runtime/server/index.js', +internalURL: 'astro/compiler-runtime', + // ... +}); ``` From 5117ac0215e8442550f260905ec7b3f87ed48aef Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 21:02:56 +0000 Subject: [PATCH 39/58] squoosh sharp --- src/content/docs/en/guides/upgrade-to/v3.mdx | 38 +++----------------- 1 file changed, 4 insertions(+), 34 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 314dd84f8edaa..2602528ff2aa2 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -389,19 +389,15 @@ export default defineConfig({ }) ``` -### Changed: default image service to Sharp instead of Squoosh +### Changed default: Squoosh image processing service -In Astro v2.x, Squoosh was the default image service. +In Astro v2.x, Squoosh was the default image processing service. -Astro v3.0, Sharp is now the default image service. +Astro v3.0 now includes Sharp as the default image processing service, and instead provides a configuration option to use Squoosh. #### What should I do? -Sharp is now the default image service used for Astro. - -You no longer need to install the dependency locally in your project. - -Uninstall Sharp using your package manager, or by removing manually from your `package.json`. +If you had previously installed Sharp, uninstall the dependency using your package manager, or by removing manually from your `package.json`. It is now included in Astro. If you would prefer to continue to use Squoosh to transform your images, update your config with the following: @@ -463,32 +459,6 @@ if (id) { } ``` -### Added: simple asset support for Cloudflare, Deno, Vercel Edge and Netlify Edge - In Astro v2.x, using the assets feature in Cloudflare, Deno, Vercel Edge and Netlify Edge errors in runtime as the environments do not support Astro's builtin Squoosh and Sharp image optimization. - - Astro v3.0 allows these environments to work without errors, but does not perform any image transformation and processing. However, you would still get benefits, e.g. no Cumulative Layout Shift (CLS), enforced alt attribute, etc. - - What should I do? - If you previously avoided the assets feature due these constraints, you can now use them without issues. You can also use the no-op image service to explicitly opt-in to this behaviour: - - ``` - // astro.config.mjs - export default { - image: { - service: { - entrypoint: 'astro/assets/services/noop' - } - } - } - ``` - -In Astro v2.x, you would get an error log in development. When building a project, the build would fail. - -Astro V3 still displays the error log, but now you can build the project. - -When using an adapter that supports neither Squoosh or Sharp, Astro will now automatically use an image service that does not support processing, but still provides the other benefits of `astro:assets` such as enforcing `alt`, no CLS etc to users. Should be noted that it does no transformations or processing, but you still get all the other benefits (no CLS, alt enforced, etc). All of those benefits are part of the image service, if you make your own, you lose those benefits unless you make it yourself - - ### Changed: Multiple JSX framework configuration In Astro v2.x, you could use multiple JSX framework integrations (React, Solid, Preact) in the same project and Astro without having to identify which files belonged to which framework. Astro automatically scanned your components to determine which framework-specific transformations should be used, but at a performance cost. From aeecbc8a0280687eb9acc32cb253d79cb80587b7 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 21:34:43 +0000 Subject: [PATCH 40/58] HTTP request methods and more links to this point --- src/content/docs/en/guides/upgrade-to/v3.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 2602528ff2aa2..75a116aa4a807 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -240,7 +240,7 @@ const { class: className } = Astro.props; ### Removed: kebab-case transform for camelCase CSS variables -In Astro v2.x, camelCase CSS variables passed to the `style` attribute were rendered as both camelCase (as written) and kebab-case (kept for backwards compatibility). +In Astro v2.x, camelCase [CSS variables](/en/guides/styling/#css-variables) passed to the `style` attribute were rendered as both camelCase (as written) and kebab-case (kept for backwards compatibility). Astro 3.0 removes the kebab-case transform for these camelCase CSS variable names, and only the original camelCase CSS variable is rendered. @@ -277,7 +277,7 @@ If you were relying on Astro to transform kebab-case in your styles, update your Do we want an example of returning an array of an array, requiring flattening? ::: -In Astro v2.x, the return value of `getStaticPaths()` was automatically flattened to allow you to return an array of array without errors. +In Astro v2.x, the return value of [`getStaticPaths()`](/en/reference/api-reference/#getstaticpaths) was automatically flattened to allow you to return an array of array without errors. Astro v3.0 removes automatic flattening of `getStaticPaths()`'s result. @@ -302,7 +302,7 @@ Run the `astro check` command after upgrading to Astro v3.0 and follow the promp In Astro v2.x, Astro ran on port `3000` by default. -Astro v3.0 changes the default port to `4321`. 🚀 +Astro v3.0 changes the [default port](/en/reference/cli-reference/#--port-number) to `4321`. 🚀 #### What should I do? @@ -391,7 +391,7 @@ export default defineConfig({ ### Changed default: Squoosh image processing service -In Astro v2.x, Squoosh was the default image processing service. +In Astro v2.x, Squoosh was the [default image processing service](/en/guides/images/#default-image-service). Astro v3.0 now includes Sharp as the default image processing service, and instead provides a configuration option to use Squoosh. @@ -411,15 +411,15 @@ export default defineConfig({ }) ``` -### Changed: casing in function endpoints +### Changed default: HTTP request methods -In Astro v2.x, endpoints were defined using lowercase function names: `get`, `post`, `put`, `all`, and `del`. +In Astro v2.x, [HTTP request methods](/en/core-concepts/endpoints/#http-methods) were written using lowercase function names: `get`, `post`, `put`, `all`, and `del`. -Astro v3.0, uses uppercase function names. +Astro v3.0 uses uppercase function names, including `DELETE` instead of `del`. #### What should I do? -Rename functions to uppercase equivalent: +Rename all functions to their uppercase equivalent: - `get` to `GET` - `post` to `POST` @@ -427,7 +427,7 @@ Rename functions to uppercase equivalent: - `all` to `ALL` - `del` to `DELETE` -```ts title="endpoint.ts" del={1} ins={2} +```js title="endpoint.ts" del={1} ins={2} export function get() { export function GET() { return new Response(JSON.stringify({ "title": "Bob's blog" })); From 00e61238c8bdd392d473f5671582fceebc6abf76 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 21:37:28 +0000 Subject: [PATCH 41/58] shortened image service title --- src/content/docs/en/guides/upgrade-to/v3.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 75a116aa4a807..86008738e122b 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -389,7 +389,7 @@ export default defineConfig({ }) ``` -### Changed default: Squoosh image processing service +### Changed default: image service In Astro v2.x, Squoosh was the [default image processing service](/en/guides/images/#default-image-service). From cd4ef96396c344cf5f5697531caeae5ef0d68e5d Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 21:50:30 +0000 Subject: [PATCH 42/58] astro.cookies entry --- src/content/docs/en/guides/upgrade-to/v3.mdx | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 86008738e122b..587137322a54f 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -434,28 +434,25 @@ export function GET() { } ``` -### Changed: Behaviour when `Astro.cookies.get(key)` doesn't exist +### Added: `Astro.cookies.get(key)` can return `undefined` -In Astro v2.x, `Astro.cookies.get(key)` would always return a `AstroCookie` object, even if the cookie did not exist. To check for the existence you needed to use `Astro.cookies.has(key)`. +In Astro v2.x, [`Astro.cookies.get(key)`](/en/reference/api-reference/#astrocookies) would always return an [`AstroCookie` object](/en/reference/api-reference/#astrocookie), even if the cookie did not exist. To check for its existence, you needed to use `Astro.cookies.has(key)`. -Astro v3.0 `Astro.cookies.get(key)` will return `undefined` if the cookie does not exist. +Astro v3.0 returns `undefined` for `Astro.cookies.get(key)` if the cookie does not exist. #### What should I do? -This change will not break existing code that checks for the existance of the `Astro.cookie` object before using `Astro.cookies.get(key)`, but is now no longer required. You can safely remove this code. +This change will not break existing code that checks for the existance of the `Astro.cookie` object before using `Astro.cookies.get(key)`, but is now no longer required. -You can safely skip `has()` and check if the value is `undefined`: +You can safely remove any code that uses `has()` to check if the value of `Astro.cookies` is `undefined`: -```ts -// before: +```js del={1-3} ins={5-7} if (Astro.cookies.has(id)) { const id = Astro.cookies.get(id)!; } -//after: const id = Astro.cookies.get(id); if (id) { - // TypeScript knows id is an AstroCookie } ``` From 714b5cb221ffb27a3c5cc7297f0e91c72cd27383 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Sat, 19 Aug 2023 22:07:14 +0000 Subject: [PATCH 43/58] final draft done!! --- src/content/docs/en/guides/upgrade-to/v3.mdx | 52 ++++++++++---------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 587137322a54f..8369d51831045 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -411,7 +411,7 @@ export default defineConfig({ }) ``` -### Changed default: HTTP request methods +### Changed: HTTP request methods case In Astro v2.x, [HTTP request methods](/en/core-concepts/endpoints/#http-methods) were written using lowercase function names: `get`, `post`, `put`, `all`, and `del`. @@ -434,37 +434,15 @@ export function GET() { } ``` -### Added: `Astro.cookies.get(key)` can return `undefined` - -In Astro v2.x, [`Astro.cookies.get(key)`](/en/reference/api-reference/#astrocookies) would always return an [`AstroCookie` object](/en/reference/api-reference/#astrocookie), even if the cookie did not exist. To check for its existence, you needed to use `Astro.cookies.has(key)`. - -Astro v3.0 returns `undefined` for `Astro.cookies.get(key)` if the cookie does not exist. - -#### What should I do? - -This change will not break existing code that checks for the existance of the `Astro.cookie` object before using `Astro.cookies.get(key)`, but is now no longer required. - -You can safely remove any code that uses `has()` to check if the value of `Astro.cookies` is `undefined`: - -```js del={1-3} ins={5-7} -if (Astro.cookies.has(id)) { - const id = Astro.cookies.get(id)!; -} - -const id = Astro.cookies.get(id); -if (id) { -} -``` - ### Changed: Multiple JSX framework configuration -In Astro v2.x, you could use multiple JSX framework integrations (React, Solid, Preact) in the same project and Astro without having to identify which files belonged to which framework. Astro automatically scanned your components to determine which framework-specific transformations should be used, but at a performance cost. +In Astro v2.x, you could use [multiple JSX framework integrations](/en/guides/integrations-guide/#official-integrations) (React, Solid, Preact) in the same project without needing to identify which files belonged to which framework. -Astro v3.0 determines which framework to use with `include` and `exclude` integration config options where you can specify files and folders on a per-framework basis. This allows Astro to better support single-framework usage, as well as advanced features like Fast Refresh. +Astro v3.0 now requires you to specify which framework to use for your files with new `include` and `exclude` integration config options when you have multiple JSX framework integrations installed. This allows Astro to better support single-framework usage, as well as advanced features like React Fast Refresh. #### What should I do? -If you are using multiple JSX frameworks in the same project, use the `include` and/or `exclude` configuration options to specify which files belong to which framework. Provide an array of files and/or folders. Wildcards may be used to include multiple file paths. +If you are using multiple JSX frameworks in the same project, set `include` (and optionally `exclude`) to an array of files and/or folders. Wildcards may be used to include multiple file paths. We recommend placing common framework components in the same folder (e.g. `/components/react/` and `/components/solid/`) to make specifying your includes easier, but this is not required: @@ -493,6 +471,28 @@ export default defineConfig({ }); ``` +### Changed: `Astro.cookies.get(key)` can return `undefined` + +In Astro v2.x, [`Astro.cookies.get(key)`](/en/reference/api-reference/#astrocookies) would always return an [`AstroCookie` object](/en/reference/api-reference/#astrocookie), even if the cookie did not exist. To check for its existence, you needed to use `Astro.cookies.has(key)`. + +Astro v3.0 returns `undefined` for `Astro.cookies.get(key)` if the cookie does not exist. + +#### What should I do? + +This change will not break existing code that checks for the existance of the `Astro.cookie` object before using `Astro.cookies.get(key)`, but is now no longer required. + +You can safely remove any code that uses `has()` to check if the value of `Astro.cookies` is `undefined`: + +```js del={1-3} ins={5-7} +if (Astro.cookies.has(id)) { + const id = Astro.cookies.get(id)!; +} + +const id = Astro.cookies.get(id); +if (id) { +} +``` + ### Changed: internal Astro API entry point export paths In Astro v2.x, you could import internal Astro APIs from `astro/internal/*` and `astro/runtime/server/*`. From ea80c14a3ea84a7431930b1b42919d8184fbe0dd Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa <my.burning@gmail.com> Date: Mon, 21 Aug 2023 13:53:55 +0100 Subject: [PATCH 44/58] feat: document adapter features (#3917) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elian ☕️ <hello@elian.codes> Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca> --- .../docs/en/reference/adapter-reference.mdx | 190 +++++++++++++++--- 1 file changed, 163 insertions(+), 27 deletions(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index 54974665714f2..d059d5ccfbca7 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -43,44 +43,58 @@ The object passed into `setAdapter` is defined as: ```ts interface AstroAdapter { - name: string; - serverEntrypoint?: string; - exports?: string[]; + name: string; + serverEntrypoint?: string; + exports?: string[]; + adapterFeatures: AstroAdapterFeatures; supportedAstroFeatures: AstroFeatureMap; -} -export type SupportsKind = 'unsupported' | 'stable' | 'experimental' | 'deprecated'; +} -export type AstroFeatureMap = { - /** - * The adapter is able to serve static pages - */ - staticOutput?: SupportsKind; +export interface AstroAdapterFeatures { /** - * The adapter is able to serve pages that are static or rendered via server + * Creates an edge function that will communicate with the Astro middleware. */ - hybridOutput?: SupportsKind; + edgeMiddleware: boolean; /** - * The adapter is able to serve SSR pages + * SSR only. Each route becomes its own function/file. */ - serverOutput?: SupportsKind; - /** - * The adapter can emit static assets - */ - assets?: AstroAssetsFeature; + functionPerRoute: boolean; +} + +export type SupportsKind = 'unsupported' | 'stable' | 'experimental' | 'deprecated'; + +export type AstroFeatureMap = { + /** + * The adapter is able to serve static pages + */ + staticOutput?: SupportsKind; + /** + * The adapter is able to serve pages that are static or rendered via server + */ + hybridOutput?: SupportsKind; + /** + * The adapter is able to serve SSR pages + */ + serverOutput?: SupportsKind; + /** + * The adapter can emit static assets + */ + assets?: AstroAssetsFeature; }; export interface AstroAssetsFeature { - supportKind?: SupportsKind; - /** - * Whether or not this adapter deploys files in an environment that is compatible with the library `sharp` - */ - isSharpCompatible?: boolean; - /** - * Whether or not this adapter deploys files in an environment that is compatible with the library `squoosh` - */ - isSquooshCompatible?: boolean; + supportKind?: SupportsKind; + /** + * Whether this adapter deploys files in an environment that is compatible with the library `sharp` + */ + isSharpCompatible?: boolean; + /** + * Whether this adapter deploys files in an environment that is compatible with the library `squoosh` + */ + isSquooshCompatible?: boolean; } + ``` The properties are: @@ -88,6 +102,8 @@ The properties are: * __name__: A unique name for your adapter, used for logging. * __serverEntrypoint__: The entrypoint for server-side rendering. * __exports__: An array of named exports when used in conjunction with `createExports` (explained below). +* __adapterFeatures__: An object that enables specific features that must be supported by the adapter. + These features will change the built output, and the adapter must implement the proper logic to handle the different output. * __supportedAstroFeatures__: A map of Astro built-in features. This allows Astro to determine which features an adapter is unable or unwilling to support so appropriate error messages can be provided. ### Server Entrypoint @@ -278,3 +294,123 @@ and an error if the service used for assets is not compatible with the adapter: ``` [@matthewp/my-adapter] The currently selected adapter `@matthewp/my-adapter` is not compatible with the service "Sharp". Your project will NOT be able to build. ``` + +## Adapter features + +A set of features that changes the output of the emitted files. When an adapter opts in to these features, they will get additional information inside specific hooks. + +### `functionPerRoute` + +This is a feature that is enabled when using SSR only. By default, Astro emits a single `entry.mjs` file, which is responsible for emitting the rendered page on each request. + +When `functionPerRoute` is `true`, Astro will instead create a separate file for each route defined in the project. +Each file emitted will only render one page. The pages will be emitted inside a `dist/pages/` directory, and the emitted files will keep the same file paths of the `src/pages/` directory. + +Enable the feature by passing `true` to the adapter. + +```js title="my-adapter.mjs" ins={9-11} +export default function createIntegration() { + return { + name: '@matthewp/my-adapter', + hooks: { + 'astro:config:done': ({ setAdapter }) => { + setAdapter({ + name: '@matthewp/my-adapter', + serverEntrypoint: '@matthewp/my-adapter/server.js', + adapterFeatures: { + functionPerRoute: true + } + }); + }, + }, + }; +} +``` + +Then, consume the hook [`astro:build:ssr`](/en/reference/integrations-reference/#astrobuildssr), which will give you an `entryPoints` object that maps a page route to the physical file emitted after the build. + +```js title="my-adapter.mjs" ins={15-19} +export default function createIntegration() { + return { + name: '@matthewp/my-adapter', + hooks: { + 'astro:config:done': ({ setAdapter }) => { + setAdapter({ + name: '@matthewp/my-adapter', + serverEntrypoint: '@matthewp/my-adapter/server.js', + adapterFeatures: { + functionPerRoute: true + } + }); + }, + + 'astro:build:ssr': ({ entryPoints }) => { + for (const [route, entryFile] of entryPoints) { + // do something with route and entryFile + } + } + }, + }; +} +``` + +:::caution +The `entryFile` is of type `URL` and represents the physical path of the file in the file system. This means that the paths change based on the OS where the code runs. +::: + +### `edgeMiddleware` + +Defines whether any SSR middleware code will be bundled when built. + +When enabled, this prevents middleware code from being bundled and imported by all pages during the build: + +```js title="my-adapter.mjs" ins={9-11} +export default function createIntegration() { + return { + name: '@matthewp/my-adapter', + hooks: { + 'astro:config:done': ({ setAdapter }) => { + setAdapter({ + name: '@matthewp/my-adapter', + serverEntrypoint: '@matthewp/my-adapter/server.js', + adapterFeatures: { + edgeMiddleware: true + } + }); + }, + }, + }; +} +``` + +Then, consume the hook [`astro:build:ssr`](/en/reference/integrations-reference/#astrobuildssr), which will give you a `middlewareEntryPoint`, an `URL` to the physical file on the file system. + +```js title="my-adapter.mjs" ins={15-19} +export default function createIntegration() { + return { + name: '@matthewp/my-adapter', + hooks: { + 'astro:config:done': ({ setAdapter }) => { + setAdapter({ + name: '@matthewp/my-adapter', + serverEntrypoint: '@matthewp/my-adapter/server.js', + adapterFeatures: { + edgeMiddleware: true + } + }); + }, + + 'astro:build:ssr': ({ middlewareEntryPoint }) => { + // remember to check if this property exits, it will be `undefined` if the adapter doesn't opt in to the feature + if (middlewareEntryPoint) { + createEdgeMiddleware(middlewareEntryPoint) + } + } + }, + }; +} + +function createEdgeMiddleware(middlewareEntryPoint) { + // emit a new physical file using your bundler +} +``` From e58d9d9b392e44b94ed8663ea5f19cd7bdb8db65 Mon Sep 17 00:00:00 2001 From: = <otterlord.dev@gmail.com> Date: Mon, 21 Aug 2023 15:29:55 +0100 Subject: [PATCH 45/58] Update capitalisation of GET --- src/content/docs/en/guides/integrations-guide/cloudflare.mdx | 2 +- src/content/docs/en/guides/integrations-guide/netlify.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx index 0d5d4b4cf0dfa..5ca718d01f493 100644 --- a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx +++ b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx @@ -109,7 +109,7 @@ See Cloudflare's documentation for [working with environment variables](https:// ```js // pages/[id].json.js -export function get({ params }) { +export function GET({ params }) { // Access environment variables per request inside a function const serverUrl = import.meta.env.SERVER_URL; const result = await fetch(serverUrl + "/user/" + params.id); diff --git a/src/content/docs/en/guides/integrations-guide/netlify.mdx b/src/content/docs/en/guides/integrations-guide/netlify.mdx index bd5e6fd987ec5..7cd84245495bf 100644 --- a/src/content/docs/en/guides/integrations-guide/netlify.mdx +++ b/src/content/docs/en/guides/integrations-guide/netlify.mdx @@ -274,7 +274,7 @@ We check for common mime types for audio, image, and video files. To include spe import fs from 'node:fs'; -export function get() { +export function GET() { const buffer = fs.readFileSync('../image.jpg'); // Return the buffer directly, @astrojs/netlify will base64 encode the body From 873d99c93911092080a1c2788a6d249decbec4de Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Mon, 21 Aug 2023 16:56:59 -0300 Subject: [PATCH 46/58] Apply suggestions from EVERYONE's code review! Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> Co-authored-by: Kevin Zuniga Cuellar <46791833+kevinzunigacuellar@users.noreply.github.com> Co-authored-by: Bjorn Lu <bjornlu.dev@gmail.com> Co-authored-by: Erika <3019731+Princesseuh@users.noreply.github.com> Co-authored-by: Shinya Fujino <shf0811@gmail.com> --- src/content/docs/en/guides/upgrade-to/v3.mdx | 50 ++++++++++---------- 1 file changed, 26 insertions(+), 24 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 8369d51831045..dba1ae50cd648 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -80,11 +80,11 @@ See [the changelog](https://github.com/withastro/astro/blob/main/packages/astro/ Node 16 is scheduled to reach its End of Life in September 2023. -Astro v3.0 drops Node 16 support entirely, so that all Astro users can take advantage of Node's more modern features. +Astro v3.0 drops Node 16 support entirely so that all Astro users can take advantage of Node's more modern features. #### What should I do? - Check that both your development environment and your deployment environment are using **Node `18.14.1` or later**. + Check that both your development environment and your deployment environment are using **Node `18.14.1` or higher**. 1. Check your local version of Node using: @@ -92,13 +92,15 @@ Astro v3.0 drops Node 16 support entirely, so that all Astro users can take adva node -v ``` - If your local development environment needs upgrading, [install Node](https://nodejs.org/en/download/). 2. Check your [deployment environment's](/en/guides/deploy/) own documentation to verify that they support Node 18. - You can specify Node `18.14.1` for your Astro project either in a dashboard configuration setting, or a `.nvmrc` file. + You can specify Node `18.14.1` for your Astro project either in a dashboard configuration setting or a `.nvmrc` file. +```bash title=".nvmrc" +18.14.1 +``` ### Removed: Support for TypeScript 4 In Astro v2.x, the `tsconfig.json` presets include support for both TypeScript 4.x and 5.x. @@ -121,7 +123,7 @@ Astro v3.0 removes this integration from the codebase entirely. Astro's new solu #### What should I do? -Remove the `@astrojs/image` integration from your project. You will need to not only uninstall the integration, but also update or remove any import statements and existing `<Image />` and `<Picture />` components. You might also need to configure a preferred default image processing service. +Remove the `@astrojs/image` integration from your project. You will need to not only uninstall the integration but also update or remove any import statements and existing `<Image />` and `<Picture />` components. You might also need to configure a preferred default image processing service. You will find [complete, step-by-step instructions for removing the old image integration](/en/guides/images/#remove-astrojsimage) in our Images guide. @@ -141,7 +143,7 @@ export default defineConfig({ ### Removed: `<Markdown />` component -In Astro v2.x, Astro deprecated the `<Markdown />` component and moved it to an external package. +In Astro v1.x, Astro deprecated the `<Markdown />` component and moved it to an external package. Astro v3.0 completely removes the package `@astrojs/markdown-component`. Astro's `<Markdown />` component will no longer work in your project. @@ -277,7 +279,7 @@ If you were relying on Astro to transform kebab-case in your styles, update your Do we want an example of returning an array of an array, requiring flattening? ::: -In Astro v2.x, the return value of [`getStaticPaths()`](/en/reference/api-reference/#getstaticpaths) was automatically flattened to allow you to return an array of array without errors. +In Astro v2.x, the return value of [`getStaticPaths()`](/en/reference/api-reference/#getstaticpaths) was automatically flattened to allow you to return an array of arrays without errors. Astro v3.0 removes automatic flattening of `getStaticPaths()`'s result. @@ -287,9 +289,9 @@ If you're returning an array of arrays instead of an array of _objects_ (as is e An [error message indicating that `getStaticPath()`'s return value must be an array of objects](/en/reference/errors/invalid-get-static-paths-entry/#what-went-wrong) will be provided if you need to update your code. -### Moved: `astro check` is now an external package +### Moved: `astro check` now requires an external package -In Astro v2.x, [`astro check`](/en/reference/cli-reference/#astro-check) was included in Astro by default and its dependencies were bundled in Astro. This meant a larger package whether or not you ever used `astro check`. This also prevented you from having control over the version of TypeScript and the Astro Language Server to use. +In Astro v2.x, [`astro check`](/en/reference/cli-reference/#astro-check) was included in Astro by default, and its dependencies were bundled in Astro. This meant a larger package whether or not you ever used `astro check`. This also prevented you from having control over the version of TypeScript and the Astro Language Server to use. Astro v3.0 moves the `astro check` command out of Astro core and now requires an external package `@astrojs/check`. Additionally, you must install `typescript` in your project to use the `astro check` command. @@ -311,7 +313,7 @@ Update any existing references to `localhost:3000`, for example in tests or in y ### Changed default: import.meta.env.BASE_URL `trailingSlash` -In Astro v2.x, `import.meta.env.BASE_URL` appended your [`base`](/en/reference/configuration-reference/#base) setting with a [trailingSlash](/en/reference/configuration-reference/#trailingslash) by default. `trailingSlash: "ignore"`also appended a trailing slash. +In Astro v2.x, `import.meta.env.BASE_URL` appended your [`base`](/en/reference/configuration-reference/#base) setting with a [trailingSlash](/en/reference/configuration-reference/#trailingslash) by default. `trailingSlash: "ignore"` also appended a trailing slash. Astro v3.0 no longer appends `import.meta.env.BASE_URL` with a trailing slash by default, nor when `trailingSlash: "ignore"` is set. (The existing behavior of `base` in combination with `trailingSlash: "always"` or `trailingSlash: "never"` is unchanged.) @@ -319,7 +321,7 @@ Astro v3.0 no longer appends `import.meta.env.BASE_URL` with a trailing slash by If your `base` already has a trailing slash, no change is needed. -If your `base` does not have a trailing slash, add one if you wish to preserve the previous default (or `trailingSlash: "ignore"`) behaviour: +If your `base` does not have a trailing slash, add one if you wish to preserve the previous default (or `trailingSlash: "ignore"`) behavior: ```js title="astro.config.mjs" del={4} ins={5} import { defineConfig } from "astro/config"; @@ -371,7 +373,7 @@ export default defineConfig({ ### Changed default: `inlineStyleSheets` -In Astro v2.x, all project stylesheets were sent as link tags by default. You could opt in to `"always"` inlining them into `<style>` tags, or to `"auto"`matically inlining only stylesheets below a certain size by setting the [`build.inlineStylesheets`](/en/reference/configuration-reference/#buildinlinestylesheets) configuration. The default setting was `"never"`. +In Astro v2.x, all project stylesheets were sent as link tags by default. You could opt in to inlining them into `<style>` tags everytime with `"always"`, or to inlining only stylesheets below a certain size with `"auto"` by setting the [`build.inlineStylesheets`](/en/reference/configuration-reference/#buildinlinestylesheets) configuration. The default setting was `"never"`. Astro v3.0 changes the default value of `inlineStylesheets` to `"auto"`. Stylesheets smaller than `ViteConfig.build.assetsInlineLimit` (default: 4kb) are inlined by default. Otherwise, project styles are sent in external stylesheets. @@ -393,7 +395,7 @@ export default defineConfig({ In Astro v2.x, Squoosh was the [default image processing service](/en/guides/images/#default-image-service). -Astro v3.0 now includes Sharp as the default image processing service, and instead provides a configuration option to use Squoosh. +Astro v3.0 now includes Sharp as the default image processing service and instead provides a configuration option to use Squoosh. #### What should I do? @@ -479,7 +481,7 @@ Astro v3.0 returns `undefined` for `Astro.cookies.get(key)` if the cookie does n #### What should I do? -This change will not break existing code that checks for the existance of the `Astro.cookie` object before using `Astro.cookies.get(key)`, but is now no longer required. +This change will not break any code that checks for the existence of the `Astro.cookie` object before using `Astro.cookies.get(key)`, but is now no longer required. You can safely remove any code that uses `has()` to check if the value of `Astro.cookies` is `undefined`: @@ -497,29 +499,29 @@ if (id) { In Astro v2.x, you could import internal Astro APIs from `astro/internal/*` and `astro/runtime/server/*`. -Astro v3.0 removes the two entry points in favour of the existing `astro/runtime/*` entrypoint. Additionally, a new `astro/compiler-runtime` export has been added for compiler-specific runtime code. +Astro v3.0 removes the two entry points in favor of the existing `astro/runtime/*` entrypoint. Additionally, a new `astro/compiler-runtime` export has been added for compiler-specific runtime code. #### What should I do? These are entry points for Astro's internal API and should not affect your project. But if you do use these entrypoints, update as shown below: - ```js del={1,4,10} ins={2,5,11} - import 'astro/internal/index.js'; - import 'astro/runtime/server/index.js'; +```js del={1,4,10} ins={2,5,11} +import 'astro/internal/index.js'; +import 'astro/runtime/server/index.js'; - import 'astro/server/index.js'; - import 'astro/runtime/server/index.js'; +import 'astro/server/index.js'; +import 'astro/runtime/server/index.js'; ``` - ```js ins={5} del={4} +```js ins={5} del={4} import { transform } from '@astrojs/compiler'; const result = await transform(source, { -internalURL: 'astro/runtime/server/index.js', -internalURL: 'astro/compiler-runtime', + internalURL: 'astro/runtime/server/index.js', + internalURL: 'astro/compiler-runtime', // ... }); - ``` +``` From 4d76d73766b39195d8e791505e23845f886d6b69 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Mon, 21 Aug 2023 17:01:22 -0300 Subject: [PATCH 47/58] Touche, Matthew. Co-authored-by: Matthew Phillips <matthew@skypack.dev> --- src/content/docs/en/reference/integrations-reference.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 42cc5d7a98d69..e42e92c96ca8f 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -540,10 +540,10 @@ An instance of the Astro logger, useful to write logs. This logger uses the same configured via CLI. **Methods available** to write to terminal: -- `logger.info("Messsage")`; -- `logger.warn("Messsage")`; -- `logger.error("Messsage")`; -- `logger.debug("Messsage")`; +- `logger.info("Message")`; +- `logger.warn("Message")`; +- `logger.error("Message")`; +- `logger.debug("Message")`; All the messages are prepended with a label that has the same value of the integration. From 09309f3c40619f3e00233938c65526a5c5716dbb Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Mon, 21 Aug 2023 17:43:27 -0300 Subject: [PATCH 48/58] Every time someone has a good idea, we commit! Co-authored-by: J. B. Rainsberger <me@jbrains.ca> --- src/content/docs/en/guides/upgrade-to/v3.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index dba1ae50cd648..2bcbbde07d28a 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -373,7 +373,7 @@ export default defineConfig({ ### Changed default: `inlineStyleSheets` -In Astro v2.x, all project stylesheets were sent as link tags by default. You could opt in to inlining them into `<style>` tags everytime with `"always"`, or to inlining only stylesheets below a certain size with `"auto"` by setting the [`build.inlineStylesheets`](/en/reference/configuration-reference/#buildinlinestylesheets) configuration. The default setting was `"never"`. +In Astro v2.x, all project stylesheets were sent as link tags by default. You could opt in to inlining them into `<style>` tags every time with `"always"`, or to inlining only stylesheets below a certain size with `"auto"` by setting the [`build.inlineStylesheets`](/en/reference/configuration-reference/#buildinlinestylesheets) configuration. The default setting was `"never"`. Astro v3.0 changes the default value of `inlineStylesheets` to `"auto"`. Stylesheets smaller than `ViteConfig.build.assetsInlineLimit` (default: 4kb) are inlined by default. Otherwise, project styles are sent in external stylesheets. From 2f1fdf4dceed48f1cf8730a475e770286af378c0 Mon Sep 17 00:00:00 2001 From: Bjorn Lu <bjornlu.dev@gmail.com> Date: Tue, 22 Aug 2023 06:44:04 +0800 Subject: [PATCH 49/58] Document experimental JS API (#4234) Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca> --- .../docs/en/reference/cli-reference.mdx | 126 ++++++++++++++++++ 1 file changed, 126 insertions(+) diff --git a/src/content/docs/en/reference/cli-reference.mdx b/src/content/docs/en/reference/cli-reference.mdx index 79f29ba0c085c..8ec7b2ccc255c 100644 --- a/src/content/docs/en/reference/cli-reference.mdx +++ b/src/content/docs/en/reference/cli-reference.mdx @@ -373,3 +373,129 @@ Automatically opens the app in the browser on server start. ### `--help` Prints the help message and exits. + +## Advanced APIs (Experimental) + +If you need more control when running Astro, the `"astro"` package also exports APIs to programmatically run the CLI commands. + +These APIs are experimental and their API signature may change. Any updates will be mentioned in the [Astro changelog](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md) and the information below will always show the current, up-to-date information. + +### `AstroInlineConfig` + +The `AstroInlineConfig` type is used by all of the command APIs below. It extends from the user [Astro config](/en/reference/configuration-reference/) type: + +```ts +interface AstroInlineConfig extends AstroUserConfig { + configFile?: string | false; + mode?: "development" | "production"; + logLevel?: "debug" | "info" | "warn" | "error" | "silent"; +} +``` + +#### `configFile` + +<p> + +**Type:** `string | false`<br /> +**Default:** `undefined` +</p> + +A custom path to the Astro config file. + +If this value is undefined (default) or unset, Astro will search for an `astro.config.(js,mjs,ts)` file relative to the `root` and load the config file if found. + +If a relative path is set, it will resolve based on the current working directory. + +Set to `false` to disable loading any config files. + +The inline config passed in this object will take highest priority when merging with the loaded user config. + +#### `mode` + +<p> + +**Type:** `"development" | "production"`<br /> +**Default:** `"development"` when running `astro dev`, `"production"` when running `astro build` +</p> + +The mode used when building your site to generate either "development" or "production" code. + +#### `logLevel` + +<p> + +**Type:** `"debug" | "info" | "warn" | "error" | "silent"`<br /> +**Default:** `"info"` +</p> + +The logging level to filter messages logged by Astro. + +- `"debug"`: Log everything, including noisy debugging diagnostics. +- `"info"`: Log informational messages, warnings, and errors. +- `"warn"`: Log warnings and errors. +- `"error"`: Log errors only. +- `"silent"`: No logging. + +### `dev()` + +**Type:** `(inlineConfig: AstroInlineConfig) => AstroDevServer` + +Similar to [`astro dev`](#astro-dev), it runs Astro's development server. + +```js +import { dev } from "astro"; + +const devServer = await dev({ + root: "./my-project", +}); + +// Stop the server if needed +await devServer.stop(); +``` + +### `build()` + +**Type:** `(inlineConfig: AstroInlineConfig) => void` + +Similar to [`astro build`](#astro-build), it builds your site for deployment. + +```js +import { build } from "astro"; + +await build({ + root: "./my-project", +}); +``` + +### `preview()` + +**Type:** `(inlineConfig: AstroInlineConfig) => AstroPreviewServer` + +Similar to [`astro preview`](#astro-preview), it starts a local server to serve your static `dist/` directory. + +```js +import { preview } from "astro"; + +const previewServer = await preview({ + root: "./my-project", +}); + +// Stop the server if needed +await previewServer.stop(); +``` + +### `sync()` + +**Type:** `(inlineConfig: AstroInlineConfig) => number` + +Similar to [`astro sync`](#astro-sync), it generates TypeScript types for all Astro modules + +```js +import { sync } from "astro"; + +const exitCode = await sync({ + root: "./my-project", +}); + +process.exit(exitCode) +``` From 41b02504e8ddbd6519292085b28371a94154eb60 Mon Sep 17 00:00:00 2001 From: Matthew Phillips <matthew@skypack.dev> Date: Tue, 22 Aug 2023 09:27:58 -0400 Subject: [PATCH 50/58] Update Firebase example to use cookies.has() (#4302) Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca> Co-authored-by: Reuben Tier <64310361+TheOtterlord@users.noreply.github.com> --- .../docs/en/guides/backend/google-firebase.mdx | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/src/content/docs/en/guides/backend/google-firebase.mdx b/src/content/docs/en/guides/backend/google-firebase.mdx index 3a091262c7257..4509287087200 100644 --- a/src/content/docs/en/guides/backend/google-firebase.mdx +++ b/src/content/docs/en/guides/backend/google-firebase.mdx @@ -354,8 +354,8 @@ import Layout from "../layouts/Layout.astro"; /* Check if the user is authenticated */ const auth = getAuth(app); -const sessionCookie = Astro.cookies.get("session").value; -if (sessionCookie) { +if (Astro.cookies.has("session")) { + const sessionCookie = Astro.cookies.get("session").value; const decodedCookie = await auth.verifySessionCookie(sessionCookie); if (decodedCookie) { return Astro.redirect("/dashboard"); @@ -431,11 +431,10 @@ import Layout from "../layouts/Layout.astro"; const auth = getAuth(app); /* Check current session */ -const sessionCookie = Astro.cookies.get("session").value; - -if (!sessionCookie) { +if (!Astro.cookies.has("session")) { return Astro.redirect("/signin"); } +const sessionCookie = Astro.cookies.get("session").value; const decodedCookie = await auth.verifySessionCookie(sessionCookie); const user = await auth.getUser(decodedCookie.uid); @@ -473,8 +472,8 @@ import Layout from "../layouts/Layout.astro"; /* Check if the user is authenticated */ const auth = getAuth(app); -const sessionCookie = Astro.cookies.get("session").value; -if (sessionCookie) { +if (Astro.cookies.has("session")) { + const sessionCookie = Astro.cookies.get("session").value; const decodedCookie = await auth.verifySessionCookie(sessionCookie); if (decodedCookie) { return Astro.redirect("/dashboard"); From c50bba3c530ad31b1e5a7f20d13949d8dd7e43ee Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Tue, 22 Aug 2023 16:29:53 +0000 Subject: [PATCH 51/58] last new entries for upgrade guide! Code freeze! --- src/content/docs/en/guides/upgrade-to/v3.mdx | 83 ++++++++++++++++++++ 1 file changed, 83 insertions(+) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 2bcbbde07d28a..4d468c0b4694d 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -161,6 +161,57 @@ To continue using a similar `<Markdown />` component in your code, consider usin Otherwise, delete all references to importing Astro's `<Markdown />` component and the component itself in your `.astro` files. You will need to rewrite your content as HTML directly or [import Markdown](/en/guides/markdown-content/#importing-markdown) from a `.md` file. +### Removed: deprecated 1.x APIs + +In Astro v2.x, deprecated config options as well as script/style `global` and `hoist` attributes types. These were kept for backwards compatibility. + +Astro v3.0 removes these deprecated APIs entirely. They can no longer be used in your Astro project. + +#### What should I do? + +If you are continuing to use v1.x APIs, use the new APIs for each feature instead: + +- Deprecated config options: See [the 0.26 migration guide](/en/guides/upgrade-to/v1/#new-configuration-api) +- Deprecated script/style attribute types: See [the 0.26 migration guide](/en/guides/upgrade-to/v1/#new-default-script-behavior) + +### Changed: validating `image` in content collections schema + +In Astro 2.x, the content collections API deprecated an `image` export from `astro:content` for use in your content collections schemas. + +Astro 3.0 removes this export entirely. + +#### What should I do? + +If you are using the deprecated `image()` from `astro:content`, remove it as this no longer exists. Validate images through [the `image` helper from `schema`](/en/guides/images/#update-content-collections-schemas) instead: + + ```ts title="astro.config.mjs" del={1} ins={2} "({ image })" +import { defineCollection, z, image() } from "astro:content"; +import { defineCollection, z } from "astro:content"; + + defineCollection({ + schema: ({ image }) => + z.object({ + image: image(), + }), +}); +``` + +### Removed: pre-0.14 Shiki theme names + +In Astro v2.x, some Shiki theme names had been renamed, but the original names were kept for backwards compatibility. + +Astro v3.0 removes the original names in favour of the renamed theme names. + +#### What should I do? + +If your project uses any of the themes below, rename them to their updated name: + +- `material-darker` -> `material-theme-darker` +- `material-default` -> `material-theme` +- `material-lighter` -> `material-theme-lighter` +- `material-ocean` -> `material-theme-ocean` +- `material-palenight` -> `material-theme-palenight` + ### Removed: `build.excludeMiddleware` and `build.split` In Astro v2.x, `build.excludeMiddleware` and `build.split` could be used to change how specific files were emitted when using an adapter in SSR mode. @@ -300,6 +351,16 @@ Astro v3.0 moves the `astro check` command out of Astro core and now requires an Run the `astro check` command after upgrading to Astro v3.0 and follow the prompts to install the required dependencies, or manually install `@astrojs/check` and `typescript` into your project. +### Deprecated: `markdown.drafts` + +In Astro v2.x, the `markdown.drafts` configuration allowed you to have draft pages that were available in when running the dev server, but not built in production. + +Astro v3.0 deprecates this feature in favour of the content collections method of handling draft pages by filtering manually instead, which gives more control over the feature. + +#### What should I do? + +To continue to mark some pages in your project as drafts, [migrate to content collections](/en/guides/content-collections/#migrating-from-file-based-routing) and [manually filter out pages](/en/guides/content-collections/#filtering-collection-queries) with the `draft: true` frontmatter property instead. + ### Changed default: port `3000` In Astro v2.x, Astro ran on port `3000` by default. @@ -495,6 +556,28 @@ if (id) { } ``` +### Changed: running the Astro CLI programmatically + +In Astro v2.x, the `"astro"` package entrypoint exported and ran the Astro CLI directly. It is not recommended to run Astro this way in practice. + +Astro v3.0 removes the CLI from the entrypoint, and exports a new set of experimental JavaScript APIs, including `dev()`, `build()`, `preview()`, and `sync()`. + +#### What should I do? + +To [run the Astro CLI programatically](/en/reference/cli-reference/#advanced-apis-experimental), use the new experimental JavaScript APIs: + +```js +import { dev, build } from "astro"; + +// Start the Astro dev server +const devServer = await dev(); +await devServer.stop(); + +// Build your Astro project +await build(); +``` + + ### Changed: internal Astro API entry point export paths In Astro v2.x, you could import internal Astro APIs from `astro/internal/*` and `astro/runtime/server/*`. From 17a8228b94bd746dfada591a098ce66142434bb5 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Tue, 22 Aug 2023 13:40:12 -0300 Subject: [PATCH 52/58] Mostly formatting catches, also build config DEPRECATED and line highlighting Co-authored-by: Emanuele Stoppa <my.burning@gmail.com> Co-authored-by: Shinya Fujino <shf0811@gmail.com> --- src/content/docs/en/guides/upgrade-to/v3.mdx | 26 ++++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 4d468c0b4694d..358fa0cc9b05a 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -212,7 +212,7 @@ If your project uses any of the themes below, rename them to their updated name: - `material-ocean` -> `material-theme-ocean` - `material-palenight` -> `material-theme-palenight` -### Removed: `build.excludeMiddleware` and `build.split` +### Deprecated: `build.excludeMiddleware` and `build.split` In Astro v2.x, `build.excludeMiddleware` and `build.split` could be used to change how specific files were emitted when using an adapter in SSR mode. @@ -407,7 +407,7 @@ You can now remove `compressHTML: true` from your configuration as this is the n import { defineConfig } from "astro/config"; export default defineConfig({ - compressHTML: true + compressHTML: true }) ``` @@ -428,7 +428,7 @@ To retain your project's current [style scoping](/en/guides/styling/#scoped-styl import { defineConfig } from "astro/config"; export default defineConfig({ - scopedStyleStrategy: "where" + scopedStyleStrategy: "where" }) ``` @@ -509,7 +509,7 @@ If you are using multiple JSX frameworks in the same project, set `include` (and We recommend placing common framework components in the same folder (e.g. `/components/react/` and `/components/solid/`) to make specifying your includes easier, but this is not required: -```js +```js ins={13,16,19} import { defineConfig } from 'astro/config'; import preact from '@astrojs/preact'; import react from '@astrojs/react'; @@ -521,15 +521,15 @@ export default defineConfig({ // Enable many frameworks to support all different kinds of components. // No `include` is needed if you are only using a single framework! integrations: [ - preact({ - include: ['**/preact/*'] - }), - react({ - include: ['**/react/*'] - }), - solid({ - include: ['**/solid/*'], - }), + preact({ + include: ['**/preact/*'] + }), + react({ + include: ['**/react/*'] + }), + solid({ + include: ['**/solid/*'], + }), ] }); ``` From 740d821ed63d114f052dc76b6dc57f7411fa80e2 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Tue, 22 Aug 2023 13:50:23 -0300 Subject: [PATCH 53/58] missed a formatting correction Co-authored-by: Emanuele Stoppa <my.burning@gmail.com> --- src/content/docs/en/reference/adapter-reference.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index d059d5ccfbca7..6d5eb92878d6a 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -272,8 +272,8 @@ export default function createIntegration() { supportedAstroFeatures: { assets: { supportKind: "experimental", - isSharpCompatible: false, - isSquooshCompatible: false + isSharpCompatible: false, + isSquooshCompatible: false } } }); From 98f8f99248bdf8f992967091a3c210dce4bc3364 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Tue, 22 Aug 2023 16:58:04 +0000 Subject: [PATCH 54/58] moves build config options down to deprecated section --- src/content/docs/en/guides/upgrade-to/v3.mdx | 78 ++++++++++---------- 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 358fa0cc9b05a..f7311e15215d6 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -174,7 +174,7 @@ If you are continuing to use v1.x APIs, use the new APIs for each feature instea - Deprecated config options: See [the 0.26 migration guide](/en/guides/upgrade-to/v1/#new-configuration-api) - Deprecated script/style attribute types: See [the 0.26 migration guide](/en/guides/upgrade-to/v1/#new-default-script-behavior) -### Changed: validating `image` in content collections schema +### Removed: `image` from `astro:content` in content collections schema In Astro 2.x, the content collections API deprecated an `image` export from `astro:content` for use in your content collections schemas. @@ -212,44 +212,6 @@ If your project uses any of the themes below, rename them to their updated name: - `material-ocean` -> `material-theme-ocean` - `material-palenight` -> `material-theme-palenight` -### Deprecated: `build.excludeMiddleware` and `build.split` - -In Astro v2.x, `build.excludeMiddleware` and `build.split` could be used to change how specific files were emitted when using an adapter in SSR mode. - -Astro v3.0 replaces these build config options with new [SSR adapter configuration options](/en/guides/integrations-guide/#official-integrations) to perform the same tasks: `edgeMiddleware` and `functionPerRoute`. - -#### What should I do? - -Update the Astro config file to now use the new options **in the adapter configuration** directly. - -```js title="astro.config.mjs" del={5-7} ins={9} -import { defineConfig } from "astro/config"; -import vercel from "@astrojs/vercel/serverless"; - -export default defineConfig({ - build: { - excludeMiddleware: true - }, - adapter: vercel({ - edgeMiddleware: true - }), -}); -``` - -```js title="astro.config.mjs" del={5-7} ins={9} -import { defineConfig } from "astro/config"; -import netlify from "@astrojs/netlify/functions"; - -export default defineConfig({ - build: { - split: true - }, - adapter: netlify({ - functionPerRoute: true - }), -}); -``` - ### Removed: `class:list` features In Astro v2.x, the [`class:list` directive](/en/reference/directives-reference/#classlist) used a custom implementation inspired by [`clsx`](https://github.com/lukeed/clsx) with a few extra features like deduplication and `Set` support. @@ -351,6 +313,44 @@ Astro v3.0 moves the `astro check` command out of Astro core and now requires an Run the `astro check` command after upgrading to Astro v3.0 and follow the prompts to install the required dependencies, or manually install `@astrojs/check` and `typescript` into your project. +### Deprecated: `build.excludeMiddleware` and `build.split` + +In Astro v2.x, `build.excludeMiddleware` and `build.split` were used to change how specific files were emitted when using an adapter in SSR mode. + +Astro v3.0 replaces these build config options with new [SSR adapter configuration options](/en/guides/integrations-guide/#official-integrations) to perform the same tasks: `edgeMiddleware` and `functionPerRoute`. + +#### What should I do? + +Update the Astro config file to now use the new options **in the adapter configuration** directly. + +```js title="astro.config.mjs" del={5-7} ins={9} +import { defineConfig } from "astro/config"; +import vercel from "@astrojs/vercel/serverless"; + +export default defineConfig({ + build: { + excludeMiddleware: true + }, + adapter: vercel({ + edgeMiddleware: true + }), +}); +``` + +```js title="astro.config.mjs" del={5-7} ins={9} +import { defineConfig } from "astro/config"; +import netlify from "@astrojs/netlify/functions"; + +export default defineConfig({ + build: { + split: true + }, + adapter: netlify({ + functionPerRoute: true + }), +}); +``` + ### Deprecated: `markdown.drafts` In Astro v2.x, the `markdown.drafts` configuration allowed you to have draft pages that were available in when running the dev server, but not built in production. From 0412b2eab65ec6274580e213ecd59c06a7945ad7 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Wed, 23 Aug 2023 08:22:45 -0300 Subject: [PATCH 55/58] bluwy nits! Co-authored-by: Bjorn Lu <bjornlu.dev@gmail.com> --- src/content/docs/en/guides/upgrade-to/v3.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index f7311e15215d6..c55f66dcb76fb 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -163,7 +163,7 @@ Otherwise, delete all references to importing Astro's `<Markdown />` component a ### Removed: deprecated 1.x APIs -In Astro v2.x, deprecated config options as well as script/style `global` and `hoist` attributes types. These were kept for backwards compatibility. +In Astro v1.x, Astro deprecated config options as well as script/style `global` and `hoist` attributes types. These were kept for backwards compatibility. Astro v3.0 removes these deprecated APIs entirely. They can no longer be used in your Astro project. @@ -185,7 +185,7 @@ Astro 3.0 removes this export entirely. If you are using the deprecated `image()` from `astro:content`, remove it as this no longer exists. Validate images through [the `image` helper from `schema`](/en/guides/images/#update-content-collections-schemas) instead: ```ts title="astro.config.mjs" del={1} ins={2} "({ image })" -import { defineCollection, z, image() } from "astro:content"; +import { defineCollection, z, image } from "astro:content"; import { defineCollection, z } from "astro:content"; defineCollection({ From b41a7ba8e16f978478adae12c01fcda04fa33a23 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Wed, 23 Aug 2023 08:26:54 -0300 Subject: [PATCH 56/58] earlier link to image upgrade advice --- src/content/docs/en/guides/upgrade-to/v3.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index c55f66dcb76fb..fb232bd550bba 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -64,7 +64,7 @@ export default defineConfig({ These features are now available by default: - [View Transitions](/en/guides/view-transitions/) for animated page transitions and persistent islands. -- A new image services API `astro:assets` for [using images in Astro](/en/guides/images/), including a new `<Image />` component and `getImage()` function. +- A new image services API `astro:assets` for [using images in Astro](/en/guides/images/), including a new `<Image />` component and `getImage()` function. Please read the detailed [image upgrade advice](/en/guides/images/#upgrade-to-v30-from-v2x) to see how this might affect your project. Read more about these two exciting features and more in the 3.0 Blog post! From e164c3751f952e5513acc1fc5d75250c5c7efd1b Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Wed, 23 Aug 2023 11:44:56 +0000 Subject: [PATCH 57/58] upgrade node version to 18.14.1 in English files only --- src/content/docs/en/guides/deploy/netlify.mdx | 2 +- src/content/docs/en/guides/deploy/render.mdx | 2 +- src/content/docs/en/guides/deploy/vercel.mdx | 2 +- src/content/docs/en/install/auto.mdx | 2 +- src/content/docs/en/install/manual.mdx | 2 +- src/content/docs/en/tutorial/1-setup/1.mdx | 8 ++++---- 6 files changed, 9 insertions(+), 9 deletions(-) diff --git a/src/content/docs/en/guides/deploy/netlify.mdx b/src/content/docs/en/guides/deploy/netlify.mdx index 6f73c8867d865..b97096558cbb2 100644 --- a/src/content/docs/en/guides/deploy/netlify.mdx +++ b/src/content/docs/en/guides/deploy/netlify.mdx @@ -121,7 +121,7 @@ You can also create a new site on Netlify and link up your Git repository by ins ### Set a Node.js Version -If you are using a legacy [build image](https://docs.netlify.com/configure-builds/get-started/#build-image-selection) (Xenial) on Netlify, make sure that your Node.js version is set. Astro requires `v16.12.0` or higher. +If you are using a legacy [build image](https://docs.netlify.com/configure-builds/get-started/#build-image-selection) (Xenial) on Netlify, make sure that your Node.js version is set. Astro requires `v18.14.1` or higher. You can [specify your Node.js version in Netlify](https://docs.netlify.com/configure-builds/manage-dependencies/#node-js-and-javascript) using: - a [`.nvmrc`](https://github.com/nvm-sh/nvm#nvmrc) file in your base directory. diff --git a/src/content/docs/en/guides/deploy/render.mdx b/src/content/docs/en/guides/deploy/render.mdx index 98f6112bc1a33..08079057533a6 100644 --- a/src/content/docs/en/guides/deploy/render.mdx +++ b/src/content/docs/en/guides/deploy/render.mdx @@ -15,5 +15,5 @@ You can deploy your Astro project to [Render](https://render.com/), a service to 4. Give your website a name, select the branch and specify the build command and publish directory - **build command:** `npm run build` - **publish directory:** `dist` - - **Environment variables (advanced)**: By default, Render uses Node.js 14.17.0, but Astro [requires a higher version](/en/install/auto/#prerequisites). Add an environment variable with a **Variable key** of `NODE_VERSION` and a **Value** of `16.12.0` or higher to tell Render to use a compatible Node.js version. Alternatively, add a [`.node-version`](https://render.com/docs/node-version) or [`.nvmrc`](https://render.com/docs/node-version) file to your project to specify a Node.js version. + - **Environment variables (advanced)**: By default, Render uses Node.js 14.17.0, but Astro [requires a higher version](/en/install/auto/#prerequisites). Add an environment variable with a **Variable key** of `NODE_VERSION` and a **Value** of `18.14.1` or higher to tell Render to use a compatible Node.js version. Alternatively, add a [`.node-version`](https://render.com/docs/node-version) or [`.nvmrc`](https://render.com/docs/node-version) file to your project to specify a Node.js version. 5. Click the **Create Static Site** button diff --git a/src/content/docs/en/guides/deploy/vercel.mdx b/src/content/docs/en/guides/deploy/vercel.mdx index 6d92580aed19e..faa838700e13f 100644 --- a/src/content/docs/en/guides/deploy/vercel.mdx +++ b/src/content/docs/en/guides/deploy/vercel.mdx @@ -85,4 +85,4 @@ You can use `vercel.json` to override the default behavior of Vercel and to conf ### Upgrading to Astro 2.0 -Astro v2.0 drops support for Node 14, so make sure your project is using **Node `16.12.0` or later**. You can [define the Node.js version](https://vercel.com/changelog/node-js-version-now-customizable-in-the-project-settings) used during the Build Step and Serverless Functions from the General page under Project Settings. +Astro v2.0 drops support for Node 14, so make sure your project is using **Node `18.14.1` or later**. You can [define the Node.js version](https://vercel.com/changelog/node-js-version-now-customizable-in-the-project-settings) used during the Build Step and Serverless Functions from the General page under Project Settings. diff --git a/src/content/docs/en/install/auto.mdx b/src/content/docs/en/install/auto.mdx index 9247a3bd0af4f..1f196f7d2056b 100644 --- a/src/content/docs/en/install/auto.mdx +++ b/src/content/docs/en/install/auto.mdx @@ -13,7 +13,7 @@ Read our [step-by-step manual installation guide](/en/install/manual/) instead. ::: #### Prerequisites -- **Node.js** - `v16.12.0` or higher. +- **Node.js** - `v18.14.1` or higher. - **Text editor** - We recommend [VS Code](https://code.visualstudio.com/) with our [Official Astro extension](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode). - **Terminal** - Astro is accessed through its command-line interface (CLI). diff --git a/src/content/docs/en/install/manual.mdx b/src/content/docs/en/install/manual.mdx index d6a6ebd909536..af3b88279a5aa 100644 --- a/src/content/docs/en/install/manual.mdx +++ b/src/content/docs/en/install/manual.mdx @@ -16,7 +16,7 @@ This guide will walk you through the steps to manually install and configure a n #### Prerequisites -- **Node.js** - `v16.12.0` or higher. +- **Node.js** - `v18.14.1` or higher. - **Text editor** - We recommend [VS Code](https://code.visualstudio.com/) with our [Official Astro extension](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode). - **Terminal** - Astro is accessed through its command-line interface (CLI). diff --git a/src/content/docs/en/tutorial/1-setup/1.mdx b/src/content/docs/en/tutorial/1-setup/1.mdx index 18c22ec86899f..2646b204706d0 100644 --- a/src/content/docs/en/tutorial/1-setup/1.mdx +++ b/src/content/docs/en/tutorial/1-setup/1.mdx @@ -29,7 +29,7 @@ You can access the command line through a local terminal program for your operat ### Node.js -For Astro to run on your system, you will also need to have [**Node.js**](https://nodejs.org/en/) installed, version `v16.12.0` or later. +For Astro to run on your system, you will also need to have [**Node.js**](https://nodejs.org/en/) installed, version `v18.14.1` or later. To check to see whether you already have a compatible version installed, run the following command in your terminal: @@ -37,12 +37,12 @@ To check to see whether you already have a compatible version installed, run the node -v // Example output -v16.14.0 +v18.14.1 ``` -If the command returns a version number higher than `v16.12.0`, you're good to go! +If the command returns a version number higher than `v18.14.1`, you're good to go! -If the command returns an error message like `Command 'node' not found`, or a version number lower than `v16.12.0`, then you need to [install a compatible Node.js version](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). +If the command returns an error message like `Command 'node' not found`, or a version number lower than `v18.14.1`, then you need to [install a compatible Node.js version](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). ### Code Editor From f71a9398ffdc2094f0b230898b0e3b27627ef3f4 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <sarah@rainsberger.ca> Date: Wed, 23 Aug 2023 12:28:42 +0000 Subject: [PATCH 58/58] removed examples that listed astrojs/image --- src/content/docs/en/concepts/why-astro.mdx | 2 +- src/content/docs/en/guides/integrations-guide.mdx | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/content/docs/en/concepts/why-astro.mdx b/src/content/docs/en/concepts/why-astro.mdx index 169178283e93a..759ba2f542478 100644 --- a/src/content/docs/en/concepts/why-astro.mdx +++ b/src/content/docs/en/concepts/why-astro.mdx @@ -75,6 +75,6 @@ One of our favorite sayings is: **opt-in to complexity.** We designed Astro to r **Astro is an all-in-one web framework that comes with everything you need to build a website.** Astro includes a component syntax, file-based routing, asset handling, a build process, bundling, optimizations, data-fetching, and more. You can build great websites without ever reaching outside of Astro's core feature set. -If you need more control, you can extend Astro with over [100+ integrations](https://astro.build/integrations/) like [React](https://www.npmjs.com/package/@astrojs/react), [Svelte](https://www.npmjs.com/package/@astrojs/svelte), [Vue](https://www.npmjs.com/package/@astrojs/vue), [Tailwind CSS](https://www.npmjs.com/package/@astrojs/tailwind), [MDX](https://www.npmjs.com/package/@astrojs/mdx), [image optimizations](https://www.npmjs.com/package/@astrojs/image), and more. [Connect your favorite CMS](/en/guides/cms/) or [deploy to your favorite host](/en/guides/deploy/) with just a single command. +If you need more control, you can extend Astro with over [100+ integrations](https://astro.build/integrations/) like [React](https://www.npmjs.com/package/@astrojs/react), [Svelte](https://www.npmjs.com/package/@astrojs/svelte), [Vue](https://www.npmjs.com/package/@astrojs/vue), [Tailwind CSS](https://www.npmjs.com/package/@astrojs/tailwind), [MDX](https://www.npmjs.com/package/@astrojs/mdx), and more. [Connect your favorite CMS](/en/guides/cms/) or [deploy to your favorite host](/en/guides/deploy/) with just a single command. Astro is UI-agnostic, meaning you can **Bring Your Own UI Framework (BYOF)**. React, Preact, Solid, Svelte, Vue, and Lit are all officially supported in Astro. You can even mix and match different frameworks on the same page, making future migrations easier and preventing project lock-in to a single framework. diff --git a/src/content/docs/en/guides/integrations-guide.mdx b/src/content/docs/en/guides/integrations-guide.mdx index 2a512ca2dd279..6244689988ce2 100644 --- a/src/content/docs/en/guides/integrations-guide.mdx +++ b/src/content/docs/en/guides/integrations-guide.mdx @@ -126,17 +126,17 @@ To remove an integration, first uninstall the integration from your project <PackageManagerTabs> <Fragment slot="npm"> ```shell - npm uninstall @astrojs/image + npm uninstall @astrojs/react ``` </Fragment> <Fragment slot="pnpm"> ```shell - pnpm uninstall @astrojs/image + pnpm uninstall @astrojs/react ``` </Fragment> <Fragment slot="yarn"> ```shell - yarn remove @astrojs/image + yarn remove @astrojs/react ``` </Fragment> </PackageManagerTabs> @@ -146,11 +146,11 @@ Next, remove the integration from your `astro.config.*` file: ```js title="astro.config.mjs" del={3,7} import { defineConfig } from 'astro/config' -import image from "@astrojs/image"; +import image from "@astrojs/react"; export default defineConfig({ integrations: [ - image() + react() ] }) ```