API Reference
Ce contenu n’est pas encore disponible dans votre langue.
Astro
global
Section titled Astro globalThe Astro
global is available in all contexts in .astro
files. It has the following functions:
Astro.glob()
Section titled Astro.glob()Astro.glob()
is a way to load many local files into your static site setup.
.glob()
only takes one parameter: a relative URL glob of which local files you’d like to import. It’s asynchronous, and returns an array of the exports from matching files.
.glob()
can’t take variables or strings that interpolate them, as they aren’t statically analyzable. (See the troubleshooting guide for a workaround.) This is because Astro.glob()
is a wrapper of Vite’s import.meta.glob()
.
You can also use import.meta.glob()
itself in your Astro project. You may want to do this when:
- You need this feature in a file that isn’t
.astro
, like an API route.Astro.glob()
is only available in.astro
files, whileimport.meta.glob()
is available anywhere in the project. - You don’t want to load each file immediately.
import.meta.glob()
can return functions that import the file content, rather than returning the content itself. Note that this import includes all styles and scripts for any imported files. These will be bundled and added to the page whether or not a file is actually used, as this is decided by static analysis, not at runtime. - You want access to each file’s path.
import.meta.glob()
returns a map of a file’s path to its content, whileAstro.glob()
returns a list of content. - You want to pass multiple patterns; for example, you want to add a “negative pattern” that filters out certain files.
import.meta.glob()
can optionally take an array of glob strings, rather than a single string.
Read more in the Vite documentation.
Markdown Files
Section titled Markdown FilesMarkdown files have the following interface:
You can optionally provide a type for the frontmatter
variable using a TypeScript generic.
Astro Files
Section titled Astro FilesAstro files have the following interface:
Other Files
Section titled Other FilesOther files may have various different interfaces, but Astro.glob()
accepts a TypeScript generic if you know exactly what an unrecognized file type contains.
Astro.props
Section titled Astro.propsAstro.props
is an object containing any values that have been passed as component attributes. Layout components for .md
and .mdx
files receive frontmatter values as props.
Astro.params
Section titled Astro.paramsAstro.params
is an object containing the values of dynamic route segments matched for this request.
In static builds, this will be the params
returned by getStaticPaths()
used for prerendering dynamic routes.
In SSR builds, this can be any value matching the path segments in the dynamic route pattern.
See also: params
Astro.request
Section titled Astro.requestAstro.request
is a standard Request object. It can be used to get the url
, headers
, method
, and even body of the request.
See also: Astro.url
With the default output: 'static'
option, Astro.request.url
does not contain search parameters, like ?foo=bar
, as it’s not possible to determine them ahead of time during static builds. However in output: 'server'
mode, Astro.request.url
does contain search parameters as it can be determined from a server request.
Astro.response
Section titled Astro.responseAstro.response
is a standard ResponseInit
object. It has the following structure.
status
: The numeric status code of the response, e.g.,200
.statusText
: The status message associated with the status code, e.g.,'OK'
.headers
: AHeaders
instance that you can use to set the HTTP headers of the response.
Astro.response
is used to set the status
, statusText
, and headers
for a page’s response.
Or to set a header:
Astro.cookies
Section titled Astro.cookies
Ajouté à la version :
astro@1.4.0
Astro.cookies
contains utilities for reading and manipulating cookies in server-side rendering mode.
Type: (key: string, options?: CookieGetOptions) => AstroCookie
Gets the cookie as an AstroCookie
object, which contains the value
and utility functions for converting the cookie to non-string types.
Type: (key: string) => 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
.
Type: (key: string, value: string | number | boolean | 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, such as the maxAge
or httpOnly
.
delete
Section titled deleteType: (key: string, options?: CookieDeleteOptions) => void
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
with a value
of undefined
. Options available when deleting a cookie are: domain
, path
, httpOnly
, sameSite
, and secure
.
headers
Section titled headersType: () => Iterator<string>
Gets the header values for Set-Cookie
that will be sent out with the response.
AstroCookie
Section titled AstroCookieGetting a cookie via Astro.cookies.get()
returns a AstroCookie
type. It has the following structure.
value
Section titled valueType: string | undefined
The raw string value of the cookie.
Type: () => Record<string, any>
Parses the cookie value via JSON.parse()
, returning an object. Throws if the cookie value is not valid JSON.
number
Section titled numberType: () => number
Parses the cookie value as a Number. Returns NaN if not a valid number.
boolean
Section titled booleanType: () => boolean
Converts the cookie value to a boolean.
CookieGetOptions
Section titled CookieGetOptions
Ajouté à la version :
astro@4.1.0
Getting a cookie also allows specifying options via the CookieGetOptions
interface:
decode
Section titled decodeType: (value: string) => string
Allows customization of how a cookie is deserialized into a value.
CookieSetOptions
Section titled CookieSetOptions
Ajouté à la version :
astro@4.1.0
Setting a cookie via Astro.cookies.set()
allows passing in a CookieSetOptions
to customize how the cookie is serialized.
domain
Section titled domainType: string
Specifies the domain. If no domain is set, most clients will interpret to apply to the current domain.
expires
Section titled expiresType: Date
Specifies the date on which the cookie will expire.
httpOnly
Section titled httpOnlyType: boolean
If true, the cookie will not be accessible client-side.
maxAge
Section titled maxAgeType: number
Specifies a number, in seconds, for which the cookie is valid.
Type: string
Specifies a subpath of the domain in which the cookie is applied.
sameSite
Section titled sameSiteType: boolean | 'lax' | 'none' | 'strict'
Specifies the value of the SameSite cookie header.
secure
Section titled secureType: boolean
If true, the cookie is only set on https sites.
encode
Section titled encodeType: (value: string) => string
Allows customizing how the cookie is serialized.
Astro.redirect()
Section titled Astro.redirect()Type: (path: string, status?: number) => Response
Allows you to redirect to another page, and optionally provide an HTTP response status code as a second parameter.
A page (and not a child component) must return
the result of Astro.redirect()
for the redirect to occur.
For statically-generated sites, this will produce a client redirect using a <meta http-equiv="refresh">
tag and does not support status codes.
When using an on-demand rendering mode, status codes are supported. Astro will serve redirected requests with a default HTTP response status of 302
unless another code is specified.
The following example redirects a user to a login page:
Astro.canonicalURL
Section titled Astro.canonicalURLUse Astro.url
to construct your own canonical URL.
The canonical URL of the current page.
Astro.url
Section titled Astro.url
Ajouté à la version :
astro@1.0.0-rc
A 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)
.
You can also use Astro.url
to create new URLs by passing it as an argument to new URL()
.
Astro.clientAddress
Section titled Astro.clientAddress
Ajouté à la version :
astro@1.0.0-rc
Specifies the 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.site
Section titled Astro.siteAstro.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
Section titled Astro.generator
Ajouté à la version :
astro@1.0.0
Astro.generator
is a convenient way to add a <meta name="generator">
tag with your current version of Astro. It follows the format "Astro v1.x.x"
.