Merge branch 'v3-upgrade-guide' into i18n-ja-integrations-guide-v3

src/components/LeftSidebar/Sponsors.astro

@@ -4,15 +4,9 @@ import UIString from '../UIString.astro';
 
 <div dir="ltr" lang="en" class="sponsors">
 	<h2 class="sponsors-title"><UIString key="leftSidebar.sponsoredBy" /></h2>
-	<a href="https://www.netlify.com/" aria-label="Netlify">
-		<svg xmlns="http://www.w3.org/2000/svg" width="105" viewBox="0 0 256 105" aria-hidden="true">
-			<path
-				fill="#32E6E2"
-				d="M58.5 103.8V77.4l.5-.5h6.6l.6.5v26.4l-.6.5H59l-.5-.5Zm0-76.9V.5L59 0h6.6l.6.5V27l-.6.5H59l-.5-.5ZM35.8 85.2h-1l-4.4-4.5v-.9l8.5-8.5h4.7l.7.6v4.8l-8.5 8.5Zm-5.4-60.5v-.9l4.5-4.5h.9l8.5 8.5v4.8l-.7.6H39l-8.5-8.5ZM.5 48.3H38l.5.6v6.6l-.5.5H.5l-.5-.5v-6.6l.5-.6Zm255 0 .5.6v6.6l-.6.5h-37.8l-.6-.5 2.8-6.6.5-.6h35.1Z"
-			></path>
-			<path
-				d="M74.7 65.9H68l-.6-.6V50c0-2.7-1-4.9-4.4-5-1.7 0-3.6 0-5.7.2l-.3.3v20l-.6.5H50l-.6-.6V39l.6-.6h14.8c5.7 0 10.4 4.7 10.4 10.5v16.4l-.5.6Zm31.9-11.6-.6.6H89l-.6.5c0 1.1 1.1 4.4 5.5 4.4 1.7 0 3.3-.5 3.9-1.6l.5-.6h6.6l.6.6c-.6 3.3-3.3 8.2-11.6 8.2-9.3 0-13.7-6.6-13.7-14.3S84.6 38 93.4 38s13.2 6.6 13.2 14.2v2.2ZM98.3 49c0-.6-.5-4.4-5-4.4s-4.9 3.8-4.9 4.4l.6.5h8.8l.5-.5Zm23.7 8.7c0 1.1.5 1.7 1.6 1.7h5l.5.5v5.5l-.6.6h-4.9c-5 0-9.3-2.2-9.3-8.3v-12l-.6-.6H110l-.6-.5V39l.6-.6h3.8l.6-.5v-5l.5-.5h6.6l.5.5v5l.6.5h6l.6.6v5.5l-.6.5h-6l-.6.6v12Zm20.3 8.3h-6.6l-.6-.6V28l.6-.6h6.6l.5.6v37.3l-.5.6ZM157 34h-6.6l-.5-.5V28l.5-.6h6.6l.6.6v5.5l-.6.5Zm0 31.9h-6.6l-.5-.6V39l.5-.6h6.6l.6.6v26.3l-.6.6Zm25.8-38v5.6l-.5.5h-5c-1 0-1.6.6-1.6 1.7v2.2l.5.5h5.5l.6.6v5.5l-.6.5h-5.5l-.5.6v19.7l-.6.6h-6.5l-.6-.6V45.5l-.5-.5h-3.9l-.5-.5V39l.5-.6h3.9l.5-.5v-2.2c0-6 4.4-8.3 9.4-8.3h4.9l.5.6Zm20.3 38.5c-2.2 5.5-4.3 8.8-12 8.8h-2.8l-.5-.5v-5.5l.5-.6h2.8c2.7 0 3.3-.5 3.8-2.2V66l-8.8-21.4V39l.6-.6h5l.5.6 6.5 18.7h.6L206 39l.5-.6h5l.5.6v5.5l-8.8 22Z"
-			></path>
+	<a href="https://vercel.com/" aria-label="Vercel">
+		<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 284 65" width="95" aria-hidden="true">
+			<path d="M141.7 16.3c-11 0-19 7.1-19 18s9 18 20 18c6.7 0 12.5-2.7 16.2-7.1l-7.7-4.5c-2 2.2-5 3.5-8.5 3.5-4.8 0-8.9-2.5-10.4-6.5h28c.3-1 .4-2.2.4-3.5 0-10.8-8-18-19-18zm-9.5 14.4c1.3-4 4.7-6.4 9.5-6.4s8.2 2.5 9.4 6.4h-18.9zm117.2-14.4c-11 0-19 7.1-19 18s9 18 20 18a21 21 0 0 0 16.2-7.1l-7.7-4.5c-2 2.2-5 3.5-8.5 3.5-4.8 0-8.9-2.5-10.4-6.5h28c.2-1 .4-2.2.4-3.5 0-10.8-8-18-19-18zm-9.5 14.4c1.3-4 4.7-6.4 9.5-6.4s8.2 2.5 9.4 6.4H240zm-39 3.6c0 6 3.9 10 10 10 4.1 0 7.2-2 8.8-5l7.7 4.5a18.5 18.5 0 0 1-16.5 8.5c-11 0-19-7.2-19-18s8-18 19-18c7.3 0 13.3 3.1 16.5 8.4l-7.7 4.5c-1.6-3-4.7-5-8.8-5-6 0-10 4-10 10zm82.5-29v46h-9v-46h9zM37.6.3l37 64H.5l37-64zm92.4 5-27.7 48-27.8-48H85l17.4 30 17.3-30H130zm58.9 12v9.6c-1-.3-2-.5-3.2-.5-5.8 0-10 4-10 10v14.9h-9v-34h9v9.1c0-5 5.9-9.1 13.2-9.1z"/>
 		</svg>
 	</a>
 	<a href="https://www.storyblok.com/" aria-label="Storyblok">

