Merge branch 'v3-upgrade-guide' into feat/astro-features-plt-722

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.
+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.

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

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

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, 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.
+
+Please see the full [v3 Image Upgrade Guide](/en/guides/images/#upgrade-to-v30-from-v2x) for details!
 
-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.
+
+### 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?
 
-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.
+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,25 +360,142 @@ 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
+### Removed: camelCase transformations
 
-In Astro v2.x, Astro deprecated the `<Markdown />` component and moved it to an external package.
+In Astro 2.x, Astro automatically transformed camelCase CSS variable names passed to the `style` attribute of an HTML element.
 
-Astro v3.0 comletely removes the package `@astrojs/markdown-component`, so Astro's `<Markdown />` component will no longer work in your project.
+Astro 3.0 removes backwards-compatible kebab-case transform for these camelCase CSS variable names. 
 
 #### 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.
+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:
 
-### Removed: camelCase transformations
+```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>
+```
 
-In Astro 2.x, Astro automatically transformed camelCase CSS variable names passed to the `style` attribute of an HTML element.
+```diff
+<style>
+  div {
+-   color: var(--my-value);
++   color: var(--myValue);
+  }
+</style>
+```
 
-Astro 3.0 removes backwards-compatible kebab-case transform for these camelCase CSS variable names. 
+### 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?
 
-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:
+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 automatically scanned your components to determine which framework-specific transformations should be used, but at a performance cost.
+
+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?
+
+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';
+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.
+  // No `include` is needed if you are only using a single framework!
+  integrations: [
+		preact({
+			include: ['**/preact/*']
+		}),
+		react({
+			include: ['**/react/*']
+		}),
+		solid({
+			include: ['**/solid/*'],
+		}),
+  ]
+});
+```
+
+
+### 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
 ---
@@ -362,6 +518,82 @@ const myValue = "red"
 </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.