From a968374fb3cbf5d8c76192b8283bd213fc335001 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Mon, 29 Jul 2024 15:52:40 +0200 Subject: [PATCH 01/25] fix(api-reference): add missing Since and default in paginate section * Add default for `page.size` and `pageSize` (see https://github.com/withastro/astro/pull/11561) * Add missing Since for `page.url.first` and `page.url.last` (see https://github.com/withastro/astro/pull/11176) --- src/content/docs/en/reference/api-reference.mdx | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index 4a1f7addfb615..f6ebca53e178a 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -925,7 +925,7 @@ const { page } = Astro.props; - `/posts/[...page].astro` would generate the URLs `/posts`, `/posts/2`, `/posts/3`, etc. `paginate()` has the following arguments: -- `pageSize` - The number of items shown per page +- `pageSize` - The number of items shown per page (`10` by default) - `params` - Send additional parameters for creating dynamic routes - `props` - Send additional props to be available on each page @@ -960,7 +960,8 @@ Index of last item on current page. ##### `page.size`

-**Type:** `number` +**Type:** `number` +**Default:** `10`

How many items per-page. @@ -1015,6 +1016,8 @@ Get the URL of the next page (will be `undefined` if no more pages). If a value ##### `page.url.first` +

+

**Type:** `string | undefined`

@@ -1023,6 +1026,8 @@ Get the URL of the first page (will be `undefined` if on page 1). If a value is ##### `page.url.last` +

+

**Type:** `string | undefined`

From 5630a1d98a9924bf14a1d7fed3e1d5e44efaedc8 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Mon, 29 Jul 2024 16:27:55 +0200 Subject: [PATCH 02/25] fix(api-reference): update MarkdownInstance interface * Add missing properties (`rawContent`, `compiledContent` and `default`) --- src/content/docs/en/reference/api-reference.mdx | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index f6ebca53e178a..2c895e45dedc2 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -52,14 +52,19 @@ Markdown files have the following interface: export interface MarkdownInstance> { /* Any data specified in this file's YAML frontmatter */ frontmatter: T; - /* The file path of this file */ + /* The absolute file path of this file */ file: string; /* The rendered path of this file */ url: string | undefined; /* Astro Component that renders the contents of this file */ Content: AstroComponent; + /** Raw Markdown file content, excluding layout HTML and YAML frontmatter */ + rawContent(): string; + /** Markdown file compiled to HTML, excluding layout HTML */ + compiledContent(): string; /* Function that returns an array of the h1...h6 elements in this file */ getHeadings(): Promise<{ depth: number; slug: string; text: string }[]>; + default: AstroComponentFactory; } ``` From 061d4b84dcf499c73bf06c34d8e18ced41a1d8a8 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Mon, 29 Jul 2024 16:34:56 +0200 Subject: [PATCH 03/25] fix(api-reference): update Astro.cookies types * Fix inaccurate types for Astro.cookies `get` and `set` methods * Add missing `merge` method for Astro.cookies (the `AstroCookies` return type could miss some documentation) * Fix inaccurate type for AstroCookie `value` I did not updated the name of the options types, but all of them should be prefixed with `Astro`. I don't know if this is deliberate or an oversight during an update. See: `packages/astro/src/core/cookies/cookies.ts` --- src/content/docs/en/reference/api-reference.mdx | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index 2c895e45dedc2..a9ed0aaf2ee4a 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -216,7 +216,7 @@ Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;'); ##### `get`

-**Type:** `(key: string, options?: CookieGetOptions) => AstroCookie` +**Type:** `(key: string, options?: CookieGetOptions) => AstroCookie | undefined`

Gets the cookie as an [`AstroCookie`](#astrocookie) object, which contains the `value` and utility functions for converting the cookie to non-string types. @@ -224,7 +224,7 @@ Gets the cookie as an [`AstroCookie`](#astrocookie) object, which contains the ` ##### `has`

-**Type:** `(key: string) => boolean` +**Type:** `(key: string, options?: CookieGetOptions) => boolean`

Whether this cookie exists. If the cookie has been set via `Astro.cookies.set()` this will return true, otherwise it will check cookies in the `Astro.request`. @@ -232,7 +232,7 @@ Whether this cookie exists. If the cookie has been set via `Astro.cookies.set()` ##### `set`

-**Type:** `(key: string, value: string | number | boolean | object, options?: CookieSetOptions) => void` +**Type:** `(key: string, value: string | object, options?: CookieSetOptions) => void`

Sets the cookie `key` to the given value. This will attempt to convert the cookie value to a string. Options provide ways to set [cookie features](https://www.npmjs.com/package/cookie#options-1), such as the `maxAge` or `httpOnly`. @@ -247,6 +247,14 @@ Invalidates a cookie by setting the expiration date in the past (0 in Unix time) Once a cookie is "deleted" (expired), `Astro.cookies.has()` will return `false` and `Astro.cookies.get()` will return an [`AstroCookie`](#astrocookie) with a `value` of `undefined`. Options available when deleting a cookie are: `domain`, `path`, `httpOnly`, `sameSite`, and `secure`. +##### `merge` + +

+**Type:** `(cookies: AstroCookies) => void` +

+ +Merges a new `AstroCookies` instance into the current instance. Any new cookies will be added to the current instance, overwriting any existing cookies with the same name. + ##### `headers`

@@ -262,7 +270,7 @@ Getting a cookie via `Astro.cookies.get()` returns a `AstroCookie` type. It has ##### `value`

-**Type:** `string | undefined` +**Type:** `string`

The raw string value of the cookie. From 32554a2c911c08bab9a6965fbeccd7f52c08c3be Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Mon, 29 Jul 2024 16:52:14 +0200 Subject: [PATCH 04/25] fix(api-reference): remove Astro.canonicalURL It was deprecated but it has been removed in v2.0.0 (see https://github.com/withastro/astro/pull/5707). I think it should not be displayed in the reference anymore since we are now at v4.12.1 --- src/content/docs/en/reference/api-reference.mdx | 8 -------- 1 file changed, 8 deletions(-) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index a9ed0aaf2ee4a..83e4cff481b57 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -410,14 +410,6 @@ if (!isLoggedIn(cookie)) { --- ``` -### `Astro.canonicalURL` - -:::caution[Deprecated] -Use [`Astro.url`](#astrourl) to construct your own canonical URL. -::: - -The [canonical URL][canonical] of the current page. - ### `Astro.url`

From f863f7264644591d76728e46506256293658a9e4 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Mon, 29 Jul 2024 17:46:30 +0200 Subject: [PATCH 05/25] fix(api-reference): add missing Since/Type in Astro global & APIContext * See https://github.com/withastro/astro/pull/4986 for `site`, `generator`, `url`, `clientAddress`, `props` and `redirect` * See https://github.com/withastro/astro/pull/6721 for `locals` * See https://github.com/withastro/astro/pull/9021 for `preferredLocale` and `preferredLocaleList` * See https://github.com/withastro/astro/pull/9101 for `currentLocale` --- .../docs/en/reference/api-reference.mdx | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index 83e4cff481b57..3e9baecd4149c 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -165,6 +165,8 @@ See also: [`params`](#params) ### `Astro.request` +**Type:** `Request` + `Astro.request` is a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. It can be used to get the `url`, `headers`, `method`, and even body of the request. ```astro @@ -180,6 +182,7 @@ With the default `output: 'static'` option, `Astro.request.url` does not contain ### `Astro.response` +**Type:** `ResponseInit & { readonly headers: Headers }` `Astro.response` is a standard `ResponseInit` object. It has the following structure. @@ -211,6 +214,8 @@ Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;');

+**Type:** `AstroCookies` + `Astro.cookies` contains utilities for reading and manipulating cookies in [server-side rendering](/en/guides/server-side-rendering/) mode. ##### `get` @@ -414,6 +419,8 @@ if (!isLoggedIn(cookie)) {

+**Type:** `URL` + A [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) object constructed from the current `Astro.request.url` URL string value. Useful for interacting with individual properties of the request URL, like pathname and origin. Equivalent to doing `new URL(Astro.request.url)`. @@ -441,6 +448,8 @@ const socialImageURL = new URL('/images/preview.png', Astro.url);

+**Type:** `string` + Specifies the [IP address](https://en.wikipedia.org/wiki/IP_address) of the request. This property is only available when building for SSR (server-side rendering) and should not be used for static sites. ```astro @@ -453,12 +462,16 @@ const ip = Astro.clientAddress; ### `Astro.site` +**Type:** `URL | undefined` + `Astro.site` returns a `URL` made from `site` in your Astro config. If `site` in your Astro config isn't defined, `Astro.site` won't be defined. ### `Astro.generator`

+**Type:** `string` + `Astro.generator` is a convenient way to add a [``](https://html.spec.whatwg.org/multipage/semantics.html#meta-generator) tag with your current version of Astro. It follows the format `"Astro v1.x.x"`. ```astro mark="Astro.generator" @@ -593,6 +606,8 @@ And would render HTML like this: ### `Astro.locals` +

+ `Astro.locals` is an object containing any values from the [`context.locals`](#contextlocals) object from a middleware. Use this to access data returned by middleware in your `.astro` files. ```astro title="src/pages/Orders.astro" @@ -610,6 +625,10 @@ const orders = Array.from(Astro.locals.orders.entries()); ### `Astro.preferredLocale` +

+ +**Type:** `string | undefined` + `Astro.preferredLocale` is a computed value that represents the preferred locale of the user. It is computed by checking the configured locales in your `i18n.locales` array and locales supported by the users's browser via the header `Accept-Language`. This value is `undefined` if no such match exists. @@ -618,6 +637,10 @@ This property is only available when building for SSR (server-side rendering) an ### `Astro.preferredLocaleList` +

+ +**Type:** `string[] | undefined` + `Astro.preferredLocaleList` represents the array of all locales that are both requested by the browser and supported by your website. This produces a list of all compatible languages between your site and your visitor. If none of the browser's requested languages are found in your locales array, then the value is `[]`: you do not support any of your visitor's preferred locales. @@ -628,6 +651,10 @@ This property is only available when building for SSR (server-side rendering) an ### `Astro.currentLocale` +

+ +**Type:** `string | undefined` + The locale computed from the current URL, using the syntax specified in your `locales` configuration. If the URL does not contain a `/[locale]/` prefix, then the value will default to `i18n.defaultLocale`. ## Endpoint Context @@ -672,6 +699,8 @@ See also: [`params`](#params) ### `context.props` +

+ `context.props` is an object containing any `props` passed from `getStaticPaths()`. Because `getStaticPaths()` is not used when building for SSR (server-side rendering), `context.props` is only available in static builds. ```ts title="src/pages/posts/[id].json.ts" @@ -696,6 +725,8 @@ See also: [Data Passing with `props`](#data-passing-with-props) ### `context.request` +**Type:** `Request` + A standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. It can be used to get the `url`, `headers`, `method`, and even body of the request. ```ts @@ -710,18 +741,28 @@ See also: [Astro.request](#astrorequest) ### `context.cookies` +**Type:** `AstroCookies` + `context.cookies` contains utilities for reading and manipulating cookies. See also: [Astro.cookies](#astrocookies) ### `context.url` +

+ +**Type:** `URL` + A [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) object constructed from the current `context.request.url` URL string value. See also: [Astro.url](#astrourl) ### `context.clientAddress` +

+ +**Type:** `string` + Specifies the [IP address](https://en.wikipedia.org/wiki/IP_address) of the request. This property is only available when building for SSR (server-side rendering) and should not be used for static sites. ```ts @@ -737,12 +778,20 @@ See also: [Astro.clientAddress](#astroclientaddress) ### `context.site` +

+ +**Type:** `URL | undefined` + `context.site` returns a `URL` made from `site` in your Astro config. If undefined, this will return a URL generated from `localhost`. See also: [Astro.site](#astrosite) ### `context.generator` +

+ +**Type:** `string` + `context.generator` is a convenient way to indicate the version of Astro your project is running. It follows the format `"Astro v1.x.x"`. ```ts title="src/pages/site-info.json.ts" @@ -758,6 +807,10 @@ See also: [Astro.generator](#astrogenerator) ### `context.redirect()` +

+ +**Type:** `(path: string, status?: number) => Response` + `context.redirect()` returns a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) object that allows you to redirect to another page. This function is only available when building for SSR (server-side rendering) and should not be used for static sites. ```ts @@ -772,6 +825,8 @@ See also: [`Astro.redirect()`](#astroredirect) ### `context.locals` +

+ `context.locals` is an object used to store and access arbitrary information during the lifecycle of a request. Middleware functions can read and write the values of `context.locals`: From 6c4017cad3bcbe459ede4454421efaf9be2828c3 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Mon, 29 Jul 2024 18:16:31 +0200 Subject: [PATCH 06/25] fix(api-reference): add getStaticPaths type --- src/content/docs/en/reference/api-reference.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index 3e9baecd4149c..ae1201fb92990 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -856,6 +856,8 @@ See also: [`Astro.locals`](#astrolocals) ## `getStaticPaths()` +**Type:** `(options: GetStaticPathsOptions) => Promise | GetStaticPathsResult` + If a page uses dynamic params in the filename, that component will need to export a `getStaticPaths()` function. This function is required because Astro is a static site builder. That means that your entire site is built ahead of time. If Astro doesn't know to generate a page at build time, your users won't see it when they visit your site. From 8025c4d9e61138c3f4119b22cb92cc76ec1d7a7a Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Mon, 29 Jul 2024 19:22:48 +0200 Subject: [PATCH 07/25] fix(api-reference): add missing Since and Types in Content collections * See https://github.com/withastro/astro/pull/7607 for the most recent exported types * See https://github.com/withastro/astro/pull/6850 for `reference()` * See `packages/astro/types/content.d.ts` for `schema` type (might need a refactor) * `getDataEntryById` is missing but since `getEntryBySlug` is announced as deprecated I don't know if we should add it (so no change here) --- src/content/docs/en/reference/api-reference.mdx | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index ae1201fb92990..96b578a0f9e41 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -1149,6 +1149,8 @@ Content collections offer APIs to configure and query your Markdown or MDX docum ### `defineCollection()` +**Type:** `(input: CollectionConfig) => CollectionConfig` + `defineCollection()` is a utility to configure a collection in a `src/content/config.*` file. ```ts @@ -1187,7 +1189,7 @@ This means collections **cannot** store a mix of content and data formats. You m #### `schema` -**Type:** `TSchema extends ZodType` +**Type:** `TSchema extends ZodType | (context: SchemaContext) => TSchema extends ZodType` `schema` is an optional Zod object to configure the type and shape of document frontmatter for a collection. Each value must use [a Zod validator](https://github.com/colinhacks/zod). @@ -1195,6 +1197,8 @@ This means collections **cannot** store a mix of content and data formats. You m ### `reference()` +

+ **Type:** `(collection: string) => ZodEffects` The `reference()` function is used in the content config to define a relationship, or "reference," from one collection to another. This accepts a collection name and validates the entry identifier(s) specified in your content frontmatter or data file. @@ -1395,6 +1399,8 @@ The `astro:content` module also exports the following types for use in your Astr #### `CollectionKey` +

+ A string union of all collection names defined in your `src/content/config.*` file. This type can be useful when defining a generic function that accepts any collection name. ```ts @@ -1407,10 +1413,14 @@ async function getCollection(collection: CollectionKey) { #### `ContentCollectionKey` +

+ A string union of all the names of `type: 'content'` collections defined in your `src/content/config.*` file. #### `DataCollectionKey` +

+ A string union of all the names of `type: 'data'` collection defined in your `src/content/config.*` file. #### `SchemaContext` From e8da5a39fb77de3a6c14fe1e7ca7e30ef54bdb7f Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Mon, 29 Jul 2024 21:32:05 +0200 Subject: [PATCH 08/25] fix(api-reference): add missing Types and Since in Middleware section * Add missing Since (see https://github.com/withastro/astro/pull/7578 for `createContext` and `trySerializeLocals` * Add missing types (see `packages/astro/src/core/build/types.ts` and `packages/astro/src/@types/astro.ts`) --- src/content/docs/en/reference/api-reference.mdx | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index 96b578a0f9e41..a9acce5bc8124 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -1458,6 +1458,8 @@ Middleware allows you to intercept requests and responses and inject behaviors d ### `onRequest()` +**Type:** `(context: APIContext, next: MiddlewareNext) => Promise | Response | Promise | void` + A required exported function from `src/middleware.js` that will be called before rendering every page or API route. It accepts two optional arguments: [context](#contextlocals) and [next()](#next). `onRequest()` must return a `Response`: either directly, or by calling `next()`. ```js title="src/middleware.js" @@ -1471,6 +1473,8 @@ export function onRequest (context, next) { ### `next()` +**Type:** `(rewritePayload?: RewritePayload) => Promise` + A function that intercepts (reads and modifies) the `Response` of a `Request` or calls the "next" middleware in the chain and returns a `Response`. For example, this function could modify the HTML body of a response. This is an optional argument of `onRequest()`, and may provide the required `Response` returned by the middleware. @@ -1478,6 +1482,8 @@ This is an optional argument of `onRequest()`, and may provide the required `Res ### `sequence()` +**Type:** `(...handlers: MiddlewareHandler[]) => MiddlewareHandler` + A function that accepts middleware functions as arguments, and will execute them in the order in which they are passed. ```js title="src/middleware.js" @@ -1492,12 +1498,20 @@ export const onRequest = sequence(validation, auth, greeting); ### `createContext()` +

+ +**Type:** `(context: CreateContext) => APIContext` + A low-level API to create an [`APIContext`](#endpoint-context)to be passed to an Astro middleware `onRequest()` function. This function can be used by integrations/adapters to programmatically execute the Astro middleware. ### `trySerializeLocals()` +

+ +**Type:** `(value: unknown) => string` + 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. ## Internationalization (`astro:i18n`) From 4ec94b1aea9a1164962eac79a7d992e3c10aeca9 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Mon, 29 Jul 2024 21:46:00 +0200 Subject: [PATCH 09/25] fix(api-reference): rewrite Types in Internationalization section * Make Types in Internationalization section consistent with other declared functions types --- .../docs/en/reference/api-reference.mdx | 23 +++++++++---------- 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index a9acce5bc8124..f7be252d1d3d5 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -1533,7 +1533,7 @@ For features and usage examples, [see our i18n routing guide](/en/guides/interna ### `getRelativeLocaleUrl()` -`getRelativeLocaleUrl(locale: string, path?: string, options?: GetLocaleOptions): string` +**Type:** `(locale: string, path?: string, options?: GetLocaleOptions) => string` Use this function to retrieve a relative path for a locale. If the locale doesn't exist, Astro throws an error. @@ -1563,7 +1563,7 @@ getRelativeLocaleUrl("fr_CA", "getting-started", { ### `getAbsoluteLocaleUrl()` -`getAbsoluteLocaleUrl(locale: string, path: string, options?: GetLocaleOptions): string` +**Type:** `(locale: string, path: string, options?: GetLocaleOptions) => string` Use this function to retrieve an absolute path for a locale when [`site`] has a value. If [`site`] isn't configured, the function returns a relative URL. If the locale doesn't exist, Astro throws an error. @@ -1596,21 +1596,20 @@ getAbsoluteLocaleUrl("fr_CA", "getting-started", { ### `getRelativeLocaleUrlList()` -`getRelativeLocaleUrlList(path?: string, options?: GetLocaleOptions): string[]` - +**Type:** `(path?: string, options?: GetLocaleOptions) => string[]` Use this like [`getRelativeLocaleUrl`](#getrelativelocaleurl) to return a list of relative paths for all the locales. ### `getAbsoluteLocaleUrlList()` -`getAbsoluteLocaleUrlList(path?: string, options?: GetLocaleOptions): string[]` +**Type:** `(path?: string, options?: GetLocaleOptions) => string[]` Use this like [`getAbsoluteLocaleUrl`](/en/guides/internationalization/#custom-locale-paths) to return a list of absolute paths for all the locales. ### `getPathByLocale()` -`getPathByLocale(locale: string): string` +**Type:** `(locale: string) => string` A function that returns the `path` associated to one or more `codes` when [custom locale paths](/en/guides/internationalization/#custom-locale-paths) are configured. @@ -1634,7 +1633,7 @@ getPathByLocale("fr-CA"); // returns "french" ### `getLocaleByPath` - `getLocaleByPath(path: string): string` +*Type:** `(path: string) => string` A function that returns the `code` associated to a locale `path`. @@ -1657,7 +1656,7 @@ getLocaleByPath("french"); // returns "fr" because that's the first code configu ### `redirectToDefaultLocale()` -`redirectToDefaultLocale(context: APIContext, statusCode?: ValidRedirectStatus): Promise` +**Type:** `(context: APIContext, statusCode?: ValidRedirectStatus) => Promise`

@@ -1682,7 +1681,7 @@ export const onRequest = defineMiddleware((context, next) => { ### `redirectToFallback()` -`redirectToFallback(context: APIContext, response: Response): Promise` +**Type:** `(context: APIContext, response: Response) => Promise`

@@ -1707,7 +1706,7 @@ export const onRequest = defineMiddleware(async (context, next) => { ### `notFound()` -`notFound(context: APIContext, response: Response): Promise` +**Type:** `(context: APIContext, response?: Response) => Promise | undefined`

@@ -1736,7 +1735,7 @@ export const onRequest = defineMiddleware((context, next) => { ### `middleware()` -`middleware(options: { prefixDefaultLocale: boolean, redirectToDefaultLocale: boolean })` +**Type:** `(options: { prefixDefaultLocale: boolean, redirectToDefaultLocale: boolean }) => MiddlewareHandler`

@@ -1769,7 +1768,7 @@ export const onRequest = sequence(customLogic, middleware({ ### `requestHasLocale()` -`requestHasLocale(context: APIContext): boolean` +**Type:** `(context: APIContext) => boolean`

From d46cbb891b568e979a5fb45b1a9f3f3e000c7574 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Mon, 29 Jul 2024 21:54:53 +0200 Subject: [PATCH 10/25] fix(api-reference): add missing Since for ViewTransitions built-in --- src/content/docs/en/reference/api-reference.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index f7be252d1d3d5..7ff4b5c701c39 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -2004,6 +2004,8 @@ const { Content } = await entry.render(); ### `` +

+ Opt in to using view transitions on individual pages by importing and adding the `` routing component to `` on every desired page. ```astro title="src/pages/index.astro" ins={2,7} From b8bb6008b712c6723e174c7cae934036d56c2700 Mon Sep 17 00:00:00 2001 From: Armand Philippot <59021693+ArmandPhilippot@users.noreply.github.com> Date: Thu, 1 Aug 2024 15:17:33 +0200 Subject: [PATCH 11/25] add link to documented SchemaContext type Co-authored-by: Chris Swithinbank --- src/content/docs/en/reference/api-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index 7ff4b5c701c39..9060b468f8d73 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -1189,7 +1189,7 @@ This means collections **cannot** store a mix of content and data formats. You m #### `schema` -**Type:** `TSchema extends ZodType | (context: SchemaContext) => TSchema extends ZodType` +**Type:** ZodType | (context: SchemaContext) => ZodType `schema` is an optional Zod object to configure the type and shape of document frontmatter for a collection. Each value must use [a Zod validator](https://github.com/colinhacks/zod). From 7e52d897b57a0c36aa1299de9b7e6deb5a7f0d9f Mon Sep 17 00:00:00 2001 From: Armand Philippot <59021693+ArmandPhilippot@users.noreply.github.com> Date: Thu, 1 Aug 2024 15:24:09 +0200 Subject: [PATCH 12/25] reword `merge` section Co-authored-by: Chris Swithinbank --- src/content/docs/en/reference/api-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index 9060b468f8d73..292b6d772c216 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -258,7 +258,7 @@ Once a cookie is "deleted" (expired), `Astro.cookies.has()` will return `false` **Type:** `(cookies: AstroCookies) => void`

-Merges a new `AstroCookies` instance into the current instance. Any new cookies will be added to the current instance, overwriting any existing cookies with the same name. +Merges a new `AstroCookies` instance into the current instance. Any new cookies will be added to the current instance and any cookies with the same name will overwrite existing values. ##### `headers` From d8956874ed9e046de7c1159be9fc15c082866deb Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Thu, 1 Aug 2024 15:42:59 +0200 Subject: [PATCH 13/25] fix(api-reference): add a redirection for #astrocanonicalurl section --- public/_redirects | 55 ++++++++++++++++++++++++----------------------- 1 file changed, 28 insertions(+), 27 deletions(-) diff --git a/public/_redirects b/public/_redirects index a1a72f2a44138..f1ad8a8ad744c 100644 --- a/public/_redirects +++ b/public/_redirects @@ -1,32 +1,33 @@ # Moved content # When moving a page, usually you’ll want to add a redirect to the bottom of this block. -/:lang/install/auto /:lang/install-and-setup/ -/:lang/install/manual /:lang/install-and-setup/ -/:lang/core-concepts/project-structure /:lang/basics/project-structure/ -/:lang/core-concepts/astro-components /:lang/basics/astro-components/ -/:lang/core-concepts/astro-pages /:lang/basics/astro-pages/ -/:lang/core-concepts/layouts /:lang/basics/layouts/ -/:lang/core-concepts/astro-syntax /:lang/basics/astro-syntax/ -/:lang/core-concepts/rendering-modes /:lang/basics/rendering-modes/ -/:lang/core-concepts/routing /:lang/guides/routing/ -/:lang/core-concepts/endpoints /:lang/guides/endpoints/ -/:lang/core-concepts/framework-components /:lang/guides/framework-components/ -/:lang/core-concepts/sharing-state /:lang/recipes/sharing-state-islands/ -/:lang/reference/dev-overlay-plugin-reference /:lang/reference/dev-toolbar-app-reference/ -/:lang/core-concepts/partial-hydration /:lang/concepts/islands/ -/:lang/guides/publish-to-npm /:lang/reference/publish-to-npm/ -/:lang/concepts/mpa-vs-spa /:lang/concepts/why-astro/ -/:lang/deploy/:service /:lang/guides/deploy/:service -/:lang/guides/deploy/layer-zero /:lang/guides/deploy/edgio/ -/:lang/guides/client-side-routing /:lang/guides/view-transitions/ -/:lang/guides/assets /:lang/guides/images/ -/en/guides/aliases /en/guides/imports/#aliases -/:lang/guides/aliases /:lang/guides/imports/ -/:lang/guides/integrations-guide/image /:lang/guides/images/ -/:lang/migration/0.21.0 /:lang/guides/upgrade-to/v1/ -/:lang/migrate /:lang/guides/upgrade-to/v1/ -/:lang/recipes/studio /:lang/guides/astro-db/ -/:lang/recipes /:lang/community-resources/content/ +/:lang/install/auto /:lang/install-and-setup/ +/:lang/install/manual /:lang/install-and-setup/ +/:lang/core-concepts/project-structure /:lang/basics/project-structure/ +/:lang/core-concepts/astro-components /:lang/basics/astro-components/ +/:lang/core-concepts/astro-pages /:lang/basics/astro-pages/ +/:lang/core-concepts/layouts /:lang/basics/layouts/ +/:lang/core-concepts/astro-syntax /:lang/basics/astro-syntax/ +/:lang/core-concepts/rendering-modes /:lang/basics/rendering-modes/ +/:lang/core-concepts/routing /:lang/guides/routing/ +/:lang/core-concepts/endpoints /:lang/guides/endpoints/ +/:lang/core-concepts/framework-components /:lang/guides/framework-components/ +/:lang/core-concepts/sharing-state /:lang/recipes/sharing-state-islands/ +/:lang/reference/dev-overlay-plugin-reference /:lang/reference/dev-toolbar-app-reference/ +/:lang/core-concepts/partial-hydration /:lang/concepts/islands/ +/:lang/guides/publish-to-npm /:lang/reference/publish-to-npm/ +/:lang/concepts/mpa-vs-spa /:lang/concepts/why-astro/ +/:lang/deploy/:service /:lang/guides/deploy/:service +/:lang/guides/deploy/layer-zero /:lang/guides/deploy/edgio/ +/:lang/guides/client-side-routing /:lang/guides/view-transitions/ +/:lang/guides/assets /:lang/guides/images/ +/en/guides/aliases /en/guides/imports/#aliases +/:lang/guides/aliases /:lang/guides/imports/ +/:lang/guides/integrations-guide/image /:lang/guides/images/ +/:lang/migration/0.21.0 /:lang/guides/upgrade-to/v1/ +/:lang/migrate /:lang/guides/upgrade-to/v1/ +/:lang/recipes/studio /:lang/guides/astro-db/ +/:lang/recipes /:lang/community-resources/content/ +/:lang:/reference/api-reference/#astrocanonicalurl /:lang:/reference/api-reference/#astrourl # Very old docs site redirects # Once upon a time these URLs existed, so we try to keep them meaning something. From 306d4a40c6594fe3f633b83683a69cc1b44f3e1c Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Thu, 1 Aug 2024 15:45:26 +0200 Subject: [PATCH 14/25] fix(api-reference): replace AstroComponent with AstroComponentFactory --- src/content/docs/en/reference/api-reference.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index 35df9fd387c2e..b6d18c984b513 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -57,7 +57,7 @@ export interface MarkdownInstance> { /* The rendered path of this file */ url: string | undefined; /* Astro Component that renders the contents of this file */ - Content: AstroComponent; + Content: AstroComponentFactory; /** Raw Markdown file content, excluding layout HTML and YAML frontmatter */ rawContent(): string; /** Markdown file compiled to HTML, excluding layout HTML */ @@ -94,7 +94,7 @@ export interface AstroInstance { file: string; /* The URL for this file (if it is in the pages directory) */ url: string | undefined; - default: AstroComponent; + default: AstroComponentFactory; } ``` From 2989037e72948b1e98f7b78e263ace2ed002f7d5 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Thu, 1 Aug 2024 15:48:27 +0200 Subject: [PATCH 15/25] fix(api-reference): add MD only mention on MarkdownInstance interface * Add "Markdown only" mention to `rawContent` and `compiledContent` * Reword the introductory line to index `MarkdownInstance` (see https://github.com/withastro/docs/pull/8943/#discussion_r1699978862) Co-authored-by: Chris Swithinbank --- src/content/docs/en/reference/api-reference.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index b6d18c984b513..13479c84e9d6d 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -46,7 +46,7 @@ Read more in the [Vite documentation](https://vitejs.dev/guide/features.html#glo ::: #### Markdown Files -Markdown files have the following interface: +Markdown files loaded with `Astro.glob()` return the following `MarkdownInstance` interface: ```ts export interface MarkdownInstance> { @@ -58,9 +58,9 @@ export interface MarkdownInstance> { url: string | undefined; /* Astro Component that renders the contents of this file */ Content: AstroComponentFactory; - /** Raw Markdown file content, excluding layout HTML and YAML frontmatter */ + /** (Markdown only) Raw Markdown file content, excluding layout HTML and YAML frontmatter */ rawContent(): string; - /** Markdown file compiled to HTML, excluding layout HTML */ + /** (Markdown only) Markdown file compiled to HTML, excluding layout HTML */ compiledContent(): string; /* Function that returns an array of the h1...h6 elements in this file */ getHeadings(): Promise<{ depth: number; slug: string; text: string }[]>; From 7a115e94fe186f00e4d664e8fd3e04d6a8de4631 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Thu, 1 Aug 2024 16:01:24 +0200 Subject: [PATCH 16/25] fix(api-reference): add Astro prefix to Cookies types * Replace `CookieGetOptions` with `AstroCookieGetOptions` * Replace `CookieSetOptions` with `AstroCookieSetOptions` * Replace `CookieDeleteOptions` with `AstroCookieDeleteOptions` * Add links to documented types inside `Type:` information --- src/content/docs/en/reference/api-reference.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index 13479c84e9d6d..e76231341388f 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -221,7 +221,7 @@ Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;'); ##### `get`

-**Type:** `(key: string, options?: CookieGetOptions) => AstroCookie | undefined` +**Type:** (key: string, options?: AstroCookieGetOptions) => AstroCookie | undefined

Gets the cookie as an [`AstroCookie`](#astrocookie) object, which contains the `value` and utility functions for converting the cookie to non-string types. @@ -229,7 +229,7 @@ Gets the cookie as an [`AstroCookie`](#astrocookie) object, which contains the ` ##### `has`

-**Type:** `(key: string, options?: CookieGetOptions) => boolean` +**Type:** (key: string, options?: AstroCookieGetOptions) => boolean

Whether this cookie exists. If the cookie has been set via `Astro.cookies.set()` this will return true, otherwise it will check cookies in the `Astro.request`. @@ -237,7 +237,7 @@ Whether this cookie exists. If the cookie has been set via `Astro.cookies.set()` ##### `set`

-**Type:** `(key: string, value: string | object, options?: CookieSetOptions) => void` +**Type:** (key: string, value: string | object, options?: AstroCookieSetOptions) => void

Sets the cookie `key` to the given value. This will attempt to convert the cookie value to a string. Options provide ways to set [cookie features](https://www.npmjs.com/package/cookie#options-1), such as the `maxAge` or `httpOnly`. @@ -245,7 +245,7 @@ Sets the cookie `key` to the given value. This will attempt to convert the cooki ##### `delete`

-**Type:** `(key: string, options?: CookieDeleteOptions) => void` +**Type:** `(key: string, options?: AstroCookieDeleteOptions) => void`

Invalidates a cookie by setting the expiration date in the past (0 in Unix time). @@ -304,11 +304,11 @@ Parses the cookie value as a Number. Returns NaN if not a valid number. Converts the cookie value to a boolean. -#### `CookieGetOptions` +#### `AstroCookieGetOptions`

-Getting a cookie also allows specifying options via the `CookieGetOptions` interface: +Getting a cookie also allows specifying options via the `AstroCookieGetOptions` interface: ##### `decode` @@ -318,11 +318,11 @@ Getting a cookie also allows specifying options via the `CookieGetOptions` inter Allows customization of how a cookie is deserialized into a value. -#### `CookieSetOptions` +#### `AstroCookieSetOptions`

-Setting a cookie via `Astro.cookies.set()` allows passing in a `CookieSetOptions` to customize how the cookie is serialized. +Setting a cookie via `Astro.cookies.set()` allows passing in a `AstroCookieSetOptions` to customize how the cookie is serialized. ##### `domain` From bd2d7da7054ba13f86a09ea79b1dbf037d092537 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Thu, 1 Aug 2024 16:34:27 +0200 Subject: [PATCH 17/25] style(api-reference): make Types/Default/Since formatting consistent From Astro Docs Docs, Types/Default/Since information should be in a single block (see https://contribute.docs.astro.build/reference/custom-components/#examples-1) I wrapped single information (e.g. Types) with a `

` tag to keep the block consistent and to help future contributors understand that the format must be the same if they add information. Also, I added an empty line after the opening `

` tag because of a possible parsing issue. See: 35d1f4b --- .../docs/en/reference/api-reference.mdx | 283 +++++++++++++----- 1 file changed, 211 insertions(+), 72 deletions(-) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index e76231341388f..fd2afa4376ca2 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -165,7 +165,10 @@ See also: [`params`](#params) ### `Astro.request` +

+ **Type:** `Request` +

`Astro.request` is a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. It can be used to get the `url`, `headers`, `method`, and even body of the request. @@ -182,7 +185,10 @@ With the default `output: 'static'` option, `Astro.request.url` does not contain ### `Astro.response` +

+ **Type:** `ResponseInit & { readonly headers: Headers }` +

`Astro.response` is a standard `ResponseInit` object. It has the following structure. @@ -212,15 +218,18 @@ Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;'); ### `Astro.cookies` -

+

-**Type:** `AstroCookies` +**Type:** `AstroCookies`
+ +

`Astro.cookies` contains utilities for reading and manipulating cookies in [server-side rendering](/en/guides/server-side-rendering/) mode. ##### `get`

+ **Type:** (key: string, options?: AstroCookieGetOptions) => AstroCookie | undefined

@@ -229,6 +238,7 @@ Gets the cookie as an [`AstroCookie`](#astrocookie) object, which contains the ` ##### `has`

+ **Type:** (key: string, options?: AstroCookieGetOptions) => boolean

@@ -237,6 +247,7 @@ Whether this cookie exists. If the cookie has been set via `Astro.cookies.set()` ##### `set`

+ **Type:** (key: string, value: string | object, options?: AstroCookieSetOptions) => void

@@ -245,6 +256,7 @@ Sets the cookie `key` to the given value. This will attempt to convert the cooki ##### `delete`

+ **Type:** `(key: string, options?: AstroCookieDeleteOptions) => void`

@@ -255,6 +267,7 @@ Once a cookie is "deleted" (expired), `Astro.cookies.has()` will return `false` ##### `merge`

+ **Type:** `(cookies: AstroCookies) => void`

@@ -263,6 +276,7 @@ Merges a new `AstroCookies` instance into the current instance. Any new cookies ##### `headers`

+ **Type:** `() => Iterator`

@@ -275,6 +289,7 @@ Getting a cookie via `Astro.cookies.get()` returns a `AstroCookie` type. It has ##### `value`

+ **Type:** `string`

@@ -283,6 +298,7 @@ The raw string value of the cookie. ##### `json`

+ **Type:** `() => Record`

@@ -291,6 +307,7 @@ Parses the cookie value via `JSON.parse()`, returning an object. Throws if the c ##### `number`

+ **Type:** `() => number`

@@ -299,6 +316,7 @@ Parses the cookie value as a Number. Returns NaN if not a valid number. ##### `boolean`

+ **Type:** `() => boolean`

@@ -327,22 +345,25 @@ Setting a cookie via `Astro.cookies.set()` allows passing in a `AstroCookieSetOp ##### `domain`

+ **Type:** `string`

Specifies the domain. If no domain is set, most clients will interpret to apply to the current domain. - ##### `expires` +##### `expires` + +

-

- **Type:** `Date` -

+**Type:** `Date` +

Specifies the date on which the cookie will expire. ##### `httpOnly`

+ **Type:** `boolean`

@@ -351,6 +372,7 @@ If true, the cookie will not be accessible client-side. ##### `maxAge`

+ **Type:** `number`

@@ -359,6 +381,7 @@ Specifies a number, in seconds, for which the cookie is valid. ##### `path`

+ **Type:** `string`

@@ -367,6 +390,7 @@ Specifies a subpath of the domain in which the cookie is applied. ##### `sameSite`

+ **Type:** `boolean | 'lax' | 'none' | 'strict'`

@@ -375,6 +399,7 @@ Specifies the value of the [SameSite](https://datatracker.ietf.org/doc/html/draf ##### `secure`

+ **Type:** `boolean`

@@ -383,6 +408,7 @@ If true, the cookie is only set on https sites. ##### `encode`

+ **Type:** `(value: string) => string`

@@ -390,7 +416,10 @@ Allows customizing how the cookie is serialized. ### `Astro.redirect()` +

+ **Type:** `(path: string, status?: number) => Response` +

Allows you to redirect to another page, and optionally provide an [HTTP response status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#redirection_messages) as a second parameter. @@ -417,9 +446,11 @@ if (!isLoggedIn(cookie)) { ### `Astro.rewrite()` -

+

-**Type:** `(rewritePayload: string | URL | Request) => Promise` +**Type:** `(rewritePayload: string | URL | Request) => Promise`
+ +

Allows you to serve content from a different URL or path without redirecting the browser to a new page. @@ -455,9 +486,11 @@ return Astro.rewrite(new Request(new URL("../", Astro.url), { ### `Astro.url` -

+

-**Type:** `URL` +**Type:** `URL`
+ +

A [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) object constructed from the current `Astro.request.url` URL string value. Useful for interacting with individual properties of the request URL, like pathname and origin. @@ -484,9 +517,11 @@ const socialImageURL = new URL('/images/preview.png', Astro.url); ### `Astro.clientAddress` -

+

-**Type:** `string` +**Type:** `string`
+ +

Specifies the [IP address](https://en.wikipedia.org/wiki/IP_address) of the request. This property is only available when building for SSR (server-side rendering) and should not be used for static sites. @@ -500,15 +535,20 @@ const ip = Astro.clientAddress; ### `Astro.site` +

+ **Type:** `URL | undefined` +

`Astro.site` returns a `URL` made from `site` in your Astro config. If `site` in your Astro config isn't defined, `Astro.site` won't be defined. ### `Astro.generator` -

+

-**Type:** `string` +**Type:** `string`
+ +

`Astro.generator` is a convenient way to add a [``](https://html.spec.whatwg.org/multipage/semantics.html#meta-generator) tag with your current version of Astro. It follows the format `"Astro v1.x.x"`. @@ -531,7 +571,10 @@ const ip = Astro.clientAddress; #### `Astro.slots.has()` +

+ **Type:** `(slotName: string) => boolean` +

You can check whether content for a specific slot name exists with `Astro.slots.has()`. This can be useful when you want to wrap slot contents, but only want to render the wrapper elements when the slot is being used. @@ -550,7 +593,10 @@ You can check whether content for a specific slot name exists with `Astro.slots. #### `Astro.slots.render()` +

+ **Type:** `(slotName: string, args?: any[]) => Promise` +

You can asynchronously render the contents of a slot to a string of HTML using `Astro.slots.render()`. @@ -656,7 +702,10 @@ And would render HTML like this: ### `Astro.locals` -

+

+ + +

`Astro.locals` is an object containing any values from the [`context.locals`](#contextlocals) object from a middleware. Use this to access data returned by middleware in your `.astro` files. @@ -675,9 +724,11 @@ const orders = Array.from(Astro.locals.orders.entries()); ### `Astro.preferredLocale` -

+

-**Type:** `string | undefined` +**Type:** `string | undefined`
+ +

`Astro.preferredLocale` is a computed value that represents the preferred locale of the user. @@ -687,9 +738,11 @@ This property is only available when building for SSR (server-side rendering) an ### `Astro.preferredLocaleList` -

+

-**Type:** `string[] | undefined` +**Type:** `string[] | undefined`
+ +

`Astro.preferredLocaleList` represents the array of all locales that are both requested by the browser and supported by your website. This produces a list of all compatible languages between your site and your visitor. @@ -701,9 +754,11 @@ This property is only available when building for SSR (server-side rendering) an ### `Astro.currentLocale` -

+

-**Type:** `string | undefined` +**Type:** `string | undefined`
+ +

The locale computed from the current URL, using the syntax specified in your `locales` configuration. If the URL does not contain a `/[locale]/` prefix, then the value will default to `i18n.defaultLocale`. @@ -749,7 +804,10 @@ See also: [`params`](#params) ### `context.props` -

+

+ + +

`context.props` is an object containing any `props` passed from `getStaticPaths()`. Because `getStaticPaths()` is not used when building for SSR (server-side rendering), `context.props` is only available in static builds. @@ -775,7 +833,10 @@ See also: [Data Passing with `props`](#data-passing-with-props) ### `context.request` +

+ **Type:** `Request` +

A standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. It can be used to get the `url`, `headers`, `method`, and even body of the request. @@ -791,7 +852,10 @@ See also: [Astro.request](#astrorequest) ### `context.cookies` +

+ **Type:** `AstroCookies` +

`context.cookies` contains utilities for reading and manipulating cookies. @@ -799,9 +863,11 @@ See also: [Astro.cookies](#astrocookies) ### `context.url` -

+

-**Type:** `URL` +**Type:** `URL`
+ +

A [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) object constructed from the current `context.request.url` URL string value. @@ -809,9 +875,11 @@ See also: [Astro.url](#astrourl) ### `context.clientAddress` -

+

-**Type:** `string` +**Type:** `string`
+ +

Specifies the [IP address](https://en.wikipedia.org/wiki/IP_address) of the request. This property is only available when building for SSR (server-side rendering) and should not be used for static sites. @@ -828,9 +896,11 @@ See also: [Astro.clientAddress](#astroclientaddress) ### `context.site` -

+

-**Type:** `URL | undefined` +**Type:** `URL | undefined`
+ +

`context.site` returns a `URL` made from `site` in your Astro config. If undefined, this will return a URL generated from `localhost`. @@ -838,9 +908,11 @@ See also: [Astro.site](#astrosite) ### `context.generator` -

+

-**Type:** `string` +**Type:** `string`
+ +

`context.generator` is a convenient way to indicate the version of Astro your project is running. It follows the format `"Astro v1.x.x"`. @@ -857,9 +929,11 @@ See also: [Astro.generator](#astrogenerator) ### `context.redirect()` -

+

-**Type:** `(path: string, status?: number) => Response` +**Type:** `(path: string, status?: number) => Response`
+ +

`context.redirect()` returns a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) object that allows you to redirect to another page. This function is only available when building for SSR (server-side rendering) and should not be used for static sites. @@ -875,9 +949,11 @@ See also: [`Astro.redirect()`](#astroredirect) ### `context.rewrite()` -

+

-**Type:** `(rewritePayload: string | URL | Request) => Promise` +**Type:** `(rewritePayload: string | URL | Request) => Promise`
+ +

Allows you to serve content from a different URL or path without redirecting the browser to a new page. @@ -1094,6 +1170,7 @@ Pagination will pass a `page` prop to every rendered page that represents a sing ##### `page.data`

+ **Type:** `Array`

@@ -1102,6 +1179,7 @@ Array of data returned from `data()` for the current page. ##### `page.start`

+ **Type:** `number`

@@ -1110,6 +1188,7 @@ Index of first item on current page, starting at `0`. (e.g. if `pageSize: 25`, t ##### `page.end`

+ **Type:** `number`

@@ -1118,7 +1197,8 @@ Index of last item on current page. ##### `page.size`

-**Type:** `number` + +**Type:** `number`
**Default:** `10`

@@ -1127,6 +1207,7 @@ How many items per-page. ##### `page.total`

+ **Type:** `number`

@@ -1135,6 +1216,7 @@ The total number of items across all pages. ##### `page.currentPage`

+ **Type:** `number`

@@ -1143,6 +1225,7 @@ The current page number, starting with `1`. ##### `page.lastPage`

+ **Type:** `number`

@@ -1151,6 +1234,7 @@ The total number of pages. ##### `page.url.current`

+ **Type:** `string`

@@ -1159,6 +1243,7 @@ Get the URL of the current page (useful for canonical URLs). ##### `page.url.prev`

+ **Type:** `string | undefined`

@@ -1167,6 +1252,7 @@ Get the URL of the previous page (will be `undefined` if on page 1). If a value ##### `page.url.next`

+ **Type:** `string | undefined`

@@ -1174,20 +1260,20 @@ Get the URL of the next page (will be `undefined` if no more pages). If a value ##### `page.url.first` -

-

-**Type:** `string | undefined` + +**Type:** `string | undefined`
+

Get the URL of the first page (will be `undefined` if on page 1). If a value is set for [`base`](/en/reference/configuration-reference/#base), prepend the base path to the URL. ##### `page.url.last` -

-

-**Type:** `string | undefined` + +**Type:** `string | undefined`
+

Get the URL of the last page (will be `undefined` if no more pages). If a value is set for [`base`](/en/reference/configuration-reference/#base), prepend the base path to the URL. @@ -1245,7 +1331,10 @@ Content collections offer APIs to configure and query your Markdown or MDX docum ### `defineCollection()` -**Type:** `(input: CollectionConfig) => CollectionConfig` +

+ +**Type:** `(input: CollectionConfig) => CollectionConfig` +

`defineCollection()` is a utility to configure a collection in a `src/content/config.*` file. @@ -1269,10 +1358,12 @@ This function accepts the following properties: #### `type` -

+

-**Type:** `'content' | 'data'` -**Default:** `'content'` +**Type:** `'content' | 'data'`
+**Default:** `'content'`
+ +

`type` is a string that defines the type of entries stored within a collection: @@ -1285,7 +1376,10 @@ This means collections **cannot** store a mix of content and data formats. You m #### `schema` +

+ **Type:** ZodType | (context: SchemaContext) => ZodType +

`schema` is an optional Zod object to configure the type and shape of document frontmatter for a collection. Each value must use [a Zod validator](https://github.com/colinhacks/zod). @@ -1293,9 +1387,11 @@ This means collections **cannot** store a mix of content and data formats. You m ### `reference()` -

+

-**Type:** `(collection: string) => ZodEffects` +**Type:** `(collection: string) => ZodEffects`
+ +

The `reference()` function is used in the content config to define a relationship, or "reference," from one collection to another. This accepts a collection name and validates the entry identifier(s) specified in your content frontmatter or data file. @@ -1326,7 +1422,10 @@ export const collections = { blog, authors }; ### `getCollection()` +

+ **Type:** `(collection: string, filter?: (entry: CollectionEntry) => boolean) => CollectionEntry[]` +

`getCollection()` is a function that retrieves a list of content collection entries by collection name. @@ -1350,13 +1449,14 @@ const draftBlogPosts = await getCollection('blog', ({ data }) => { ### `getEntry()` -

+

**Types:** - - `(collection: string, contentSlugOrDataId: string) => CollectionEntry` - `({ collection: string, id: string }) => CollectionEntry` - `({ collection: string, slug: string }) => CollectionEntry` + +

`getEntry()` is a function that retrieves a single collection entry by collection name and either the entry `id` (for `type: 'data'` collections) or entry `slug` (for `type: 'content'` collections). `getEntry()` can also be used to get referenced entries to access the `data`, `body`, or `render()` properties: @@ -1379,12 +1479,13 @@ See the `Content Collections` guide for examples of [querying collection entries ### `getEntries()` -

+

**Types:** - - `(Array<{ collection: string, id: string }>) => Array>` - `(Array<{ collection: string, slug: string }>) => Array>` + +

`getEntries()` is a function that retrieves multiple collection entries from the same collection. This is useful for [returning an array of referenced entries](/en/guides/content-collections/#defining-collection-references) to access their associated `data`, `body`, and `render()` properties. @@ -1401,7 +1502,10 @@ const enterpriseRelatedPosts = await getEntries(enterprisePost.data.relatedPosts ### `getEntryBySlug()` +

+ **Type:** `(collection: string, slug: string) => CollectionEntry` +

:::caution[Deprecated] Use the [`getEntry()` function](#getentry) to query content entries. This accepts the same arguments as `getEntryBySlug()`, and supports querying by `id` for JSON or YAML collections. @@ -1569,21 +1673,24 @@ export function onRequest (context, next) { ### `next()` -**Type:** `(rewritePayload?: RewritePayload) => Promise` +

+ +**Type:** `(rewritePayload?: string | URL | Request) => Promise`
+ +

A function that intercepts (reads and modifies) the `Response` of a `Request` or calls the "next" middleware in the chain and returns a `Response`. For example, this function could modify the HTML body of a response. This is an optional argument of `onRequest()`, and may provide the required `Response` returned by the middleware. -

- -**Type:** `(rewritePayload?: string | URL | Request) => Promise` - It accepts an optional URL path parameter in the form of a string, `URL`, or `Request` to [rewrite](/en/guides/routing/#rewrites) the current request without retriggering a new rendering phase. ### `sequence()` +

+ **Type:** `(...handlers: MiddlewareHandler[]) => MiddlewareHandler` +

A function that accepts middleware functions as arguments, and will execute them in the order in which they are passed. @@ -1599,9 +1706,11 @@ export const onRequest = sequence(validation, auth, greeting); ### `createContext()` -

+

-**Type:** `(context: CreateContext) => APIContext` +**Type:** `(context: CreateContext) => APIContext`
+ +

A low-level API to create an [`APIContext`](#endpoint-context)to be passed to an Astro middleware `onRequest()` function. @@ -1609,9 +1718,11 @@ This function can be used by integrations/adapters to programmatically execute t ### `trySerializeLocals()` -

+

-**Type:** `(value: unknown) => string` +**Type:** `(value: unknown) => string`
+ +

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. @@ -1634,7 +1745,10 @@ For features and usage examples, [see our i18n routing guide](/en/guides/interna ### `getRelativeLocaleUrl()` +

+ **Type:** `(locale: string, path?: string, options?: GetLocaleOptions) => string` +

Use this function to retrieve a relative path for a locale. If the locale doesn't exist, Astro throws an error. @@ -1664,7 +1778,10 @@ getRelativeLocaleUrl("fr_CA", "getting-started", { ### `getAbsoluteLocaleUrl()` -**Type:** `(locale: string, path: string, options?: GetLocaleOptions) => string` +

+ +**Type:** `(locale: string, path: string, options?: GetLocaleOptions) => string` +

Use this function to retrieve an absolute path for a locale when [`site`] has a value. If [`site`] isn't configured, the function returns a relative URL. If the locale doesn't exist, Astro throws an error. @@ -1697,20 +1814,29 @@ getAbsoluteLocaleUrl("fr_CA", "getting-started", { ### `getRelativeLocaleUrlList()` +

+ **Type:** `(path?: string, options?: GetLocaleOptions) => string[]` +

Use this like [`getRelativeLocaleUrl`](#getrelativelocaleurl) to return a list of relative paths for all the locales. ### `getAbsoluteLocaleUrlList()` +

+ **Type:** `(path?: string, options?: GetLocaleOptions) => string[]` +

Use this like [`getAbsoluteLocaleUrl`](/en/guides/internationalization/#custom-locale-paths) to return a list of absolute paths for all the locales. ### `getPathByLocale()` +

+ **Type:** `(locale: string) => string` +

A function that returns the `path` associated to one or more `codes` when [custom locale paths](/en/guides/internationalization/#custom-locale-paths) are configured. @@ -1734,7 +1860,10 @@ getPathByLocale("fr-CA"); // returns "french" ### `getLocaleByPath` -*Type:** `(path: string) => string` +

+ +**Type:** `(path: string) => string` +

A function that returns the `code` associated to a locale `path`. @@ -1757,9 +1886,11 @@ getLocaleByPath("french"); // returns "fr" because that's the first code configu ### `redirectToDefaultLocale()` -**Type:** `(context: APIContext, statusCode?: ValidRedirectStatus) => Promise` +

-

+**Type:** `(context: APIContext, statusCode?: ValidRedirectStatus) => Promise`
+ +

:::note Available only when `i18n.routing` is set to `"manual"` @@ -1782,9 +1913,11 @@ export const onRequest = defineMiddleware((context, next) => { ### `redirectToFallback()` -**Type:** `(context: APIContext, response: Response) => Promise` +

-

+**Type:** `(context: APIContext, response: Response) => Promise`
+ +

:::note Available only when `i18n.routing` is set to `"manual"` @@ -1807,9 +1940,11 @@ export const onRequest = defineMiddleware(async (context, next) => { ### `notFound()` -**Type:** `(context: APIContext, response?: Response) => Promise | undefined` +

-

+**Type:** `(context: APIContext, response?: Response) => Promise | undefined`
+ +

:::note Available only when `i18n.routing` is set to `"manual"` @@ -1836,9 +1971,11 @@ export const onRequest = defineMiddleware((context, next) => { ### `middleware()` -**Type:** `(options: { prefixDefaultLocale: boolean, redirectToDefaultLocale: boolean }) => MiddlewareHandler` +

-

+**Type:** `(options: { prefixDefaultLocale: boolean, redirectToDefaultLocale: boolean }) => MiddlewareHandler`
+ +

:::note Available only when `i18n.routing` is set to `"manual"` @@ -1869,9 +2006,11 @@ export const onRequest = sequence(customLogic, middleware({ ### `requestHasLocale()` -**Type:** `(context: APIContext) => boolean` +

-

+**Type:** `(context: APIContext) => boolean`
+ +

:::note Available only when `i18n.routing` is set to `"manual"` From 5c39fbe21b651b911e29b2433f4dc5a7dba93024 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Thu, 1 Aug 2024 18:40:02 +0200 Subject: [PATCH 18/25] feat(api-reference): add getDataEntryById section * Add documentation about the deprecated getDataEntryById function * Fix return type for getDataEntryBySlug (this is a Promise) --- .../docs/en/reference/api-reference.mdx | 25 ++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index fd2afa4376ca2..d6845c06000a1 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -1504,7 +1504,7 @@ const enterpriseRelatedPosts = await getEntries(enterprisePost.data.relatedPosts

-**Type:** `(collection: string, slug: string) => CollectionEntry` +**Type:** `(collection: string, slug: string) => Promise>`

:::caution[Deprecated] @@ -1524,6 +1524,29 @@ const enterprise = await getEntryBySlug('blog', 'enterprise'); [See the `Content Collection` guide](/en/guides/content-collections/#querying-collections) for example usage. +### `getDataEntryById()` + +

+ +**Type:** `(collection: string, id: string) => Promise>`
+ +

+ +:::caution[Deprecated] +Use the [`getEntry()` function](#getentry) to query data entries. This accepts the same arguments as `getDataEntryById()`, and supports querying by `slug` for content authoring formats like Markdown. +::: + +`getDataEntryById()` is a function that retrieves a single collection entry by collection name and entry `id`. + + +```astro +--- +import { getDataEntryById } from 'astro:content'; + +const picardProfile = await getDataEntryById('captains', 'picard'); +--- +``` + ### Collection Entry Type Query functions including [`getCollection()`](#getcollection), [`getEntry()`](#getentry), and [`getEntries()`](#getentries) each return entries with the `CollectionEntry` type. This type is available as a utility from `astro:content`: From fe303f4d12e594c0566c1b502274ea5dee5aa6c7 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Thu, 1 Aug 2024 19:12:50 +0200 Subject: [PATCH 19/25] style(api-reference): reformat Types block when listing overloads We cannot use `ul` inside `p` tag so we need to make an exception when using Since and Type with overloads and separate them. --- src/content/docs/en/reference/api-reference.mdx | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index d6845c06000a1..c5ea6909370bb 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -1449,14 +1449,12 @@ const draftBlogPosts = await getCollection('blog', ({ data }) => { ### `getEntry()` -

+

**Types:** - `(collection: string, contentSlugOrDataId: string) => CollectionEntry` - `({ collection: string, id: string }) => CollectionEntry` - `({ collection: string, slug: string }) => CollectionEntry` - -

`getEntry()` is a function that retrieves a single collection entry by collection name and either the entry `id` (for `type: 'data'` collections) or entry `slug` (for `type: 'content'` collections). `getEntry()` can also be used to get referenced entries to access the `data`, `body`, or `render()` properties: @@ -1479,13 +1477,11 @@ See the `Content Collections` guide for examples of [querying collection entries ### `getEntries()` -

+

**Types:** - `(Array<{ collection: string, id: string }>) => Array>` - `(Array<{ collection: string, slug: string }>) => Array>` - -

`getEntries()` is a function that retrieves multiple collection entries from the same collection. This is useful for [returning an array of referenced entries](/en/guides/content-collections/#defining-collection-references) to access their associated `data`, `body`, and `render()` properties. From ec5ef9e686c7bd8d5a4aee3a10307b245ac6da9a Mon Sep 17 00:00:00 2001 From: Armand Philippot <59021693+ArmandPhilippot@users.noreply.github.com> Date: Fri, 2 Aug 2024 01:04:08 +0200 Subject: [PATCH 20/25] fix(api-reference): remove Since on next() section Only the argument was added in `4.13.0` so it doesn't make sense to keep it under `next()` heading. Co-authored-by: Chris Swithinbank --- src/content/docs/en/reference/api-reference.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index c5ea6909370bb..34e088efb2a52 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -1695,7 +1695,6 @@ export function onRequest (context, next) {

**Type:** `(rewritePayload?: string | URL | Request) => Promise`
-

A function that intercepts (reads and modifies) the `Response` of a `Request` or calls the "next" middleware in the chain and returns a `Response`. For example, this function could modify the HTML body of a response. From 7c944a38561aa40f303619c938faf89802d287f7 Mon Sep 17 00:00:00 2001 From: Armand Philippot <59021693+ArmandPhilippot@users.noreply.github.com> Date: Fri, 2 Aug 2024 01:05:15 +0200 Subject: [PATCH 21/25] fix(api-reference): add Astro version to next argument description Co-authored-by: Chris Swithinbank --- src/content/docs/en/reference/api-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index 34e088efb2a52..938579b1881a1 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -1701,7 +1701,7 @@ A function that intercepts (reads and modifies) the `Response` of a `Request` or This is an optional argument of `onRequest()`, and may provide the required `Response` returned by the middleware. -It accepts an optional URL path parameter in the form of a string, `URL`, or `Request` to [rewrite](/en/guides/routing/#rewrites) the current request without retriggering a new rendering phase. +Since Astro v4.13.0, `next()` accepts an optional URL path parameter in the form of a string, `URL`, or `Request` to [rewrite](/en/guides/routing/#rewrites) the current request without retriggering a new rendering phase. ### `sequence()` From b2aefcadde5551b6d682cfb4cab3e84ec575aa6b Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Fri, 2 Aug 2024 11:06:34 +0200 Subject: [PATCH 22/25] fix(api-reference): update `onRequest` section struture * Move `next()` as subheading of `onRequest()` because it is an argument of that function * Add a `context` subheading to describe the first argument * Update `context` link to redirect to the new `context` section --- src/content/docs/en/reference/api-reference.mdx | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index 938579b1881a1..eff518dc91bba 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -1679,7 +1679,7 @@ Middleware allows you to intercept requests and responses and inject behaviors d **Type:** `(context: APIContext, next: MiddlewareNext) => Promise | Response | Promise | void` -A required exported function from `src/middleware.js` that will be called before rendering every page or API route. It accepts two optional arguments: [context](#contextlocals) and [next()](#next). `onRequest()` must return a `Response`: either directly, or by calling `next()`. +A required exported function from `src/middleware.js` that will be called before rendering every page or API route. It accepts two optional arguments: [context](#context) and [next()](#next). `onRequest()` must return a `Response`: either directly, or by calling `next()`. ```js title="src/middleware.js" export function onRequest (context, next) { @@ -1690,7 +1690,18 @@ export function onRequest (context, next) { }; ``` -### `next()` +#### `context` + +

+ +**Type:** `APIContext` +

+ +The first argument of `onRequest()` is a context object. It mirrors many of the `Astro` global properties. + +See [Endpoint contexts](#endpoint-context) for more information about the context object. + +#### `next()`

From 4ab513f3f88759c7774f266db849c186adb53ed5 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Fri, 2 Aug 2024 12:09:52 +0200 Subject: [PATCH 23/25] fix(api-reference): add `getImage` types * Add the `getImage` function signature * List every properties returned by the function --- .../docs/en/reference/api-reference.mdx | 28 +++++++++++++++---- 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index eff518dc91bba..8a4e438a54286 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -1294,6 +1294,11 @@ export default function () { ### `getImage()` +

+ +**Type:** `(options: UnresolvedImageTransform) => Promise` +

+ :::caution `getImage()` relies on server-only APIs and breaks the build when used on the client. ::: @@ -1313,13 +1318,24 @@ const optimizedBackground = await getImage({src: myBackground, format: 'avif'})
``` -It returns an object with the following properties: +It returns an object with the following type: -```js -{ - options: {...} // Original parameters passed - src: "https//..." // Path to the generated image - attributes: {...} // Additional HTML attributes needed to render the image (width, height, style, etc..) +```ts +type GetImageResult = { + /* Additional HTML attributes needed to render the image (width, height, style, etc..) */ + attributes: Record; + /* Validated parameters passed */ + options: ImageTransform; + /* Original parameters passed */ + rawOptions: ImageTransform; + /* Path to the generated image */ + src: string; + srcSet: { + /* Generated values for srcset, every entry has a url and a size descriptor */ + values: SrcSetValue[]; + /* A value ready to use in`srcset` attribute */ + attribute: string; + }; } ``` From 129d9f553d7555fd64ad8476cf1dc845ddb4d381 Mon Sep 17 00:00:00 2001 From: Armand Philippot <59021693+ArmandPhilippot@users.noreply.github.com> Date: Fri, 2 Aug 2024 13:51:27 +0200 Subject: [PATCH 24/25] fix(api-reference): reword onRequest description The arguments are always available. It is up to the consumer to use them or not. Co-authored-by: Chris Swithinbank --- src/content/docs/en/reference/api-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index 8a4e438a54286..396411f97117e 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -1695,7 +1695,7 @@ Middleware allows you to intercept requests and responses and inject behaviors d **Type:** `(context: APIContext, next: MiddlewareNext) => Promise | Response | Promise | void` -A required exported function from `src/middleware.js` that will be called before rendering every page or API route. It accepts two optional arguments: [context](#context) and [next()](#next). `onRequest()` must return a `Response`: either directly, or by calling `next()`. +A required exported function from `src/middleware.js` that will be called before rendering every page or API route. It receives two arguments: [context](#context) and [next()](#next). `onRequest()` must return a `Response`: either directly, or by calling `next()`. ```js title="src/middleware.js" export function onRequest (context, next) { From d3b4b130aa0c434b8e5dd0206c00ab11b3a1bb6e Mon Sep 17 00:00:00 2001 From: Armand Philippot <59021693+ArmandPhilippot@users.noreply.github.com> Date: Fri, 2 Aug 2024 13:54:47 +0200 Subject: [PATCH 25/25] fix(api-reference): reword next subsection of onRequest * Aligns phrasing with the new `context` subsection of `onRequest` * Makes the use of `next()` function clearer Co-authored-by: Chris Swithinbank --- src/content/docs/en/reference/api-reference.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index 396411f97117e..47a98b9e93838 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -1724,9 +1724,7 @@ The first argument of `onRequest()` is a context object. It mirrors many of the **Type:** `(rewritePayload?: string | URL | Request) => Promise`

-A function that intercepts (reads and modifies) the `Response` of a `Request` or calls the "next" middleware in the chain and returns a `Response`. For example, this function could modify the HTML body of a response. - -This is an optional argument of `onRequest()`, and may provide the required `Response` returned by the middleware. +The second argument of `onRequest()` is a function that calls all the subsequent middleware in the chain and returns a `Response`. For example, other middleware could modify the HTML body of a response and awaiting the result of `next()` would allow your middleware to respond to those changes. Since Astro v4.13.0, `next()` accepts an optional URL path parameter in the form of a string, `URL`, or `Request` to [rewrite](/en/guides/routing/#rewrites) the current request without retriggering a new rendering phase.