Skip to content

Commit

Permalink
fix(api-reference): add missing Since/Type in Astro global & APIContext
Browse files Browse the repository at this point in the history
* See withastro/astro#4986 for `site`, `generator`, `url`, `clientAddress`, `props` and `redirect`
* See withastro/astro#6721 for `locals`
* See withastro/astro#9021 for `preferredLocale` and `preferredLocaleList`
* See withastro/astro#9101 for `currentLocale`
  • Loading branch information
ArmandPhilippot committed Jul 29, 2024
1 parent 3c7d574 commit d6b50e1
Showing 1 changed file with 55 additions and 0 deletions.
55 changes: 55 additions & 0 deletions src/content/docs/en/reference/api-reference.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.

Expand Down Expand Up @@ -211,6 +214,8 @@ Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;');

<p><Since v="1.4.0" /></p>

**Type:** `AstroCookies`

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

##### `get`
Expand Down Expand Up @@ -414,6 +419,8 @@ if (!isLoggedIn(cookie)) {

<p><Since v="1.0.0-rc" /></p>

**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)`.
Expand Down Expand Up @@ -441,6 +448,8 @@ const socialImageURL = new URL('/images/preview.png', Astro.url);

<p><Since v="1.0.0-rc" /></p>

**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
Expand All @@ -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`

<p><Since v="1.0.0" /></p>

**Type:** `string`

`Astro.generator` is a convenient way to add a [`<meta name="generator">`](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"
Expand Down Expand Up @@ -593,6 +606,8 @@ And would render HTML like this:

### `Astro.locals`

<p><Since v="2.4.0" /></p>

`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"
Expand All @@ -610,6 +625,10 @@ const orders = Array.from(Astro.locals.orders.entries());

### `Astro.preferredLocale`

<p><Since v="3.5.0" /></p>

**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.
Expand All @@ -618,6 +637,10 @@ This property is only available when building for SSR (server-side rendering) an

### `Astro.preferredLocaleList`

<p><Since v="3.5.0" /></p>

**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.
Expand All @@ -628,6 +651,10 @@ This property is only available when building for SSR (server-side rendering) an

### `Astro.currentLocale`

<p><Since v="3.5.6" /></p>

**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
Expand Down Expand Up @@ -672,6 +699,8 @@ See also: [`params`](#params)

### `context.props`

<p><Since v="1.5.0" /></p>

`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"
Expand All @@ -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
Expand All @@ -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`

<p><Since v="1.5.0" /></p>

**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`

<p><Since v="1.5.0" /></p>

**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
Expand All @@ -737,12 +778,20 @@ See also: [Astro.clientAddress](#astroclientaddress)

### `context.site`

<p><Since v="1.5.0" /></p>

**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`

<p><Since v="1.5.0" /></p>

**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"
Expand All @@ -758,6 +807,10 @@ See also: [Astro.generator](#astrogenerator)

### `context.redirect()`

<p><Since v="1.5.0" /></p>

**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
Expand All @@ -772,6 +825,8 @@ See also: [`Astro.redirect()`](#astroredirect)

### `context.locals`

<p><Since v="2.4.0" /></p>

`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`:
Expand Down

0 comments on commit d6b50e1

Please sign in to comment.