From 0ec0ee07756cd82a5979a88549c21318cad39f0a Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Thu, 23 Nov 2023 14:41:04 +0000 Subject: [PATCH 01/13] Co-authored-by: HiDeoo Co-authored-by: Elian Co-authored-by: Kevin Zuniga Cuellar Co-authored-by: Atharva Pise Co-authored-by: Paul Valladares Co-authored-by: Reuben Tier --- src/content/docs/en/guides/upgrade-to/v4.mdx | 120 +++++++++++++++++++ src/i18n/en/nav.ts | 2 +- 2 files changed, 121 insertions(+), 1 deletion(-) create mode 100644 src/content/docs/en/guides/upgrade-to/v4.mdx diff --git a/src/content/docs/en/guides/upgrade-to/v4.mdx b/src/content/docs/en/guides/upgrade-to/v4.mdx new file mode 100644 index 0000000000000..58de55ca95c65 --- /dev/null +++ b/src/content/docs/en/guides/upgrade-to/v4.mdx @@ -0,0 +1,120 @@ +--- +title: Upgrade to Astro v4 +description: How to upgrade your project to the latest version of Astro (v4.0). +i18nReady: false +--- +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import FileTree from '~/components/FileTree.astro' + +This guide will help you migrate from Astro v3 to Astro v4. + +Need to upgrade an older project to v3? See our [older migration guide](/en/guides/upgrade-to/v3/). + +Need to see the v3 docs? Visit this older version of the docs site (unmaintained) (random deploy preview lol) + +## 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 v4.x + npm install astro@latest + + # Example: upgrade React and Tailwind integrations + npm install @astrojs/react@latest @astrojs/tailwind@latest + ``` + + + ```shell + # Upgrade to Astro v4.x + pnpm add astro@latest + + # Example: upgrade React and Tailwind integrations + pnpm add @astrojs/react@latest @astrojs/tailwind@latest + ``` + + + ```shell + # Upgrade to Astro v4.x + yarn add astro@latest + + # Example: upgrade React and Tailwind integrations + yarn add @astrojs/react@latest @astrojs/tailwind@latest + ``` + + + +:::note[Need to continue?] +After upgrading Astro to the latest version, you may not need to make any changes to your project at all! + +But, if you notice errors or unexpected behavior, please check below for what has changed that might need updating in your project. +::: + +## Astro v4.0 Experimental Flags Removed + +Remove the following experimental flags from `astro.config.mjs`: + +```js del={6} +// astro.config.mjs +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + experimental: { + // nothing here yet @TODO: check if needed + }, +}) +``` + +These features are now available by default: + +- +- + +Read more about these two exciting features and more in [the 4.0 Blog post](https://astro.build/blog/astro-4/)! + +## Astro v4.0 Breaking Changes + +Astro v4.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 v4.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. + +### Upgraded: Vite 5.0 + +In Astro v3.0, Vite 4 was used as the development server and production bundler. + +Astro v4.0 upgrades from Vite 4 to Vite 5. + +#### What should I do? + +If you are using Vite-specific plugins, configuration or APIs, check the [Vite migration guide](https://vitejs.dev/guide/migration) for their breaking changes and upgrade your project as needed. There are no breaking changes to Astro itself. + +### Updated: unified, remark, and rehype dependencies + +In Astro v3.x, unified v10 and its related compatible remark/rehype packages were used to process Markdown and MDX. + +Astro v4.0 upgrades [unified to v11](https://github.com/unifiedjs/unified/releases/tag/11.0.0) and the other remark/rehype packages to latest. + +#### What should I do? + +If you used custom remark/rehype packages, update all of them to latest using your package manager to ensure they support unified v11. The packages you are using can be found in `astro.config.mjs`. There should not be any significant breaking changes if you use actively-updated packages, but some packages may not yet be compatible with unified v11. +Visually inspect your Markdown/MDX pages before deploying to ensure your site is functioning as intended. + +### Renamed: `entrypoint` (Integrations API) + +In Astro v3.x, the property of the `injectRoute` integrations API that specified the route entry point was named `entryPoint`. + +Astro v4.0 renames this property to `entrypoint` to be consistent with other Astro APIs. The `entryPoint` property is deprecated, but will continue to work and logs a warning prompting you to update your code. + +#### What should I do? + +If you have integrations that use the `injectRoute` API, rename the `entryPoint` property to `entrypoint`. If you're a library author who wants to support both Astro 3 and 4, you can specify both `entryPoint` and `entrypoint`, in which case, a warning will not be logged. + +## Community Resources + +Know a good resource for Astro v4.0? [Edit this page](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/upgrade-to/v4.mdx) and add a link below! + +## Known Issues + +There are currently no known issues. \ No newline at end of file diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts index 3a534bf6a372e..e5f2fb93b556c 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 v3', slug: 'guides/upgrade-to/v3', key: 'guides/upgrade-to/v3' }, + { text: 'Upgrade to v4', slug: 'guides/upgrade-to/v4', key: 'guides/upgrade-to/v4' }, { text: 'Core Concepts', header: true, type: 'learn', key: 'coreConcepts' }, { text: 'Why Astro', slug: 'concepts/why-astro', key: 'concepts/why-astro' }, From b2b00c63478ad7881af444bf3faffc89584de1a6 Mon Sep 17 00:00:00 2001 From: Elian Date: Thu, 30 Nov 2023 15:04:26 +0000 Subject: [PATCH 02/13] update with latest breaking changes Co-authored-by: HiDeoo Co-authored-by: Sarah Rainsberger Co-authored-by: Reuben Tier Co-authored-by: Genteure Co-authored-by: Atharva Pise Co-authored-by: Kevin Zuniga Cuellar --- src/content/docs/en/guides/upgrade-to/v4.mdx | 133 ++++++++++++++++--- 1 file changed, 116 insertions(+), 17 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v4.mdx b/src/content/docs/en/guides/upgrade-to/v4.mdx index 58de55ca95c65..23f8edc9ebb9a 100644 --- a/src/content/docs/en/guides/upgrade-to/v4.mdx +++ b/src/content/docs/en/guides/upgrade-to/v4.mdx @@ -14,38 +14,33 @@ Need to see the v3 docs? Visit this older version of the docs site (unmaintained ## 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. +Update your project's version of Astro and all official integrations to the latest versions using your package manager. ```shell - # Upgrade to Astro v4.x - npm install astro@latest - - # Example: upgrade React and Tailwind integrations - npm install @astrojs/react@latest @astrojs/tailwind@latest + # Upgrade Astro and official integrations together + npx @astrojs/upgrade ``` ```shell - # Upgrade to Astro v4.x - pnpm add astro@latest - - # Example: upgrade React and Tailwind integrations - pnpm add @astrojs/react@latest @astrojs/tailwind@latest + # Upgrade Astro and official integrations together + pnpm dlx @astrojs/upgrade ``` ```shell - # Upgrade to Astro v4.x - yarn add astro@latest - - # Example: upgrade React and Tailwind integrations - yarn add @astrojs/react@latest @astrojs/tailwind@latest + # Upgrade Astro and official integrations together + yarn dlx @astrojs/upgrade ``` + +You can also [upgrade your Astro integrations manually](/en/guides/integrations-guide/#manual-upgrading) if needed, and you may also need to upgrade other dependencies in your project. + + :::note[Need to continue?] After upgrading Astro to the latest version, you may not need to make any changes to your project at all! @@ -111,10 +106,114 @@ Astro v4.0 renames this property to `entrypoint` to be consistent with other Ast If you have integrations that use the `injectRoute` API, rename the `entryPoint` property to `entrypoint`. If you're a library author who wants to support both Astro 3 and 4, you can specify both `entryPoint` and `entrypoint`, in which case, a warning will not be logged. +### Removed: Support for simple objects in endpoints + +In Astro v3.x, returning simple objects from endpoints was deprecated, but was still supported to maintain compatibility with Astro v2. A `ResponseWithEncoding` utility was also provided to ease the migration. + +Astro v4.0 removes support for simple objects and requires endpoints to always return a `Response`. The `ResponseWithEncoding` utility is also removed in favor of a proper `Response` type. + +#### What should I do? + +Update your endpoints to return a `Response` object directly. + +```diff lang="ts" + export async function GET() { +- return { body: { "title": "Bob's blog" }}; ++ return new Response(JSON.stringify({ "title": "Bob's blog" })); + } +``` + +To remove usage of `ResponseWithEncoding`, refactor your code to use an `ArrayBuffer` instead: + +```diff lang="ts" + export async function GET() { + const file = await fs.readFile('./bob.png'); +- return new ResponseWithEncoding(file.toString('binary'), undefined, 'binary'); ++ return new Response(file.buffer); + } +``` + +### Removed: Shiki language `path` property support + +In Astro v3.x, a Shiki language passed to `markdown.shikiConfig.langs` will be automatically converted to a Shikiji-compatible language. Shikiji is the internal tooling used by Astro for syntax highlighting. + +Astro v4.0 removes partial compatibility support for the `path` property of a Shiki language. This `path` property used to resolve from `/node_modules/astro` which can be confusing to configure, hence its support is removed. + +#### What should I do? + +The language JSON file should be imported and passed to the option instead. + +```diff lang="js" +// astro.config.js ++ import customLang from './custom.tmLanguage.json' + +export default defineConfig({ + markdown: { + shikiConfig: { + langs: [ +- { path: '../../custom.tmLanguage.json' }, ++ customLang, + ], + }, + }, +}) +``` + +### Changed: `app.render` signature in Integrations API + +In Astro v3.0, the `app.render()` method accepted `routeData` and `locals` as separate optional arguments. + +Astro v4.0 changes the `app.render()` signature. It's second argument is now a single optional object with two optional properties: `routeData` and `locals`. + +#### What should I do? + +If you are maintaining an adapter, the current signature will continue to work until the next major version. To migrate to the new signature, pass `routeData` and `locals` as properties of an object instead of as multiple independent arguments. + +```diff lang="js" +- app.render(request, routeData, locals) ++ app.render(request, { routeData, locals }) +``` + +### Added: `astro preferences` to the CLI + +Astro v4.0 adds the `astro preferences` command to manage user preferences. User preferences are specific to individual Astro users, unlike the `astro.config.mjs` file which changes behavior for everyone working on a project. + +#### What should I do? + +In order to disable the new [dev overlay](/en/reference/dev-overlay-plugin-reference/) for the current Astro project, run the following command: + +```shell +astro preferences disable devOverlay +``` + +In order to disable the dev overlay for every project on your machine, run the following command: + +```shell +astro preferences --global disable devOverlay +``` + +In order to re-enable the dev overlay, run the following command: + +```shell +astro preferences enable devOverlay +``` + +### Changed: View Transitions will handle submit `events` by default + +In Astro v3.x, projects using the `` component were required to opt-in to handling `submit` events for `form` elements. This was done by passing a `handleForms` prop. + +Astro v4.0 handles `submit` events for `form` elements by default when `` are used. The `handleForms` prop has been deprecated and no longer has any effect. + +#### What should I do? + +Remove the `handleForms` property from your `ViewTransitions` component. + +To opt-out of `submit` event handling, add the `data-astro-reload` attribute to relevant `form` elements. + ## Community Resources Know a good resource for Astro v4.0? [Edit this page](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/upgrade-to/v4.mdx) and add a link below! ## Known Issues -There are currently no known issues. \ No newline at end of file +There are currently no known issues. From 2b73e8ab6d9a085aa77ac2df16204d2bceedc262 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Thu, 30 Nov 2023 22:56:50 +0000 Subject: [PATCH 03/13] text edits and added deprecations --- src/content/docs/en/guides/upgrade-to/v4.mdx | 114 ++++++++++++++----- 1 file changed, 84 insertions(+), 30 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v4.mdx b/src/content/docs/en/guides/upgrade-to/v4.mdx index 23f8edc9ebb9a..0a580427d9218 100644 --- a/src/content/docs/en/guides/upgrade-to/v4.mdx +++ b/src/content/docs/en/guides/upgrade-to/v4.mdx @@ -69,12 +69,16 @@ These features are now available by default: Read more about these two exciting features and more in [the 4.0 Blog post](https://astro.build/blog/astro-4/)! -## Astro v4.0 Breaking Changes +## Breaking Changes -Astro v4.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 v4.0, check this guide for an overview of all breaking changes and instructions on how to update your codebase. +Astro v4.0 includes some potentially breaking changes, as well as the removal of some previously deprecated features. + +If your project doesn't work as expected after upgrading to v4.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. +## Upgrades/Updates + ### Upgraded: Vite 5.0 In Astro v3.0, Vite 4 was used as the development server and production bundler. @@ -93,9 +97,13 @@ Astro v4.0 upgrades [unified to v11](https://github.com/unifiedjs/unified/releas #### What should I do? -If you used custom remark/rehype packages, update all of them to latest using your package manager to ensure they support unified v11. The packages you are using can be found in `astro.config.mjs`. There should not be any significant breaking changes if you use actively-updated packages, but some packages may not yet be compatible with unified v11. +If you used custom remark/rehype packages, update all of them to latest using your package manager to ensure they support unified v11. The packages you are using can be found in `astro.config.mjs`. + +There should not be any significant breaking changes if you use actively-updated packages, but some packages may not yet be compatible with unified v11. Visually inspect your Markdown/MDX pages before deploying to ensure your site is functioning as intended. +## Renamed/Changed + ### Renamed: `entrypoint` (Integrations API) In Astro v3.x, the property of the `injectRoute` integrations API that specified the route entry point was named `entryPoint`. @@ -106,7 +114,33 @@ Astro v4.0 renames this property to `entrypoint` to be consistent with other Ast If you have integrations that use the `injectRoute` API, rename the `entryPoint` property to `entrypoint`. If you're a library author who wants to support both Astro 3 and 4, you can specify both `entryPoint` and `entrypoint`, in which case, a warning will not be logged. -### Removed: Support for simple objects in endpoints +### Changed: `app.render` signature in Integrations API + +In Astro v3.0, the `app.render()` method accepted `routeData` and `locals` as separate, optional arguments. + +Astro v4.0 changes the `app.render()` signature. These two properties are now available in a single object. Both the object and these two properties are still optional. + +#### What should I do? + +If you are maintaining an adapter, the current signature will continue to work until the next major version. To migrate to the new signature, pass `routeData` and `locals` as properties of an object instead of as multiple independent arguments. + +```diff lang="js" +- app.render(request, routeData, locals) ++ app.render(request, { routeData, locals }) +``` +### Changed: adapters must now specify supported features + +In Astro v3.x, adapters were not required to specify the features they support. + +Astro 4.0 requires adapters to pass an `supportedAstroFeatures` property to specify a list of features they support. + +#### What should I do? + +Adapter authors need to pass the `supportedAstroFeatures` option to specify a list of features they support. If this was not set before, you can pass `supportedAstroFeatures: {}`. + +## Removed + +### Removed: returning simple objects from endpoints In Astro v3.x, returning simple objects from endpoints was deprecated, but was still supported to maintain compatibility with Astro v2. A `ResponseWithEncoding` utility was also provided to ease the migration. @@ -133,11 +167,11 @@ To remove usage of `ResponseWithEncoding`, refactor your code to use an `ArrayBu } ``` -### Removed: Shiki language `path` property support +### Removed: Shiki language `path` property -In Astro v3.x, a Shiki language passed to `markdown.shikiConfig.langs` will be automatically converted to a Shikiji-compatible language. Shikiji is the internal tooling used by Astro for syntax highlighting. +In Astro v3.x, a Shiki language passed to `markdown.shikiConfig.langs` was automatically converted to a Shikiji-compatible language. Shikiji is the internal tooling used by Astro for syntax highlighting. -Astro v4.0 removes partial compatibility support for the `path` property of a Shiki language. This `path` property used to resolve from `/node_modules/astro` which can be confusing to configure, hence its support is removed. +Astro v4.0 removes support for the `path` property of a Shiki language, which was confusing to configure. It is replaced by an import which can be passed to `langs` directly. #### What should I do? @@ -159,46 +193,56 @@ export default defineConfig({ }) ``` -### Changed: `app.render` signature in Integrations API +### Removed: `build.split` and `build.excludeMiddleware` -In Astro v3.0, the `app.render()` method accepted `routeData` and `locals` as separate optional arguments. +In Astro 3.0, `build.split` and `build.excludeMiddleware` were deprecated. -Astro v4.0 changes the `app.render()` signature. It's second argument is now a single optional object with two optional properties: `routeData` and `locals`. +Astro 4.0 removes these properties entirely. #### What should I do? -If you are maintaining an adapter, the current signature will continue to work until the next major version. To migrate to the new signature, pass `routeData` and `locals` as properties of an object instead of as multiple independent arguments. +If you are using the deprecated `build.split` or `build.excludeMiddleware`, you must now remove them as these no longer exist. -```diff lang="js" -- app.render(request, routeData, locals) -+ app.render(request, { routeData, locals }) -``` +Please see the v3 migration guide to [update these deprecated middleware properties](/en/guides/upgrade-to/v3/#deprecated-buildexcludemiddleware-and-buildsplit) with adapter configurations. -### Added: `astro preferences` to the CLI +### Removed: `markdown.drafts` -Astro v4.0 adds the `astro preferences` command to manage user preferences. User preferences are specific to individual Astro users, unlike the `astro.config.mjs` file which changes behavior for everyone working on a project. +In Astro 3.0, using `markdown.drafts` to control the building of draft posts was deprecated. + +Astro 4.0 removes this option entirely. #### What should I do? -In order to disable the new [dev overlay](/en/reference/dev-overlay-plugin-reference/) for the current Astro project, run the following command: +If you are using the deprecated `markdown.drafts`, you must now remove it as it no longer exist. -```shell -astro preferences disable devOverlay -``` +Please see the v3 migration guide to [upgrade to content collections to filter draft posts before building](en/guides/upgrade-to/v3/#deprecated-markdowndrafts). -In order to disable the dev overlay for every project on your machine, run the following command: +### Removed: `getHeaders()` -```shell -astro preferences --global disable devOverlay -``` +In Astro 3.0, the `getHeaders()` Markdown export was deprecated and replaced with `getHeadings()`. -In order to re-enable the dev overlay, run the following command: +Astro 4.0 removes this option entirely. -```shell -astro preferences enable devOverlay -``` +#### What should I do? + +If you are using the deprecated `getHeaders()`, you must now remove it as it no longer exists. Replace any instances with `getHeadings()`. + + +### Removed: lowercase HTTP method names + +In Astro 3.0, using lowercase HTTP request method names (`get`, `post`, `put`, `all`, `del`) was deprecated. -### Changed: View Transitions will handle submit `events` by default +Astro 4.0 removes support for lowercase names entirely. All HTTP request methods must now be written using uppercase. + +#### What should I do? + +If you are using the deprecated lowercase names, you must now replace them with their uppercase equivalents. + +Please see the v3 migration guide [for guidance using uppercase HTTP request methods](/en/guides/upgrade-to/v3/#changed-http-request-methods-case). + +## Deprecated + +### Deprecated: `handleForms` for View Transitions submit `events` In Astro v3.x, projects using the `` component were required to opt-in to handling `submit` events for `form` elements. This was done by passing a `handleForms` prop. @@ -210,6 +254,16 @@ Remove the `handleForms` property from your `ViewTransitions` component. To opt-out of `submit` event handling, add the `data-astro-reload` attribute to relevant `form` elements. +```astro title="src/components/Form.astro" +
+ +
+``` + + + + + ## Community Resources Know a good resource for Astro v4.0? [Edit this page](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/upgrade-to/v4.mdx) and add a link below! From 44f4ee2d8f7ca1639a29c6031c0b4ad9c2162abc Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Thu, 30 Nov 2023 23:05:44 +0000 Subject: [PATCH 04/13] fix link --- src/content/docs/en/guides/upgrade-to/v4.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v4.mdx b/src/content/docs/en/guides/upgrade-to/v4.mdx index 0a580427d9218..673b155986358 100644 --- a/src/content/docs/en/guides/upgrade-to/v4.mdx +++ b/src/content/docs/en/guides/upgrade-to/v4.mdx @@ -215,7 +215,7 @@ Astro 4.0 removes this option entirely. If you are using the deprecated `markdown.drafts`, you must now remove it as it no longer exist. -Please see the v3 migration guide to [upgrade to content collections to filter draft posts before building](en/guides/upgrade-to/v3/#deprecated-markdowndrafts). +Please see the v3 migration guide to [upgrade to content collections to filter draft posts before building](/en/guides/upgrade-to/v3/#deprecated-markdowndrafts). ### Removed: `getHeaders()` From 29b92dd1f456c2df26245108d016cdc85226b017 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sat, 2 Dec 2023 15:57:47 +0000 Subject: [PATCH 05/13] good enough to merge? --- src/content/docs/en/guides/upgrade-to/v4.mdx | 229 ++++++++++++++----- 1 file changed, 171 insertions(+), 58 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v4.mdx b/src/content/docs/en/guides/upgrade-to/v4.mdx index 673b155986358..045fd65e9f8eb 100644 --- a/src/content/docs/en/guides/upgrade-to/v4.mdx +++ b/src/content/docs/en/guides/upgrade-to/v4.mdx @@ -10,7 +10,7 @@ This guide will help you migrate from Astro v3 to Astro v4. Need to upgrade an older project to v3? See our [older migration guide](/en/guides/upgrade-to/v3/). -Need to see the v3 docs? Visit this older version of the docs site (unmaintained) (random deploy preview lol) +Need to see the v3 docs? Visit this older version of the docs site (unmaintained). ## Upgrade Astro @@ -47,6 +47,12 @@ After upgrading Astro to the latest version, you may not need to make any change But, if you notice errors or unexpected behavior, please check below for what has changed that might need updating in your project. ::: +Astro v4.0 includes [potentially breaking changes](/en/guides/upgrade-to/v4/#breaking-changes), as well as the [removal of some previously deprecated features](/en/guides/upgrade-to/v4/#previously-deprecated-features-now-removed). + +If your project doesn't work as expected after upgrading to v4.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. + ## Astro v4.0 Experimental Flags Removed Remove the following experimental flags from `astro.config.mjs`: @@ -69,15 +75,9 @@ These features are now available by default: Read more about these two exciting features and more in [the 4.0 Blog post](https://astro.build/blog/astro-4/)! -## Breaking Changes - -Astro v4.0 includes some potentially breaking changes, as well as the removal of some previously deprecated features. - -If your project doesn't work as expected after upgrading to v4.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. +## Upgrades -## Upgrades/Updates +Any major upgrades to Astro's dependencies may cause breaking changes in your project. ### Upgraded: Vite 5.0 @@ -89,7 +89,7 @@ Astro v4.0 upgrades from Vite 4 to Vite 5. If you are using Vite-specific plugins, configuration or APIs, check the [Vite migration guide](https://vitejs.dev/guide/migration) for their breaking changes and upgrade your project as needed. There are no breaking changes to Astro itself. -### Updated: unified, remark, and rehype dependencies +### Upgraded: unified, remark, and rehype dependencies In Astro v3.x, unified v10 and its related compatible remark/rehype packages were used to process Markdown and MDX. @@ -102,7 +102,11 @@ If you used custom remark/rehype packages, update all of them to latest using yo There should not be any significant breaking changes if you use actively-updated packages, but some packages may not yet be compatible with unified v11. Visually inspect your Markdown/MDX pages before deploying to ensure your site is functioning as intended. -## Renamed/Changed +## Breaking Changes + +The following changes are considered breaking changes in Astro. Breaking changes may or may not provide temporary backwards compatibility, and all documentation is updated to refer to only the current, supported code. + +If you need to refer to documentation for a v3.x project, you can browse this (unmaintained) version of the docs from before 4.0 was released. ### Renamed: `entrypoint` (Integrations API) @@ -114,6 +118,14 @@ Astro v4.0 renames this property to `entrypoint` to be consistent with other Ast If you have integrations that use the `injectRoute` API, rename the `entryPoint` property to `entrypoint`. If you're a library author who wants to support both Astro 3 and 4, you can specify both `entryPoint` and `entrypoint`, in which case, a warning will not be logged. +```js ins={4} del={3} +injectRoute({ + pattern: '/fancy-dashboard', + entryPoint: '@fancy/dashboard/dashboard.astro' + entrypoint: '@fancy/dashboard/dashboard.astro' +}); +``` + ### Changed: `app.render` signature in Integrations API In Astro v3.0, the `app.render()` method accepted `routeData` and `locals` as separate, optional arguments. @@ -132,13 +144,100 @@ If you are maintaining an adapter, the current signature will continue to work u In Astro v3.x, adapters were not required to specify the features they support. -Astro 4.0 requires adapters to pass an `supportedAstroFeatures` property to specify a list of features they support. +Astro 4.0 requires adapters to pass the `supportedAstroFeatures{}` property to specify a list of features they support. This property is no longer optional. #### What should I do? -Adapter authors need to pass the `supportedAstroFeatures` option to specify a list of features they support. If this was not set before, you can pass `supportedAstroFeatures: {}`. +Adapter authors need to pass the `supportedAstroFeatures{}` option to specify a list of features they support. + +```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', + supportedAstroFeatures: { + staticOutput: 'stable' + } + }); + }, + }, + }; +} +``` + +### Removed: Shiki language `path` property + +In Astro v3.x, a Shiki language passed to `markdown.shikiConfig.langs` was automatically converted to a Shikiji-compatible language. Shikiji is the internal tooling used by Astro for syntax highlighting. + +Astro v4.0 removes support for the `path` property of a Shiki language, which was confusing to configure. It is replaced by an import which can be passed to `langs` directly. + +#### What should I do? + +The language JSON file should be imported and passed to the option instead. + +```diff lang="js" +// astro.config.js ++ import customLang from './custom.tmLanguage.json' + +export default defineConfig({ + markdown: { + shikiConfig: { + langs: [ +- { path: '../../custom.tmLanguage.json' }, ++ customLang, + ], + }, + }, +}) +``` + +## Deprecated + +The following deprecated features are no longer supported and are no longer documented. Please update your project accordingly. + +Some deprecated features may temporarily continue to function until they are completely removed. Others may silently have no effect, or throw an error prompting you to update your code. + +### Deprecated: `handleForms` for View Transitions submit `events` + +In Astro v3.x, projects using the `` component were required to opt-in to handling `submit` events for `form` elements. This was done by passing a `handleForms` prop. + +Astro v4.0 handles `submit` events for `form` elements by default when `` are used. The `handleForms` prop has been deprecated and no longer has any effect. + +#### What should I do? + +Remove the `handleForms` property from your `ViewTransitions` component. It is no longer necessary. + +```astro title="src/pages/index.astro" del="handleForms" +--- +import { ViewTransitions } from "astro:transitions"; +--- + + + + + + + + +``` + +To opt-out of `submit` event handling, add the `data-astro-reload` attribute to relevant `form` elements. + +```astro title="src/components/Form.astro" +
+ +
+``` + +## Previously deprecated features now removed + +The following deprecated features have now been entirely removed from the code base and can no longer be used. Some of these features may have continued to work in your project even after deprecation. Others may have silently had no effect. -## Removed +Projects now containing these removed features will be unable to build, and there will no longer be any supporting documentation prompting you to remove these features. ### Removed: returning simple objects from endpoints @@ -167,72 +266,76 @@ To remove usage of `ResponseWithEncoding`, refactor your code to use an `ArrayBu } ``` -### Removed: Shiki language `path` property +### Removed: `build.split` and `build.excludeMiddleware` -In Astro v3.x, a Shiki language passed to `markdown.shikiConfig.langs` was automatically converted to a Shikiji-compatible language. Shikiji is the internal tooling used by Astro for syntax highlighting. +In Astro v3.0, `build.split` and `build.excludeMiddleware` build config options were deprecated and replaced with [adapter configuration options](/en/reference/adapter-reference/#adapter-features) to perform the same tasks. -Astro v4.0 removes support for the `path` property of a Shiki language, which was confusing to configure. It is replaced by an import which can be passed to `langs` directly. +Astro v4.0 removes these properties entirely. #### What should I do? -The language JSON file should be imported and passed to the option instead. - -```diff lang="js" -// astro.config.js -+ import customLang from './custom.tmLanguage.json' +If you are using the deprecated `build.split` or `build.excludeMiddleware`, you must now remove them as these no longer exist. -export default defineConfig({ - markdown: { - shikiConfig: { - langs: [ -- { path: '../../custom.tmLanguage.json' }, -+ customLang, - ], - }, - }, -}) -``` +Please see the v3 migration guide to [update these deprecated middleware properties](/en/guides/upgrade-to/v3/#deprecated-buildexcludemiddleware-and-buildsplit) with adapter configurations. -### Removed: `build.split` and `build.excludeMiddleware` +### Removed: `Astro.request.params` -In Astro 3.0, `build.split` and `build.excludeMiddleware` were deprecated. +In Astro v3.0, the `Astro.request.params` API was deprecated, but preserved for backwards compatibility. -Astro 4.0 removes these properties entirely. +Astro v4.0 removes this option entirely. #### What should I do? -If you are using the deprecated `build.split` or `build.excludeMiddleware`, you must now remove them as these no longer exist. +Update all occurances to [`Astro.params`](/en/reference/api-reference/#astroparams), which is the supported replacement. -Please see the v3 migration guide to [update these deprecated middleware properties](/en/guides/upgrade-to/v3/#deprecated-buildexcludemiddleware-and-buildsplit) with adapter configurations. +```astro del={1} ins={2} +const { id } = Astro.request.params; +const { id } = Astro.params; +``` ### Removed: `markdown.drafts` -In Astro 3.0, using `markdown.drafts` to control the building of draft posts was deprecated. +In Astro v3.0, using `markdown.drafts` to control the building of draft posts was deprecated. -Astro 4.0 removes this option entirely. +Astro v4.0 removes this option entirely. #### What should I do? If you are using the deprecated `markdown.drafts`, you must now remove it as it no longer exist. -Please see the v3 migration guide to [upgrade to content collections to filter draft posts before building](/en/guides/upgrade-to/v3/#deprecated-markdowndrafts). +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. ### Removed: `getHeaders()` -In Astro 3.0, the `getHeaders()` Markdown export was deprecated and replaced with `getHeadings()`. +In Astro v3.0, the `getHeaders()` Markdown export was deprecated and replaced with `getHeadings()`. -Astro 4.0 removes this option entirely. +Astro v4.0 removes this option entirely. #### What should I do? -If you are using the deprecated `getHeaders()`, you must now remove it as it no longer exists. Replace any instances with `getHeadings()`. +If you are using the deprecated `getHeaders()`, you must now remove it as it no longer exists. Replace any instances with `getHeadings()`, which is the supported replacement. + +```astro del={1} ins={2} +const headings = getHeaders(); +const headings = getHeadings(); +``` + +### Removed: using `rss` in `getStaticPaths()` + +In Astro v3.0, using the deprecated `rss` helper in `getStaticPaths()` would throw an error. + +Astro v4.0 removes this helper entirely. + +#### What should I do? + +If you are using the unsupported method for generating RSS feeds, you must now use the [`@astrojs/rss` integration](/en/guides/rss/) for a complete RSS setup. ### Removed: lowercase HTTP method names -In Astro 3.0, using lowercase HTTP request method names (`get`, `post`, `put`, `all`, `del`) was deprecated. +In Astro v3.0, using lowercase HTTP request method names (`get`, `post`, `put`, `all`, `del`) was deprecated. -Astro 4.0 removes support for lowercase names entirely. All HTTP request methods must now be written using uppercase. +Astro v4.0 removes support for lowercase names entirely. All HTTP request methods must now be written using uppercase. #### What should I do? @@ -240,28 +343,38 @@ If you are using the deprecated lowercase names, you must now replace them with Please see the v3 migration guide [for guidance using uppercase HTTP request methods](/en/guides/upgrade-to/v3/#changed-http-request-methods-case). -## Deprecated - -### Deprecated: `handleForms` for View Transitions submit `events` - -In Astro v3.x, projects using the `` component were required to opt-in to handling `submit` events for `form` elements. This was done by passing a `handleForms` prop. +### Removed: 301 redirects when missing a `base` prefix -Astro v4.0 handles `submit` events for `form` elements by default when `` are used. The `handleForms` prop has been deprecated and no longer has any effect. +In Astro v3.x, the Astro preview server returned a 301 redirect when accessing public directory assets without a base path. +Astro 4.0 returns a 404 status without a base path prefix for public directory assets when the preview server is running, matching the behaviour of the dev server. + #### What should I do? -Remove the `handleForms` property from your `ViewTransitions` component. +When using the Astro preview server, all of your static asset imports and URLs from the public directory must have [the base value](/en/reference/configuration-reference/#base) prefixed to the path. -To opt-out of `submit` event handling, add the `data-astro-reload` attribute to relevant `form` elements. +The following example shows the `src` attribute required to display an image from the public folder when `base: '/docs'` is configured: -```astro title="src/components/Form.astro" -
- -
+```astro title="src/pages/index.astro" ins="/docs" +// To access public/images/my-image.png: + + ``` +### Removed: `astro/client-image` auto-conversion +In Astro v3.x, the `astro/client-image` type (used for the deprecated image integration) was removed but was auto-converted to the default Astro type `astro/client` if found in your `env.d.ts` file. +Astro 4.0 ignores `astro/client-image` and will no longer update `env.d.ts` for you automatically. + +#### What should I do? + +If you had types configured for `@astrojs/image` in `src/env.d.ts` and upgrading to v3.0 did not automatically convert the type for you, replace the `astro/client-image` type manually with `astro/client`. + +```ts title="src/env.d.ts" del={1} ins={2} + /// + /// +``` ## Community Resources From 74718e6a9988fea535624d8270c638c4671ddf32 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sat, 2 Dec 2023 15:59:26 +0000 Subject: [PATCH 06/13] hiding v4 guide until release day --- src/i18n/en/nav.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts index e5f2fb93b556c..3a534bf6a372e 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 v4', slug: 'guides/upgrade-to/v4', key: 'guides/upgrade-to/v4' }, + { 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 fa3c6d584b2d64db344ad7af5fe390adccb7bfb7 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sat, 2 Dec 2023 13:30:17 -0400 Subject: [PATCH 07/13] better code example Co-authored-by: Kevin Zuniga Cuellar <46791833+kevinzunigacuellar@users.noreply.github.com> --- src/content/docs/en/guides/upgrade-to/v4.mdx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v4.mdx b/src/content/docs/en/guides/upgrade-to/v4.mdx index 045fd65e9f8eb..e5f40fe4a0bc1 100644 --- a/src/content/docs/en/guides/upgrade-to/v4.mdx +++ b/src/content/docs/en/guides/upgrade-to/v4.mdx @@ -315,9 +315,10 @@ Astro v4.0 removes this option entirely. If you are using the deprecated `getHeaders()`, you must now remove it as it no longer exists. Replace any instances with `getHeadings()`, which is the supported replacement. -```astro del={1} ins={2} -const headings = getHeaders(); -const headings = getHeadings(); +```astro del={2} ins={3} +const posts = await Astro.glob('../content/blog/*.mdx'); +const firstPostHeadings = posts.at(0).getHeaders(); +const firstPostHeadings = posts.at(0).getHeadings(); ``` From 1b9d90c9aecb050c6b80000988a32ed078631b4d Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sat, 2 Dec 2023 18:41:15 -0400 Subject: [PATCH 08/13] v4.0 consistency! Co-authored-by: Alex Nguyen Co-authored-by: Kevin Zuniga Cuellar <46791833+kevinzunigacuellar@users.noreply.github.com> --- src/content/docs/en/guides/upgrade-to/v4.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v4.mdx b/src/content/docs/en/guides/upgrade-to/v4.mdx index e5f40fe4a0bc1..81284da70c16a 100644 --- a/src/content/docs/en/guides/upgrade-to/v4.mdx +++ b/src/content/docs/en/guides/upgrade-to/v4.mdx @@ -73,7 +73,7 @@ These features are now available by default: - - -Read more about these two exciting features and more in [the 4.0 Blog post](https://astro.build/blog/astro-4/)! +Read more about these two exciting features and more in [the v4.0 Blog post](https://astro.build/blog/astro-4/)! ## Upgrades @@ -106,7 +106,7 @@ Visually inspect your Markdown/MDX pages before deploying to ensure your site is The following changes are considered breaking changes in Astro. Breaking changes may or may not provide temporary backwards compatibility, and all documentation is updated to refer to only the current, supported code. -If you need to refer to documentation for a v3.x project, you can browse this (unmaintained) version of the docs from before 4.0 was released. +If you need to refer to documentation for a v3.x project, you can browse this (unmaintained) version of the docs from before v4.0 was released. ### Renamed: `entrypoint` (Integrations API) @@ -144,7 +144,7 @@ If you are maintaining an adapter, the current signature will continue to work u In Astro v3.x, adapters were not required to specify the features they support. -Astro 4.0 requires adapters to pass the `supportedAstroFeatures{}` property to specify a list of features they support. This property is no longer optional. +Astro v4.0 requires adapters to pass the `supportedAstroFeatures{}` property to specify a list of features they support. This property is no longer optional. #### What should I do? @@ -315,7 +315,7 @@ Astro v4.0 removes this option entirely. If you are using the deprecated `getHeaders()`, you must now remove it as it no longer exists. Replace any instances with `getHeadings()`, which is the supported replacement. -```astro del={2} ins={3} +```js del={2} ins={3} const posts = await Astro.glob('../content/blog/*.mdx'); const firstPostHeadings = posts.at(0).getHeaders(); const firstPostHeadings = posts.at(0).getHeadings(); @@ -348,7 +348,7 @@ Please see the v3 migration guide [for guidance using uppercase HTTP request met In Astro v3.x, the Astro preview server returned a 301 redirect when accessing public directory assets without a base path. -Astro 4.0 returns a 404 status without a base path prefix for public directory assets when the preview server is running, matching the behaviour of the dev server. +Astro v4.0 returns a 404 status without a base path prefix for public directory assets when the preview server is running, matching the behaviour of the dev server. #### What should I do? @@ -366,7 +366,7 @@ The following example shows the `src` attribute required to display an image fro In Astro v3.x, the `astro/client-image` type (used for the deprecated image integration) was removed but was auto-converted to the default Astro type `astro/client` if found in your `env.d.ts` file. -Astro 4.0 ignores `astro/client-image` and will no longer update `env.d.ts` for you automatically. +Astro v4.0 ignores `astro/client-image` and will no longer update `env.d.ts` for you automatically. #### What should I do? From 0cc601a626db40e805ee9e073cea1fb61f72a433 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sun, 3 Dec 2023 09:12:22 -0400 Subject: [PATCH 09/13] Apply suggestions from Yan Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> --- src/content/docs/en/guides/upgrade-to/v4.mdx | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v4.mdx b/src/content/docs/en/guides/upgrade-to/v4.mdx index 81284da70c16a..58a524ba9f51d 100644 --- a/src/content/docs/en/guides/upgrade-to/v4.mdx +++ b/src/content/docs/en/guides/upgrade-to/v4.mdx @@ -87,32 +87,32 @@ Astro v4.0 upgrades from Vite 4 to Vite 5. #### What should I do? -If you are using Vite-specific plugins, configuration or APIs, check the [Vite migration guide](https://vitejs.dev/guide/migration) for their breaking changes and upgrade your project as needed. There are no breaking changes to Astro itself. +If you are using Vite-specific plugins, configuration, or APIs, check the [Vite migration guide](https://vitejs.dev/guide/migration) for their breaking changes and upgrade your project as needed. There are no breaking changes to Astro itself. ### Upgraded: unified, remark, and rehype dependencies In Astro v3.x, unified v10 and its related compatible remark/rehype packages were used to process Markdown and MDX. -Astro v4.0 upgrades [unified to v11](https://github.com/unifiedjs/unified/releases/tag/11.0.0) and the other remark/rehype packages to latest. +Astro v4.0 upgrades [unified to v11](https://github.com/unifiedjs/unified/releases/tag/11.0.0) and the other remark/rehype packages to the latest version. #### What should I do? -If you used custom remark/rehype packages, update all of them to latest using your package manager to ensure they support unified v11. The packages you are using can be found in `astro.config.mjs`. +If you used custom remark/rehype packages, update all of them to the latest version using your package manager to ensure they support unified v11. The packages you are using can be found in `astro.config.mjs`. -There should not be any significant breaking changes if you use actively-updated packages, but some packages may not yet be compatible with unified v11. +There should not be any significant breaking changes if you use actively updated packages, but some packages may not yet be compatible with unified v11. Visually inspect your Markdown/MDX pages before deploying to ensure your site is functioning as intended. ## Breaking Changes The following changes are considered breaking changes in Astro. Breaking changes may or may not provide temporary backwards compatibility, and all documentation is updated to refer to only the current, supported code. -If you need to refer to documentation for a v3.x project, you can browse this (unmaintained) version of the docs from before v4.0 was released. +If you need to refer to the documentation for a v3.x project, you can browse this (unmaintained) version of the docs from before v4.0 was released. ### Renamed: `entrypoint` (Integrations API) In Astro v3.x, the property of the `injectRoute` integrations API that specified the route entry point was named `entryPoint`. -Astro v4.0 renames this property to `entrypoint` to be consistent with other Astro APIs. The `entryPoint` property is deprecated, but will continue to work and logs a warning prompting you to update your code. +Astro v4.0 renames this property to `entrypoint` to be consistent with other Astro APIs. The `entryPoint` property is deprecated but will continue to work and logs a warning prompting you to update your code. #### What should I do? @@ -225,7 +225,7 @@ import { ViewTransitions } from "astro:transitions"; ``` -To opt-out of `submit` event handling, add the `data-astro-reload` attribute to relevant `form` elements. +To opt out of `submit` event handling, add the `data-astro-reload` attribute to relevant `form` elements. ```astro title="src/components/Form.astro"
@@ -286,7 +286,7 @@ Astro v4.0 removes this option entirely. #### What should I do? -Update all occurances to [`Astro.params`](/en/reference/api-reference/#astroparams), which is the supported replacement. +Update all occurrences to [`Astro.params`](/en/reference/api-reference/#astroparams), which is the supported replacement. ```astro del={1} ins={2} const { id } = Astro.request.params; @@ -301,7 +301,7 @@ Astro v4.0 removes this option entirely. #### What should I do? -If you are using the deprecated `markdown.drafts`, you must now remove it as it no longer exist. +If you are using the deprecated `markdown.drafts`, you must now remove it as it no longer exists. 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. @@ -348,7 +348,7 @@ Please see the v3 migration guide [for guidance using uppercase HTTP request met In Astro v3.x, the Astro preview server returned a 301 redirect when accessing public directory assets without a base path. -Astro v4.0 returns a 404 status without a base path prefix for public directory assets when the preview server is running, matching the behaviour of the dev server. +Astro v4.0 returns a 404 status without a base path prefix for public directory assets when the preview server is running, matching the behavior of the dev server. #### What should I do? From e04262f5f63c8c0b297f9925579e1e4338a1f63e Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sun, 3 Dec 2023 09:13:14 -0400 Subject: [PATCH 10/13] Let's get this i18n party started! --- src/content/docs/en/guides/upgrade-to/v4.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v4.mdx b/src/content/docs/en/guides/upgrade-to/v4.mdx index 58a524ba9f51d..96910f1723eb1 100644 --- a/src/content/docs/en/guides/upgrade-to/v4.mdx +++ b/src/content/docs/en/guides/upgrade-to/v4.mdx @@ -1,7 +1,7 @@ --- title: Upgrade to Astro v4 description: How to upgrade your project to the latest version of Astro (v4.0). -i18nReady: false +i18nReady: true --- import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' import FileTree from '~/components/FileTree.astro' From 67fd353080815fee8f1583f1cd79a63e6cffe9a5 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sun, 3 Dec 2023 13:44:43 +0000 Subject: [PATCH 11/13] add older version of docs link --- src/content/docs/en/guides/upgrade-to/v4.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v4.mdx b/src/content/docs/en/guides/upgrade-to/v4.mdx index 96910f1723eb1..63045e89ae47a 100644 --- a/src/content/docs/en/guides/upgrade-to/v4.mdx +++ b/src/content/docs/en/guides/upgrade-to/v4.mdx @@ -10,7 +10,7 @@ This guide will help you migrate from Astro v3 to Astro v4. Need to upgrade an older project to v3? See our [older migration guide](/en/guides/upgrade-to/v3/). -Need to see the v3 docs? Visit this older version of the docs site (unmaintained). +Need to see the v3 docs? Visit this [older version of the docs site (unmaintained v3.6 snapshot)](https://docs-git-v3-docs-unmaintained-astrodotbuild.vercel.app/). ## Upgrade Astro @@ -106,7 +106,7 @@ Visually inspect your Markdown/MDX pages before deploying to ensure your site is The following changes are considered breaking changes in Astro. Breaking changes may or may not provide temporary backwards compatibility, and all documentation is updated to refer to only the current, supported code. -If you need to refer to the documentation for a v3.x project, you can browse this (unmaintained) version of the docs from before v4.0 was released. +If you need to refer to the documentation for a v3.x project, you can browse this [(unmaintained) snapshot of the docs from before v4.0 was released](https://docs-git-v3-docs-unmaintained-astrodotbuild.vercel.app/). ### Renamed: `entrypoint` (Integrations API) From 1d4abb6551bfbbc4991235b4095cef0c801a0bc2 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sun, 3 Dec 2023 13:57:58 +0000 Subject: [PATCH 12/13] added experimental flags to remove --- src/content/docs/en/guides/upgrade-to/v4.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v4.mdx b/src/content/docs/en/guides/upgrade-to/v4.mdx index 63045e89ae47a..95b534cda30f9 100644 --- a/src/content/docs/en/guides/upgrade-to/v4.mdx +++ b/src/content/docs/en/guides/upgrade-to/v4.mdx @@ -57,21 +57,21 @@ See [the changelog](https://github.com/withastro/astro/blob/main/packages/astro/ Remove the following experimental flags from `astro.config.mjs`: -```js del={6} -// astro.config.mjs +```js del={5-9} title="astro.config.mjs" import { defineConfig } from 'astro/config'; export default defineConfig({ experimental: { - // nothing here yet @TODO: check if needed + devOverlay: true, + i18n: { + defaultLocale: "en", + locales: ["en", "fr", "pt-br", "es"], + } }, }) ``` -These features are now available by default: - -- -- +These features are now available in Astro v4.0. Read more about these two exciting features and more in [the v4.0 Blog post](https://astro.build/blog/astro-4/)! From 8d2d48deb04b878373618853348edea9e20282c1 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sun, 3 Dec 2023 14:00:46 +0000 Subject: [PATCH 13/13] added link to issues --- src/content/docs/en/guides/upgrade-to/v4.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v4.mdx b/src/content/docs/en/guides/upgrade-to/v4.mdx index 95b534cda30f9..7f85921f41e5f 100644 --- a/src/content/docs/en/guides/upgrade-to/v4.mdx +++ b/src/content/docs/en/guides/upgrade-to/v4.mdx @@ -384,4 +384,4 @@ Know a good resource for Astro v4.0? [Edit this page](https://github.com/withast ## Known Issues -There are currently no known issues. +Please check [Astro's issues on GitHub](https://github.com/withastro/astro/issues/) for any reported issues, or to file an issue yourself.