diff --git a/src/content/docs/en/concepts/why-astro.mdx b/src/content/docs/en/concepts/why-astro.mdx
index 169178283e93a..759ba2f542478 100644
--- a/src/content/docs/en/concepts/why-astro.mdx
+++ b/src/content/docs/en/concepts/why-astro.mdx
@@ -75,6 +75,6 @@ One of our favorite sayings is: **opt-in to complexity.** We designed Astro to r
**Astro is an all-in-one web framework that comes with everything you need to build a website.** Astro includes a component syntax, file-based routing, asset handling, a build process, bundling, optimizations, data-fetching, and more. You can build great websites without ever reaching outside of Astro's core feature set.
-If you need more control, you can extend Astro with over [100+ integrations](https://astro.build/integrations/) like [React](https://www.npmjs.com/package/@astrojs/react), [Svelte](https://www.npmjs.com/package/@astrojs/svelte), [Vue](https://www.npmjs.com/package/@astrojs/vue), [Tailwind CSS](https://www.npmjs.com/package/@astrojs/tailwind), [MDX](https://www.npmjs.com/package/@astrojs/mdx), [image optimizations](https://www.npmjs.com/package/@astrojs/image), and more. [Connect your favorite CMS](/en/guides/cms/) or [deploy to your favorite host](/en/guides/deploy/) with just a single command.
+If you need more control, you can extend Astro with over [100+ integrations](https://astro.build/integrations/) like [React](https://www.npmjs.com/package/@astrojs/react), [Svelte](https://www.npmjs.com/package/@astrojs/svelte), [Vue](https://www.npmjs.com/package/@astrojs/vue), [Tailwind CSS](https://www.npmjs.com/package/@astrojs/tailwind), [MDX](https://www.npmjs.com/package/@astrojs/mdx), and more. [Connect your favorite CMS](/en/guides/cms/) or [deploy to your favorite host](/en/guides/deploy/) with just a single command.
Astro is UI-agnostic, meaning you can **Bring Your Own UI Framework (BYOF)**. React, Preact, Solid, Svelte, Vue, and Lit are all officially supported in Astro. You can even mix and match different frameworks on the same page, making future migrations easier and preventing project lock-in to a single framework.
diff --git a/src/content/docs/en/core-concepts/endpoints.mdx b/src/content/docs/en/core-concepts/endpoints.mdx
index 157444ea56bf6..4cfc987ee27b7 100644
--- a/src/content/docs/en/core-concepts/endpoints.mdx
+++ b/src/content/docs/en/core-concepts/endpoints.mdx
@@ -10,33 +10,30 @@ 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
// Outputs: /builtwith.json
-export async function get({params, request}) {
- return {
- body: JSON.stringify({
+export async function GET({params, request}) {
+ return new Response(
+ JSON.stringify({
name: 'Astro',
- url: 'https://astro.build/',
- }),
- };
+ url: 'https://astro.build/'
+ })
+ )
}
```
-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}
-export async function get({ params, request }) {
+```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");
- const buffer = Buffer.from(await response.arrayBuffer());
- return {
- body: buffer,
- encoding: 'binary',
- };
+ return new Response(await response.arrayBuffer());
}
```
@@ -45,8 +42,7 @@ You can also type your endpoint functions using the `APIRoute` type:
```ts
import type { APIRoute } from 'astro';
-export const get: APIRoute = async ({ params, request }) => {
-...
+export const GET: APIRoute = async ({ params, request }) => {...}
```
### `params` and Dynamic routing
@@ -56,45 +52,47 @@ 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 }) => {
+export const GET: APIRoute = ({ params, request }) => {
const id = params.id;
- return {
- body: JSON.stringify({
+ return new Response(
+ JSON.stringify({
name: usernames[id]
})
- }
-};
+ )
+}
-export function getStaticPaths () {
+export function getStaticPaths() {
return [
{ 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"
import type { APIRoute } from 'astro';
-export const get: APIRoute = ({ params, request }) => {
- return {
- body: JSON.stringify({
+export const GET: APIRoute = ({ params, request }) => {
+ return new Response(JSON.stringify({
path: new URL(request.url).pathname
})
- };
+ )
}
```
## 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.
@@ -109,7 +107,7 @@ Server endpoints can access `params` without exporting `getStaticPaths`, and the
```js title="src/pages/[id].json.js"
import { getProduct } from '../db';
-export async function get({ params }) {
+export async function GET({ params }) {
const id = params.id;
const product = await getProduct(id);
@@ -120,12 +118,14 @@ export async function get({ params }) {
});
}
- return new Response(JSON.stringify(product), {
- status: 200,
- headers: {
- "Content-Type": "application/json"
+ return new Response(
+ JSON.stringify(product), {
+ status: 200,
+ headers: {
+ "Content-Type": "application/json"
+ }
}
- });
+ );
}
```
@@ -134,7 +134,7 @@ This will respond to any request that matches the dynamic route. For example, if
In SSR mode, certain providers require the `Content-Type` header to return an image. In this case, use a `Response` object to specify a `headers` property. For example, to produce a binary `.png` image:
```ts title="src/pages/astro-logo.png.ts"
-export async function get({ params, request }) {
+export async function GET({ params, request }) {
const response = await fetch("https://docs.astro.build/assets/full-logo-light.png");
const buffer = Buffer.from(await response.arrayBuffer());
return new Response(buffer, {
@@ -144,55 +144,49 @@ 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).
+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.
-:::note
-Since `delete` is a reserved word in JavaScript, export a `del` function to match the delete method.
-:::
+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).
```ts title="src/pages/methods.json.ts"
-export const get: APIRoute = ({ params, request }) => {
- return {
- body: JSON.stringify({
+export const GET: APIRoute = ({ params, request }) => {
+ return new Response(JSON.stringify({
message: "This was a GET!"
})
- }
-};
+ )
+}
-export const post: APIRoute = ({ request }) => {
- return {
- body: JSON.stringify({
+export const POST: APIRoute = ({ request }) => {
+ return new Response(JSON.stringify({
message: "This was a POST!"
})
- }
+ )
}
-export const del: APIRoute = ({ request }) => {
- return {
- body: JSON.stringify({
+export const DELETE: APIRoute = ({ request }) => {
+ return new Response(JSON.stringify({
message: "This was a DELETE!"
})
- }
+ )
}
-export const all: APIRoute = ({ request }) => {
- return {
- body: JSON.stringify({
+export const ALL: APIRoute = ({ request }) => {
+ return new Resonse(JSON.stringify({
message: `This was a ${request.method}!`
})
- }
+ )
}
```
-### `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"
-export const post: APIRoute = async ({ request }) => {
+export const POST: APIRoute = async ({ request }) => {
if (request.headers.get("Content-Type") === "application/json") {
const body = await request.json();
const name = body.name;
@@ -207,12 +201,13 @@ 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}
import { getLinkUrl } from '../db';
-export async function get({ params, redirect }) {
+export async function GET({ params, redirect }) {
const { id } = params;
const link = await getLinkUrl(id);
diff --git a/src/content/docs/en/core-concepts/project-structure.mdx b/src/content/docs/en/core-concepts/project-structure.mdx
index 57d63aca83613..fada6522aac07 100644
--- a/src/content/docs/en/core-concepts/project-structure.mdx
+++ b/src/content/docs/en/core-concepts/project-structure.mdx
@@ -66,10 +66,6 @@ Some files (like Astro components) are not even sent to the browser as written b
While this guide describes some popular conventions used in the Astro community, the only directories reserved by Astro are `src/pages/` and `src/content/`. You are free to rename and reorganize any other directories in a way that works best for you.
:::
-### `src/assets`
-
-The [`src/assets`](/en/guides/assets/) directory is the recommended folder to use for storing assets (e.g. images) that are processed by Astro. This is not required, and this is not a special reserved folder.
-
### `src/components`
**Components** are reusable units of code for your HTML pages. These could be [Astro components](/en/core-concepts/astro-components/), or [UI framework components](/en/core-concepts/framework-components/) like React or Vue. It is common to group and organize all of your project components together in this folder.
diff --git a/src/content/docs/en/guides/assets.mdx b/src/content/docs/en/guides/assets.mdx
deleted file mode 100644
index 96d05cfe90a43..0000000000000
--- a/src/content/docs/en/guides/assets.mdx
+++ /dev/null
@@ -1,404 +0,0 @@
----
-title: Assets (Experimental)
-description: Learn how to enable experimental asset support in Astro.
-i18nReady: false
----
-import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
-
-**Built-in optimized asset support** is enabled in Astro behind an experimental flag. This built-in feature will eventually replace the optional `@astrojs/image` integration.
-
-The new assets experience currently features:
-
-- A new built-in `` component
-- Relative images with automatic optimization in Markdown, [MDX](/en/guides/integrations-guide/mdx/), and [Markdoc](/en/guides/integrations-guide/markdoc/)
-- Integration with content collections
-- Improved error messages and types
-
-:::caution
-Assets are an experimental Astro feature introduced in v2.1. This API is subject to change before it is marked as stable.
-:::
-
-## Enabling Assets in your Project
-
-Enabling assets may cause some breaking changes in your project. It may also require some manual changes to take advantage of new features.
-
-Please check every section below to avoid errors and to get the most out of using the experimental assets option!
-
-### Update Config
-
-To enable built-in asset support, add the following lines to your `astro.config.mjs` configuration file:
-
-```js title="astro.config.mjs" ins={4-6}
-import { defineConfig } from 'astro/config';
-
-export default defineConfig({
- experimental: {
- assets: true
- }
-});
-```
-
-When you next run Astro, it will update your `src/env.d.ts` file to configure types for you. To do this manually, replace the `astro/client` reference with `astro/client-image`:
-
-```ts title="src/env.d.ts" del={1} ins={2}
-///
-///
-```
-
-### Move your images to `src/assets/`
-
-Create `src/assets/`, which Astro will recognize as your new assets folder.
-
-We recommend storing all images to be optimized in the `src/assets/` directory to make use of our official `~/assets` alias, although this location is optional. If you don't know where to put your images, or if you're building a product around Astro (e.g. a CMS), you can put your images there and we promise we won't break them! But, images can be stored anywhere, including alongside your content, if you prefer.
-
-Your images can be used by components (`.astro`, `.mdx`, and other UI frameworks) and in Markdown files.
-
-### Update existing `` tags
-
-Previously, importing an image would return a simple `string` with the path of the image. With the new `image` features enabled, imported image assets now match the following signature:
-
-```ts
-interface ImageMetadata {
- src: string;
- width: number;
- height: number;
- format: string;
-}
-```
-
-You must update the `src` attribute of any existing `` tags, and you may also update other attributes that are now available to you from the imported image.
-
-```astro title="src/components/MyComponent.astro" ".src" ".width" ".height" del={2,5} ins={3,6}
----
-import rocket from '../images/rocket.svg';
-import rocket from '../assets/images/rocket.svg'
----
-
-
-```
-
-### Update your Markdown, MDX, and Markdoc files
-
-Relative images can now be referenced in Markdown, MDX, and Markdoc files. These will automatically be optimized and hashed by Astro's build process.
-
-This allows you to move your images from the `public/` directory to the new, reserved `src/assets/` directory or move them near your Markdown, MDX, or Markdoc files. (See the URL path of these built images in the example below.)
-
-Your existing images in `public/` are still valid but are not automatically optimized by Astro's build process.
-
-```md title="src/pages/posts/post-1.md" "/_astro" ".hash" "../../assets/"
-# My Markdown Page
-
-
-![A starry night sky.](../../assets/stars.png)
-
-
-
-![Astro logo](https://docs.astro.build/assets/logomark-light.png)
-
-
-
-![A starry night sky.](/images/stars.png)
-
-```
-
-### Convert from `@astrojs/image`
-
-**Built-in asset support is incompatible with the `@astrojs/image` integration.**
-
-:::note[cropping images]
-The Assets API does not support image cropping. The current behaviour is to resize images to fit.
-
-Use the `@astrojs/image` integration if you need support for cropping images. Alternatively, you can use the [`object-fit` CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) to achieve a similar result.
-:::
-
-To avoid errors in your project, complete the following steps:
-
-1. Remove the `@astrojs/image` integration.
-
- You must [remove the integration](/en/guides/integrations-guide/#removing-an-integration) by uninstalling and then removing it from your `astro.config.mjs` file.
-
-2. Migrate any existing `` components.
-
- Change all `import` statements from `@astrojs/image/components` to `astro:assets` to use the new built-in `` component.
-
- Remove any component attributes that are not [currently supported image asset properties](#properties).
-
- For example `aspectRatio` is no longer supported, as it is now automatically inferred from the `width` and `height` attributes.
-
- ```astro title="src/components/MyComponent.astro" del= {2,11} ins={3}
- ---
- import { Image } from '@astrojs/image/components';
- import { Image } from 'astro:assets'
- import localImage from "../assets/logo.png";
- const localAlt = "The Astro Logo";
- ---
-
-
- ```
-
-
-3. Remove any existing `` components
-
- Currently, the built-in assets feature does not include a `` component.
-
- Instead, you can use the HTML image attributes `srcset` and `sizes` or the `