src/content/docs/ar/getting-started.mdx

@@ -81,7 +81,7 @@ import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
 
 ## انضم إلى مجتمعنا
 
-انضم إلى مجتمع [أسترو على ديسكورد](https://astro.build/chat/) للمشاركة والحصول على المساعدة من مجتمع نشط وودود!
+انضم إلى مجتمع [أسترو على ديسكورد](https://astro.build/chat) للمشاركة والحصول على المساعدة من مجتمع نشط وودود!
 
 💬 رحّب وعرف بنفسك على قناة `#general`!
 

src/content/docs/de/getting-started.mdx

@@ -92,7 +92,7 @@ Sieh dir Beispiele zu einigen grundlegenden Konzepten und Strukturen einer Astro
 
 ## Werde Teil unserer Community
 
-Tritt dem [Astro-Discord](https://astro.build/chat/) bei, um deine Erfahrungen und Fragen rund um Astro mit unserer aktiven, freundlichen Community zu teilen!
+Tritt dem [Astro-Discord](https://astro.build/chat) bei, um deine Erfahrungen und Fragen rund um Astro mit unserer aktiven, freundlichen Community zu teilen!
 
 💬 Stell dich im Kanal `#general` vor!
 

src/content/docs/en/core-concepts/endpoints.mdx

@@ -10,9 +10,10 @@ Astro lets you create custom endpoints to serve any kind of data. You can use th
 In statically-generated sites, your custom endpoints are called at build time to produce static files. If you opt in to [SSR](/en/guides/server-side-rendering/) mode, custom endpoints turn into live server endpoints that are called on request. Static and SSR endpoints are defined similarly, but SSR endpoints support additional features.
 
 ## Static File Endpoints
+
 To create a custom endpoint, add a `.js` or `.ts` file to the `/pages` directory. The `.js` or `.ts` extension will be removed during the build process, so the name of the file should include the extension of the data you want to create. For example, `src/pages/data.json.ts` will build a `/data.json` endpoint.
 
-Endpoints export a `get` function (optionally `async`) that receives a [context object](/en/reference/api-reference/#endpoint-context) with properties similar to the `Astro` global. It returns an object with a `body`, and Astro will call this at build time and use the contents of the body to generate the file.
+Endpoints export a `GET` function (optionally `async`) that receives a [context object](/en/reference/api-reference/#endpoint-context) with properties similar to the `Astro` global. Here, it returns an Response object with a `name` and `url`, and Astro will call this at build time and use the contents of the body to generate the file.
 
 ```ts
 // Example: src/pages/builtwith.json.ts
@@ -27,9 +28,9 @@ 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:
+Since Astro v3.0, the returned `Response` object doesn't have to include the `encoding` property anymore. For example, to produce a binary png image:
 
-```ts title="src/pages/astro-logo.png.ts" {6}
+```ts title="src/pages/astro-logo.png.ts" {3}
 export async function GET({ params, request }) {
   const response = await fetch("https://docs.astro.build/assets/full-logo-light.png");
   return new Response(await response.arrayBuffer());
@@ -51,7 +52,7 @@ Endpoints support the same [dynamic routing](/en/core-concepts/routing/#dynamic-
 ```ts title="src/pages/api/[id].json.ts"
 import type { APIRoute } from 'astro';
 
-const usernames = ["Sarah", "Chris", "Dan"]
+const usernames = ["Sarah", "Chris", "Yan", "Elian"]
 
 export const GET: APIRoute = ({ params, request }) => {
   const id = params.id;
@@ -67,13 +68,15 @@ export function getStaticPaths() {
     { params: { id: "0"} },
     { params: { id: "1"} },
     { params: { id: "2"} },
+    { params: { id: "3"} }
   ]
 }
 ```
 
-This will generate three JSON endpoints at build time: `/api/0.json`, `/api/1.json`, `/api/2.json`. Dynamic routing with endpoints works the same as it does with pages, but because the endpoint is a function and not a component, [props](/en/reference/api-reference/#data-passing-with-props) aren't supported.
+This will generate four JSON endpoints at build time: `/api/0.json`, `/api/1.json`, `/api/2.json` and `/api/3.json`. Dynamic routing with endpoints works the same as it does with pages, but because the endpoint is a function and not a component, [props](/en/reference/api-reference/#data-passing-with-props) aren't supported.
 
 ### `request`
+
 All endpoints receive a `request` property, but in static mode, you only have access to `request.url`. This returns the full URL of the current endpoint and works the same as [Astro.request.url](/en/reference/api-reference/#astrorequest) does for pages.
 
 ```ts title="src/pages/request-path.json.ts"
@@ -88,7 +91,8 @@ export const GET: APIRoute = ({ params, request }) => {
 ```
 
 ## Server Endpoints (API Routes)
-Everything described in the static file endpoints section can also be used in SSR mode: files can export a `get` function which receives a [context object](/en/reference/api-reference/#endpoint-context) with properties similar to the `Astro` global.
+
+Everything described in the static file endpoints section can also be used in SSR mode: files can export a `GET` function which receives a [context object](/en/reference/api-reference/#endpoint-context) with properties similar to the `Astro` global.
 
 But, unlike in `static` mode, when you configure `server` mode, the endpoints will be built when they are requested. This unlocks new features that are unavailable at build time, and allows you to build API routes that listen for requests and securely execute code on the server at runtime.
 
@@ -140,6 +144,7 @@ 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. 
 
 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).
@@ -176,7 +181,8 @@ export const ALL: APIRoute = ({ request }) => {
 
 <RecipeLinks slugs={["en/recipes/captcha", "en/recipes/build-forms-api" ]}/>
 
-### `request` 
+### `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"
@@ -195,6 +201,7 @@ export const POST: APIRoute = async ({ request }) => {
 ```
 
 ### Redirects
+
 The endpoint context exports a `redirect()` utility similar to `Astro.redirect`:
 
 ```js title="src/pages/links/[id].js" {14}

src/content/docs/en/getting-started.mdx

@@ -8,6 +8,11 @@ import TranslatorList from '~/components/TranslatorList.astro'
 import ContributorList from '~/components/ContributorList.astro'
 import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
 
+{/* TODO: Replace with 3.0 tip on 30 August 2023. */}
+:::tip[Hello Astronauts!]
+Our new docs theme [Starlight is on Product Hunt today](https://www.producthunt.com/posts/starlight-by-astro).
+:::
+
 <h2>What is Astro?</h2>
 
 Astro is an **all-in-one** **web framework** for building **fast,** **content-focused** websites. 
@@ -88,7 +93,7 @@ See examples of some of the key concepts and patterns of an Astro site!
 
 ## Join our Community
 
-Join us in the [Astro Discord](https://astro.build/chat/) to share with and get help from an active, friendly community!
+Join us in the [Astro Discord](https://astro.build/chat) to share with and get help from an active, friendly community!
 
 💬 Say hi in our `#general` channel!
 

src/content/docs/en/guides/integrations-guide/react.mdx

@@ -134,7 +134,7 @@ import ReactComponent from './ReactComponent';
 </ReactComponent>
 ```
 
-If you are using a library that *expects* more than one child element element to be passed, for example so that it can slot certain elements in different places, you might find this to be a blocker.
+If you are using a library that *expects* more than one child element to be passed, for example so that it can slot certain elements in different places, you might find this to be a blocker.
 
 You can set the experimental flag `experimentalReactChildren` to tell Astro to always pass children to React as React vnodes. There is some runtime cost to this, but it can help with compatibility.
 

src/content/docs/en/guides/integrations-guide/vercel.mdx

@@ -223,9 +223,11 @@ export default defineConfig({
 });
 ```
 
-### Per-page functions
+### Function bundling configuration
 
-The Vercel adapter builds to a single function by default. Astro 2.7 added support for splitting your build into separate entry points per page. If you use this configuration the Vercel adapter will generate a separate function for each page. This can help reduce the size of each function so they are only bundling code used on that page.
+The Vercel adapter splits builds into a separate function per route by default. This helps reduce the size of each function, as it only bundles code used on that page.
+
+You can disable this and build to a single function by setting the `functionPerRoute` configuration option to `false`:
 
 ```js
 // astro.config.mjs
@@ -235,7 +237,7 @@ import vercel from '@astrojs/vercel/serverless';
 export default defineConfig({
   output: 'server',
   adapter: vercel({
-    functionPerRoute: true,
+    functionPerRoute: false,
   }),
 });
 ```

src/content/docs/en/guides/styling.mdx

@@ -159,8 +159,7 @@ import MyComponent from "../components/MyComponent.astro"
 <MyComponent class="red">This will be red!</MyComponent>
 ```
 
-This pattern lets you style child components directly. Astro will pass the parent’s scoped class name (e.g. `astro-hhnqfkh6`) through the `class` prop automatically, including the child in its parent’s scope.
-
+This pattern lets you style child components directly. Astro will pass the parent’s scoped class name (e.g. `astro-hhnqfkh6`) through the `class` prop automatically, including the child in its parent’s scope. Note this pattern only works when your [`scopedStyleStrategy` option](/en/reference/configuration-reference/#scopedstylestrategy) is either `'where'` or `'class'`.
 :::note[Scoped classes from parent components]
 Because the `class` prop includes the child in its parent’s scope, it is possible for styles to cascade from parent to child. To avoid this having unintended side effects, ensure you use unique class names in the child component.
 :::

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

@@ -182,9 +182,9 @@ If you are continuing to use v1.x APIs, use the new APIs for each feature instea
 
 ### 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.
+In Astro v2.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.
+Astro v3.0 removes this export entirely.
 
 #### What should I do?
 
@@ -263,7 +263,7 @@ const { class: className } = Astro.props;
 
 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.
+Astro v3.0 removes the kebab-case transform for these camelCase CSS variable names, and only the original camelCase CSS variable is rendered.
 
 ```astro "my-value"
 ---
@@ -363,6 +363,32 @@ Astro v3.0 deprecates this feature in favor of the content collections method of
 
 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.
 
+### Deprecated: returning simple object in endpoints
+
+In Astro v2.x, endpoints could return a simple object, which would be converted to a JSON response.
+
+Astro v3.0 deprecates this behavior in favor of returning a `Response` object directly.
+
+#### What should I do?
+
+Update your endpoints to return a `Response` object directly.
+
+```ts title="endpoint.json.ts" del={2} ins={3}
+export async function GET() {
+  return { body: { "title": "Bob's blog" }};
+  return new Response(JSON.stringify({ "title": "Bob's blog" }));
+}
+```
+
+If you really need to keep the previous format, you can use the `ResponseWithEncoding` object but will be deprecated in the future.
+
+```ts title="endpoint.json.ts" del={2} ins={3}
+export async function GET() {
+  return { body: { "title": "Bob's blog" } };
+  return new ResponseWithEncoding({ body: { "title": "Bob's blog" }});
+}
+```
+
 ### Changed default: port `3000`
 
 In Astro v2.x, Astro ran on port `3000` by default.

src/content/docs/en/reference/adapter-reference.mdx

@@ -358,6 +358,18 @@ export default function createIntegration() {
 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. 
 :::
 
+#### Serverless environments
+
+Setting `functionPerRoute: true` in a serverless environment creates a JavaScript file (handler) for each route. A handler might have different names based on your hosting platform: lambda, function, page, etc.
+
+Each of these routes is subject to a [cold start](https://azure.microsoft.com/en-us/blog/understanding-serverless-cold-start/) when the handler runs, which may cause some delay. This delay is influenced by different factors.
+
+With `functionPerRoute: false`, there is only one single handler in charge of rendering all your routes. When this handler is first triggered, you will be subject to a cold start. Then, all other routes should function without delay. However, you will lose the benefit of code splitting that `functionPerRoute: true` provides.
+
+:::note
+It's important that you understand your hosting platform, and how it works, in order to choose the appropriate `functionPerRoute` configuration for your project.
+:::
+
 ### `edgeMiddleware`
 
 Defines whether any SSR middleware code will be bundled when built.

src/content/docs/en/reference/configuration-reference.mdx

@@ -275,7 +275,7 @@ Specify the strategy used for scoping styles within Astro components. Choose fro
 
 Using `'class'` is helpful when you want to ensure that element selectors within an Astro component override global style defaults (e.g. from a global stylesheet).
 Using `'where'` gives you more control over specifity, but requires that you use higher-specifity selectors, layers, and other tools to control which selectors are applied.
-Using 'attribute' is useful when you are manipulating the `class` attribute of elements and need to avoid conflicts between your own styling logic and Astro's application of styles.
+Using `'attribute'` is useful when you are manipulating the `class` attribute of elements and need to avoid conflicts between your own styling logic and Astro's application of styles.
 
 
 ### adapter

src/content/docs/en/reference/publish-to-npm.mdx

@@ -229,7 +229,7 @@ If you are extracting components from an existing project, you can even continue
 
 ## Testing your component
 
-Astro does not currently ship a test runner. _(If you are interested in helping out with this, [join us on Discord!](https://astro.build/chat/))_
+Astro does not currently ship a test runner. _(If you are interested in helping out with this, [join us on Discord!](https://astro.build/chat))_
 
 In the meantime, our current recommendation for testing is:
 
@@ -284,4 +284,4 @@ In addition to the required `astro-component` or `withastro` keyword, special ke
 
 ## Share
 
-We encourage you to share your work, and we really do love seeing what our talented Astronauts create. Come and share what you create with us in our [Discord](https://astro.build/chat/) or mention [@astrodotbuild](https://twitter.com/astrodotbuild) in a Tweet!
+We encourage you to share your work, and we really do love seeing what our talented Astronauts create. Come and share what you create with us in our [Discord](https://astro.build/chat) or mention [@astrodotbuild](https://twitter.com/astrodotbuild) in a Tweet!