Astro 4.0 upgrade guide

src/content/docs/en/guides/upgrade-to/v4.mdx

@@ -0,0 +1,386 @@
+---
+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).
+
+## Upgrade Astro
+
+Update your project's version of Astro and all official integrations to the latest versions using your package manager.
+
+<PackageManagerTabs>
+  <Fragment slot="npm">
+  ```shell
+  # Upgrade Astro and official integrations together
+  npx @astrojs/upgrade
+  ```
+  </Fragment>
+  <Fragment slot="pnpm">
+  ```shell
+  # Upgrade Astro and official integrations together
+  pnpm dlx @astrojs/upgrade
+  ```
+  </Fragment>
+  <Fragment slot="yarn">
+  ```shell
+  # Upgrade Astro and official integrations together
+  yarn dlx @astrojs/upgrade
+  ```
+  </Fragment>
+</PackageManagerTabs>
+
+
+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!
+
+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`:
+
+```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/)!
+
+## Upgrades
+
+Any major upgrades to Astro's dependencies may cause breaking changes in your project.
+
+### 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.
+
+### 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.
+
+#### 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.
+
+## 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)
+
+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.
+
+```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. 
+
+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 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.
+
+```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 `<ViewTransitions />` 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 `<ViewTransitions />` 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";
+---
+<html>
+  <head>
+    <ViewTransitions handleForms />
+  </head>
+  <body>
+    <!-- stuff here -->
+  </body>
+</html>
+```
+
+To opt-out of `submit` event handling, add the `data-astro-reload` attribute to relevant `form` elements.
+
+```astro title="src/components/Form.astro"
+<form action="/contact" data-astro-reload>
+  <!-- -->
+</form>
+```
+
+## 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.
+
+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
+
+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: `build.split` and `build.excludeMiddleware`
+
+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 these properties 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.
+
+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: `Astro.request.params`
+
+In Astro v3.0, the `Astro.request.params` API was deprecated, but preserved for backwards compatibility.
+
+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.
+
+```astro del={1} ins={2}
+const { id } = Astro.request.params;
+const { id } = Astro.params;
+```
+
+### Removed: `markdown.drafts`
+
+In Astro v3.0, using `markdown.drafts` to control the building of draft posts was deprecated.
+
+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.
+
+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 v3.0, the `getHeaders()` Markdown export was deprecated and replaced with `getHeadings()`.
+
+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()`, 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 v3.0, using lowercase HTTP request method names (`get`, `post`, `put`, `all`, `del`) was deprecated.
+
+Astro v4.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).
+
+### Removed: 301 redirects when missing a `base` prefix
+
+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?
+
+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.
+
+The following example shows the `src` attribute required to display an image from the public folder when `base: '/docs'` is configured:
+
+```astro title="src/pages/index.astro" ins="/docs"
+// To access public/images/my-image.png:
+
+<img src="/docs/images/my-image.png" alt="">
+```
+
+### 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}
+  /// <reference types="astro/client-image" />
+  /// <reference types="astro/client" />
+```
+
+
+## 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.