Referência da API

Global Astro

Seção intitulada Global Astro

A global Astro está disponível em todos os contextos em arquivos .astro. Ela tem as seguintes funções:

Astro.glob()

Seção intitulada Astro.glob()

Astro.glob() é uma forma de carregar vários arquivos locais em seu site estático.

src/components/meu-componente.astro

---
const postagens = await Astro.glob('../pages/postagens/*.md'); // retorna um array de postagens que estão em ./src/pages/postagens/*.md
---

<div>
{postagens.slice(0, 3).map((postagem) => (
  <article>
    <h2>{postagem.frontmatter.titulo}</h2>
    <p>{postagem.frontmatter.descricao}</p>
    <a href={postagem.url}>Leia mais</a>
  </article>
))}
</div>

.glob() recebe apenas um parâmetro: uma URL relativa dos arquivos locais que você gostaria de importar. Ela é assíncrona e retorna um array das exportações dos arquivos correspondentes.

.glob() não pode receber variáveis ou strings que são interpoladas já que não são estaticamente analisáveis. (Veja o guia de solução de problemas para uma solução alternativa.) Isso acontece pois Astro.glob() é feito em cima do import.meta.glob() do Vite.

Nota

Você também pode usar import.meta.glob() em si em seu projeto Astro. Você pode querer fazer isso quando:

• Você precisa dessa funcionalidade em um arquivo que não é .astro, como uma rota de API. Astro.glob() é apenas disponível em arquivos .astro, enquanto import.meta.glob() está disponível em qualquer parte do projeto.
• Você não quer carregar cada arquivo imediatamente. import.meta.glob() pode retornar funções que importam o conteúdo do arquivo, ao invés de retornar o conteúdo em si. Note que essa importação inclui todos os estilos e scripts para quaisquer arquivos importados. Eles vão ser empacotados e adicionados para a página sendo o arquivo usado ou não, já que isso é decidido por análise estática e não em tempo de execução.
• Você quer acessar o caminho de cada arquivo. import.meta.glob() retorna um map do caminho do arquivo ao seu conteúdo, enquanto Astro.glob() retorna uma lista de conteúdo.
• Você quer passar múltiplos padrões; por exemplo, você quer adicionar um “padrão negativo” que remove certos arquivos filtrados. import.meta.glob() pode opcionalmente receber um array de strings blog, ao invés de uma única string.

Leia mais sobre na documentação do Vite.

Arquivos Markdown

Seção intitulada Arquivos Markdown

Arquivos Markdown carregados com Astro.glob() retornam a seguinte interface MarkdownInstance:

export interface MarkdownInstance<T extends Record<string, any>> {
  /* Quaisquer dados especificados no frontmatter YAML deste arquivo */
  frontmatter: T;
  /* O caminho do arquivo deste arquivo */
  file: string;
  /* O caminho renderizado deste arquivo */
  url: string | undefined;
  /* Componente Astro que renderiza os conteúdos deste arquivo */
  Content: AstroComponentFactory;
  /** (Markdown apenas) Conteúdo de arquivo Markdown cru, excluindo layout HTML e frontmatter YAML */
  rawContent(): string;
  /** (Markdown apenas) Arquivo Markdown compilado para HTML, excluindo layout HTML */
  compiledContent(): string;
  /* Função que retorna um array de elementos h1...h6 deste arquivo */
  getHeadings(): Promise<{ depth: number; slug: string; text: string }[]>;
  default: AstroComponentFactory;
}

Você pode opcionalmente oferecer um tipo para a variável frontmatter utilizando um generic do TypeScript.

---
interface Frontmatter {
  titulo: string;
  descricao?: string;
}
const postagens = await Astro.glob<Frontmatter>('../pages/postagens/*.md');
---

<ul>
  {postagens.map(postagem => <li>{postagem.frontmatter.titulo}</li>)}
</ul>

Arquivos Astro

Seção intitulada Arquivos Astro

Arquivos Astro tem a seguinte interface:

export interface AstroInstance {
  /* O caminho de arquivo deste arquivo */
  file: string;
  /* A URL para este arquivo (se ele estiver no diretório pages) */
  url: string | undefined;
  default: AstroComponentFactory;
}

Outros Arquivos

Seção intitulada Outros Arquivos

Outros arquivos podem ter várias diferentes interfaces, mas Astro.glob() aceita um generic do TypeScript se você souber exatamente o que o tipo de um arquivo desconhecido contém.

---
interface DadosCustomizadosArquivo {
  default: Record<string, any>;
}
const dados = await Astro.glob<DadosCustomizadosArquivo>('../dados/**/*.js');
---

Astro.props

Seção intitulada Astro.props

Astro.props é um objeto contendo quaisquer valores que foram passados como atributos do componente. Componentes de Layout para arquivos .md e .mdx recebem valores frontmatter como props.

src/components/Titulo.astro

---
const { titulo, data } = Astro.props;
---
<div>
    <h1>{titulo}</h1>
    <p>{data}</p>
</div>

src/pages/index.astro

---
import Titulo from '../components/Titulo.astro';
---
<Titulo titulo="Minha Primeira Postagem" data="09 Ago 2022" />

Aprenda mais sobre como Layouts Markdown e MDX lidam com props.

Aprenda mais sobre como adicionar definições de tipo TypeScript para suas props.

Astro.params

Seção intitulada Astro.params

Astro.params é um objeto que contém os valores de segmentos dinâmicos de rota que correspondem a essa requisição.

Em builds estáticas, ele será o params retornado por getStaticPaths() usado para pré-renderizar rotas dinâmicas.

src/pages/postagens/[id].astro

---
export function getStaticPaths() {
  return [
    { params: { id: '1' } },
    { params: { id: '2' } },
    { params: { id: '3' } }
  ];
}

const { id } = Astro.params;
---
<h1>{id}</h1>

Em builds SSR, isso pode ser qualquer valor correspondente aos segmentos do caminho no padrão de roteamento dinâmico.

src/pages/postagens/[id].astro

---
import { getPost } from '../api';

const post = await getPost(Astro.params.id);

// Nenhuma postagem encontrada com esse ID
if (!post) {
  Astro.redirect("/404")
}
---
<html>
  <h1>{post.name}</h1>
</html>

Veja também: params

Astro.request

Seção intitulada Astro.request

Tipo: Request

Astro.request é um objeto Request padrão. Ele pode ser utilizado para obter a url, headers, method e até mesmo o body de uma requisição.

<p>Recebido uma requisição {Astro.request.method} para "{Astro.request.url}".</p>
<p>Headers da requisição recebidos: <code>{JSON.stringify(Object.fromEntries(Astro.request.headers))}</code>

Veja também: Astro.url

Nota

Com a opção padrão output: 'static', Astro.request.url não contém parâmetros de pesquisa, como ?foo=bar, já que não é possível determiná-los com antecedência durante builds estáticas. Porém, no modo output: 'server', Astro.request.url contém parâmetros de busca já que podem ser determinados pela requisição do servidor.

Astro.response

Seção intitulada Astro.response

Tipo: ResponseInit & { readonly headers: Headers }

Astro.response é um objeto ResponseInit padrão. Ele tem a seguinte estrutura.

• status: O código numérico do status da resposta, e.x., 200.
• statusText: A mensagem de status associada com o código de status, e.x., 'OK'
• headers: Uma instância de Headers que você pode usar para definir os cabeçalhos HTTP da resposta.

Astro.response é usado para definir o status, statusText e headers para a resposta de uma página.

---
if(condicao) {
  Astro.response.status = 404;
  Astro.response.statusText = 'Não encontrado';
}
---

Ou para definir um header:

---
Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;');
---

Astro.cookies

Seção intitulada Astro.cookies

Tipo: AstroCookies

Adicionado em: astro@1.4.0

Astro.cookies possui utilidades para ler e manipular cookies no modo de renderização no lado do servidor (EN).

get

Seção intitulada get

Tipo: (key: string, options?: AstroCookieGetOptions) => AstroCookie | undefined

Obtém o cookie como um objeto AstroCookie, que contém value e funções utilitários para converter o cookie em tipos que não sejam string.

has

Seção intitulada has

Tipo: (key: string, options?: AstroCookieGetOptions) => boolean

Se o cookie existe. Se o cookie foi definido com Astro.cookies.set(), ele irá retornar true, caso contrário, ele irá checar cookies em Astro.request.

set

Seção intitulada set

Tipo: (key: string, value: string | object, options?: AstroCookieSetOptions) => void

Define o cookie key para o valor dado. Ele tentará converter o valor do cookie para uma string. Opções providenciam formas de definir funcionalidades de cookies, como maxAge ou httpOnly.

delete

Seção intitulada delete

Tipo: (key: string, options?: AstroCookieDeleteOptions) => void

Invalida um cookie ao configurar sua data de validade para o passado (0 em tempo Unix).

Uma vez que o cookie é “deletado” (expirado), Astro.cookies.has() retornará false e Astro.cookies.get() retornará um AstroCookie com um value de undefined. Opções disponíveis ao deletar o cookie são: domain, path, httpOnly, sameSite, e secure.

merge

Seção intitulada merge

Tipo: (cookies: AstroCookies) => void

Mescla uma nova instância AstroCookies na instância corrente. Quaisquer novos cookies serão adicionados com a instância corrente e quaisquer cookies com o mesmo nome irão sobrescrever valores existentes.

headers

Seção intitulada headers

Tipo: () => Iterator<string>

Obtém os valores de cabeçalho para Set-Cookie que serão enviados com a resposta.

AstroCookie

Seção intitulada AstroCookie

Obter um cookie via Astro.cookies.get() retorna um tipo AstroCookie. Ele possui a estrutura seguinte.

value

Seção intitulada value

Tipo: string

O valor cru string do cookie.

json

Seção intitulada json

Tipo: () => Record<string, any>

Processa o valor do cookie via JSON.parse(), retornando um objeto. Lança um erro se o valor do cookie não for um JSON válido.

number

Seção intitulada number

Tipo: () => number

Processa o valor do cookie como Número. Retorna NaN se não for um número válido.

boolean

Seção intitulada boolean

Tipo: () => boolean

Converte o valor do cookie para um booleano.

AstroCookieGetOptions

Seção intitulada AstroCookieGetOptions

Adicionado em: astro@4.1.0

Obter um cookie permite especificar opções através da interface AstroCookieGetOptions:

decode

Seção intitulada decode

Tipo: (value: string) => string

Permite a personalização de como um cookie é desserializado em um valor.

AstroCookieSetOptions

Seção intitulada AstroCookieSetOptions

Adicionado em: astro@4.1.0

Definir um cookie via Astro.cookies.set() permite passar AstroCookieSetOptions para personalizar como o cookie é serializado.

domain

Seção intitulada domain

Tipo: string

Especifica o domínio corrente. Se nenhum domínio está configurado, a maioria dos clientes interpretará que é para aplicar o domínio corrente.

expires

Seção intitulada expires

Tipo: Date

Especifica a data em que o cookie irá expirar.

httpOnly

Seção intitulada httpOnly

Tipo: boolean

Se verdadeiro, o cookie não será acessível no lado do cliente.

maxAge

Seção intitulada maxAge

Tipo: number

Especifica um número, em segundos, para qual o cookie é válido.

path

Seção intitulada path

Tipo: string

Especifica um subcaminho do domínio em qual o cookie é aplicado.

sameSite

Seção intitulada sameSite

Tipo: boolean | 'lax' | 'none' | 'strict'

Especifica o valor do cabeçalho SameSite do cookie.

secure

Seção intitulada secure

Tipo: boolean

Se verdadeiro, o cookie é configurado somente em sites https.

encode

Seção intitulada encode

Tipo: (value: string) => string

Permite personalizar como o cookie é serializado.

Astro.redirect()

Seção intitulada Astro.redirect()

Tipo: (path: string, status?: number) => Response

Permite que você redirecione para outra página, e forneça opcionalmente um código de status de resposta HTTP como segundo parâmetro.

Uma página (e não um componente filho) precisa retornar com return o resultado de Astro.redirect() para o redirecionamento acontecer.

Para sites gerados estaticamente, isso irá produzir um redirecionamento de cliente usando a tag <meta http-equiv="refresh"> e que não suporta códigos de status.

Ao usar um modo de renderização sob demanda, códigos de status são suportados. Astro servirá requisições de redirecionamento com um status de resposta padrão de 302 a não ser que outro código seja especificado.

O exemplo seguinte redireciona o usuário para uma página de login:

src/pages/conta.astro

---
import { estaLogado } from '../utils';

const cookie = Astro.request.headers.get('cookie');

// Se o usuário não está logado, redireciona ele para a página de login
if (!estaLogado(cookie)) {
  return Astro.redirect('/login');
}
---

Astro.rewrite()

Seção intitulada Astro.rewrite()

Tipo: (rewritePayload: string | URL | Request) => Promise<Response>

Adicionado em: astro@4.13.0

Permite que você sirva conteúdo de uma URL ou caminho diferente sem redirecionar o navegador para uma nova página.

O método aceita tanto uma string, uma URL, ou um Request para a localização do caminho.

Use uma string para fornecer um caminho explícito:

src/pages/index.astro

---
return Astro.rewrite("/login")
---

Use um tipo URL quando você precisar construir o caminho URL para o rewrite. O exemplo seguinte renderiza o caminho pai da página ao criar uma nova URL do caminho relativo "../":

src/pages/blog/index.astro

---
return Astro.rewrite(new URL("../", Astro.url))
---

Use um tipo Request para controle completo do Request enviado ao servidor para o novo caminho. O exemplo seguinte envia uma requisição para renderizar a página pai enquanto também fornece cabeçalhos:

src/pages/blog/index.astro

---
return Astro.rewrite(new Request(new URL("../", Astro.url), {
  headers: {
    "x-custom-header": JSON.stringify(Astro.locals.someValue)
  }
}))
---

Astro.url

Seção intitulada Astro.url

Tipo: URL

Adicionado em: astro@1.0.0-rc

Um objeto URL construído a partir do valor da string URL atual do Astro.request.url. Útil para interagir com propriedades individuais da URL da requisição, como o nome do caminho e origem.

Equivalente a fazer new URL(Astro.request.url).

Astro.url será localhost em modo desenvolvimento se o site não estiver configurado para sites estáticos, e para sites renderizados sob demanda usando a saída output como server ou hybrid.

<h1>A URL atual é: {Astro.url}</h1>
<h1>O nome do caminho da URL atual é: {Astro.url.pathname}</h1>
<h1>A origem da URL atual é: {Astro.url.origin}</h1>

Você também pode usar Astro.url para criar novas URLs a passando como um argumento em new URL().

src/pages/index.astro

---
// Exemplo: Construa uma URL canônica usando seu domínio em produção
const URLCanonica = new URL(Astro.url.pathname, Astro.site);
// Exemplo: Construa uma URL para tags meta SEO usando seu domínio atual
const URLImagemSocial = new URL('/imagens/preview.png', Astro.url);
---
<link rel="canonical" href={URLCanonica} />
<meta property="og:image" content={URLImagemSocial} />

Astro.clientAddress

Seção intitulada Astro.clientAddress

Tipo: string

Adicionado em: astro@1.0.0-rc

Especifica o endereço de IP da requisição. Esta propriedade é apenas disponível ao fazer build para SSR (renderização no lado do servidor) e não deve ser usado em sites estáticos.

---
const ip = Astro.clientAddress;
---

<div>Your IP address is: <span class="address">{ ip }</span></div>

Astro.site

Seção intitulada Astro.site

Tipo: URL | undefined

Astro.site retorna a URL feita a partir do site na sua configuração Astro. Se site na sua configuração do Astro não estiver definido, Astro.sites não será definido.

Astro.generator

Seção intitulada Astro.generator

Tipo: string

Adicionado em: astro@1.0.0

Astro.generator é uma forma conveniente de adicionar uma tag <meta name="generator"> na sua versão atual do Astro. Ela segue o formato "Astro v1.x.x".

<html>
  <head>
    <meta name="generator" content={Astro.generator} />
  </head>
  <body>
    <footer>
      <p>Construído com <a href="https://astro.build">{Astro.generator}</a></p>
    </footer>
  </body>
</html>

Astro.slots

Seção intitulada Astro.slots

Astro.slots contém funções utilitárias para modificar os filhos em slots de um componente Astro.

Astro.slots.has()

Seção intitulada Astro.slots.has()

Tipo: (slotName: string) => boolean

Você pode checar se existe conteúdo para um nome de slot específico com Astro.slots.has(). Isso pode ser útil quando você quer envolver conteúdos de slots, mas apenas quer renderizar os elementos que os envolvem quando o slot está sendo utilizado.

src/pages/index.astro

---
---
<slot />

{Astro.slots.has('mais') && (
  <aside>
    <h2>Mais</h2>
    <slot name="mais" />
  </aside>
)}

Astro.slots.render()

Seção intitulada Astro.slots.render()

Tipo: (slotName: string, args?: any[]) => Promise<string>

Você pode renderizar de forma assíncrona os conteúdos de um slot para uma string de HTML utilizando Astro.slots.render().

---
const html = await Astro.slots.render('default');
---
<Fragment set:html={html} />

Nota

Isso é para casos de uso avançados! Na maioria das circunstâncias, é mais simples renderizar os conteúdos do slot com o elemento <slot />.

Astro.slots.render() opcionalmente aceita um segundo argumento: um array de parâmetros que serão passados para quaisquer funções filho. Isso pode ser útil para componentes utilitários customizados.

Por exemplo, esse componente <Grito /> converte sua prop mensagem para letras maiúsculas e o passa como o slot padrão:

src/components/Grito.astro

---
const mensagem = Astro.props.mensagem.toUpperCase();
let html = '';
if (Astro.slots.has('default')) {
  html = await Astro.slots.render('default', [mensagem]);
}
---
<Fragment set:html={html} />

Uma função de callback passada como filho de <Grito /> receberá o parâmetro mensagem em letras maiúsculas:

src/pages/index.astro

---
import Grito from "../components/Grito.astro";
---
<Grito mensagem="slots!">
  {(mensagem) => <div>{mensagem}</div>}
</Grito>

<!-- renderizado como <div>SLOTS!</div> -->

Funções callback podem ser passadas para slots onmeados desntro de um elemento HTML envoltório com o atributo slot. Esse elemento será usado apenas para transferir o callback para o slot nomeado e não será renderizado na página.

<Grito message="slots!">
  <fragment slot="message">
    {(message) => <div>{message}</div>}
  </fragment>
</Grito>

Use um elemento HTML padrão como a tag envoltória, ou qualquer tag em minúsculas (como <fragment> em vez de <Fragment />) que ela não será interpretada como componente. Não use o elemento HTML <slot> pois será interpretado como um slot Astro.

Astro.self

Seção intitulada Astro.self

Astro.self permite que componentes Astro sejam recursivamente invocados. Este comportamento te permite renderizar um componente Astro em si mesmo utilizando <Astro.self> no template do componente. Isto pode ser útil para iterar sobre grandes coleções e estruturas de dados aninhadas.

ListaAninhada.astro

---
const { itens } = Astro.props;
---
<ul class="lista-aninhada">
  {itens.map((item) => (
    <li>
      <!-- Se houver uma estrutura de dados aninhada nós renderizamos `<Astro.self>` -->
      <!-- e podemos passar props através de uma invocação recursiva -->
      {Array.isArray(item) ? (
        <Astro.self items={item} />
      ) : (
        item
      )}
    </li>
  ))}
</ul>

Este componente pode ser utilizado assim:

---
import ListaAninhada from './ListaAninhada.astro';
---
<ListaAninhada itens={['A', ['B', 'C'], 'D']} />

E renderizaria HTML assim:

<ul class="lista-aninhada">
  <li>A</li>
  <li>
    <ul class="lista-aninhada">
      <li>B</li>
      <li>C</li>
    </ul>
  </li>
  <li>D</li>
</ul>

Astro.locals

Seção intitulada Astro.locals

Adicionado em: astro@2.4.0

Astro.locals é um objeto contendo quaisquer valores do objeto context.locals de um middleware. Use isso para acessar dados retornados pelo middleware em seus arquivos .astro.

src/pages/Pedidos.astro

---
const titulo = Astro.locals.tituloBoasVindas();
const pedidos = Array.from(Astro.locals.pedidos.entries());
---
<h1>{titulo}</h1>
<ul>
    {pedidos.map(pedido => {
        return <li>{/* faz alguma coisa com cada pedido */}</li>
    })}
</ul>

Astro.preferredLocale

Seção intitulada Astro.preferredLocale

Tipo: string | undefined

Adicionado em: astro@3.5.0

Astro.preferredLocale é um valor computado que representa o idioma de preferência do usuário.

Ele é computado checando as configurações de idioma do seu array i18n.locales e os idiomas suportados pelo navegado do usuário através do cabeçalho Accept-Language. Esse valor é undefined se não houver uma correspondência.

Essa propriedade só está disponível ao fazer o build em modo SSR (renderização do lado do servidor) e não deve ser utilizada em sites estáticos.

Astro.preferredLocaleList

Seção intitulada Astro.preferredLocaleList

Tipo: string[] | undefined

Adicionado em: astro@3.5.0

Astro.preferredLocaleList representa a lista de todos os locales que são tanto requisitados pelo navegador quanto suportados pelo seu website. Isso produz uma lista de todas as linguagens compatíveis entre o seu site e seu visitante.

Se nenhuma das linguagens requesitadas pelo navegador forem encontradas na sua lista de idiomas, então o valor é []: você não suporta nenhum dos idiomas de preferência do seu visitante.

Se o navegador não especificar nenhuma linguagem de preferência, então esse valor será igual ao i18n.locales: todos os seus idiomas suportados serão considerados igualmente aceitáveis pelo visitante sem nenhuma preferênca.

Essa propriedade só está disponível ao fazer o build em modo SSR (renderização do lado do servidor) e não deve ser utilizada em sites estáticos.

Astro.currentLocale

Seção intitulada Astro.currentLocale

Tipo: string | undefined

Adicionado em: astro@3.5.6

O idioma computado a partir da URL atual, utilizando a sintaxe definida em sua configuração locales. Se a URL não incluir um prefixo /[locale]/ então o valor será o padrão definido em i18n.defaultLocale.

Astro.getActionResult()

Seção intitulada Astro.getActionResult()

Tipo: (action: TAction) => ActionReturnType<TAction> | undefined

Adicionado em: astro@4.15.0

Astro.getActionResult() é uma função que retorna o resultado de uma Ação (EN) enviada. Isso aceita uma função de ação como argumento (como actions.logout) e retorna um objeto data ou error quando o envio é recebido. Caso contrário, retornará undefined.

src/pages/index.astro

---
import { actions } from 'astro:actions';

const result = Astro.getActionResult(actions.logout);
---

<form action={actions.logout}>
  <button type="submit">Sair</button>
</form>
{result?.error && <p>Falha ao sair. Tente novamente, por favor.</p>}

Astro.callAction()

Seção intitulada Astro.callAction()

Adicionado em: astro@4.15.0

Astro.callAction() é uma função usada para chamar um manipulador de Ação diretamente do seu componente Astro. Essa função aceita uma função Ação como primeiro argumento (como actions.logout) e qualquer outra entrada que a ação recebe como segundo argumento. Ela retorna o resultado da ação como Promise.

src/pages/index.astro

---
import { actions } from 'astro:actions';

const { data, error } = await Astro.callAction(actions.logout, { userId: '123' });
---

Contexto de Endpoint

Seção intitulada Contexto de Endpoint

Funções de Endpoint recebem um objeto de contexto como primeiro parâmetro. Ele copia muitas das propriedades da global Astro.

endpoint.json.ts

import type { APIContext } from 'astro';

export function GET(context: APIContext) {
  // ...
}

context.params

Seção intitulada context.params

context.params é um objeto que contém os valores de segmentos dinâmicos de rota que correspondem a essa requisição.

Em builds estáticas, ele será o params retornado por getStaticPaths() usado para pré-renderizar rotas dinâmicas.

Em builds SSR, ele pode ser qualquer valor correspondente aos segmentos do caminho no padrão da rota dinâmica.

src/pages/postagens/[id].json.ts

import type { APIContext } from 'astro';

export function getStaticPaths() {
  return [
    { params: { id: '1' } },
    { params: { id: '2' } },
    { params: { id: '3' } }
  ];
}

export function GET({ params }: APIContext) {
  return new Response(
    JSON.stringify({ id: params.id }),
  );
}

Veja também: params

context.props

Seção intitulada context.props

Adicionado em: astro@1.5.0

context.props é um objeto que contém quaisquer props passadas de getStaticPaths(). Por conta de getStaticPaths() não ser usado ao fazer build para SSR (renderização no lado do servidor), context.props está disponível apenas em builds estáticas.

src/pages/postagens/[id].json.ts

import type { APIContext } from 'astro';

export function getStaticPaths() {
  return [
    { params: { id: '1' }, props: { autor: 'Blu' } },
    { params: { id: '2' }, props: { autor: 'Erika' } },
    { params: { id: '3' }, props: { autor: 'Matthew' } }
  ];
}

export function GET({ props }: APIContext) {
  return new Response(
    JSON.stringify({ autor: props.autor }),
  );
}

Veja também: Passagem de dados com props

context.request

Seção intitulada context.request

Tipo: Request

Um objeto Request padrão. Ele pode ser utilizado para conseguir a url, headers, method e até mesmo body da requisição.

import type { APIContext } from 'astro';

export function GET({ request }: APIContext) {
  return new Response(`Olá ${request.url}`);
}

Veja também: Astro.request

context.cookies

Seção intitulada context.cookies

Tipo: AstroCookies

context.cookies contém utilitários para a leitura e manipulação de cookies.

Veja também: Astro.cookies

context.url

Seção intitulada context.url

Tipo: URL

Adicionado em: astro@1.5.0

Um objeto URL construído do valor string context.request.url da URL atual.

Veja também: Astro.url

context.clientAddress

Seção intitulada context.clientAddress

Tipo: string

Adicionado em: astro@1.5.0

Especifica o endereço de IP da requisição. Essa propriedade só está disponível ao fazer build para SSR (renderização no lado do servidor) e não deve ser utilizada para sites estáticos.

import type { APIContext } from 'astro';

export function GET({ clientAddress }: APIContext) {
  return new Response(`Seu endereço de IP é: ${clientAddress}`);
}

Veja também: Astro.clientAddress

context.site

Seção intitulada context.site

Tipo: URL | undefined

Adicionado em: astro@1.5.0

context.site retorna uma URL feita do site na sua configuração do Astro. Se for undefined, ela irá retornar uma URL gerada a partir de localhost.

Veja também: Astro.site

context.generator

Seção intitulada context.generator

Tipo: string

Adicionado em: astro@1.5.0

context.generator é uma forma conveniente de indicar a versão do Astro em que seu projeto está. Ela segue o formato "Astro v1.x.x".

src/pages/informacao-site.json.ts

import type { APIContext } from 'astro';

export function GET({ generator, site }: APIContext) {
  const body = JSON.stringify({ generator, site });
  return new Response(body);
}

Veja também: Astro.generator

context.redirect()

Seção intitulada context.redirect()

Tipo: (path: string, status?: number) => Response

Adicionado em: astro@1.5.0

context.redirect() retorna um objeto Response que te permite redirecionar para outra página. Essa função está disponível apenas ao fazer build para SSR (renderização no lado do servidor) e não deve ser utilizada para sites estáticos.

import type { APIContext } from 'astro';

export function GET({ redirect }: APIContext) {
  return redirect('/login', 302);
}

Veja também: Astro.redirect()

context.rewrite()

Seção intitulada context.rewrite()

Tipo: (rewritePayload: string | URL | Request) => Promise<Response>

Adicionado em: astro@4.13.0

Permite que você sirva conteúdo de uma URL ou caminho diferente sem redirecionar o navegador para uma nova página.

O método aceita uma string, uma URL ou um Request para a localização do caminho.

Use uma string para fornecer um caminho explícito:

import type { APIContext } from 'astro';

export function GET({ rewrite }: APIContext) {
  return rewrite('/login');
}

Use um tipo URL quando precisar construir o caminho da URL para o redirecionamento. O exemplo a seguir renderiza o caminho pai de uma página criando uma nova URL a partir do caminho relativo "../":

import type { APIContext } from 'astro';

export function GET({ rewrite }: APIContext) {
  return rewrite(new URL("../", Astro.url));
}

Use um tipo Request para ter controle completo do Request enviado ao servidor para o novo caminho. O exemplo a seguir envia uma solicitação para renderizar a página pai, fornecendo também cabeçalhos:

import type { APIContext } from 'astro';

export function GET({ rewrite }: APIContext) {
  return rewrite(new Request(new URL("../", Astro.url), {
   headers: {
     "x-custom-header": JSON.stringify(Astro.locals.someValue)
   }
 }));
}

Veja também: Astro.rewrite()

context.locals

Seção intitulada context.locals

Adicionado em: astro@2.4.0

context.locals é um objeto usado para armazenar e acessar informações arbitrárias durante o ciclo de vida de uma requisição.

Funções de middleware podem ler e escrever valores do context.locals:

src/middleware.ts

import type { MiddlewareHandler } from 'astro';

export const onRequest: MiddlewareHandler = ({ locals }, next) => {
  if (!locals.title) {
    locals.title = "Título Padrão";
  }
  return next();
}

Endpoints de API podem ler somente informações de context.locals:

src/pages/hello.ts

import type { APIContext } from 'astro';

export function GET({ locals }: APIContext) {
  return new Response(locals.title); // "Título Padrão"
}

Veja também: Astro.locals

context.getActionResult()

Seção intitulada context.getActionResult()

Tipo: (action: TAction) => ActionReturnType<TAction> | undefined

Adicionado em: astro@4.15.0

context.getActionResult() é uma função que retorna o resultado de uma submissão de Ação (EN). Ela aceita uma função de ação como argumento (como actions.logout) e retorna um objeto data ou error quando uma submissão é recebida. Caso contrário, retornará undefined.

Veja também Astro.getActionResult()

context.callAction()

Seção intitulada context.callAction()

Adicionado em: astro@4.15.0

context.callAction() é uma função usada para chamar um manipulador de Ação diretamente do seu componente Astro. Essa função aceita uma função de Ação como primeiro argumento (como actions.logout) e qualquer entrada que essa ação receba como segundo argumento. Ela retorna o resultado da ação como uma Promise.

Veja também Astro.callAction()

getStaticPaths()

Seção intitulada getStaticPaths()

Tipo: (options: GetStaticPathsOptions) => Promise<GetStaticPathsResult> | GetStaticPathsResult

Se uma página utiliza parâmetros dinâmicos em seu nome de arquivo, tal componente precisará exportar uma função getStaticPaths().

Esta função é necessária pois Astro é um gerador de sites estáticos. Isso significa que o seu site inteiro é construído previamente. Se Astro não sabe como gerar uma página em tempo de build, seus usuários não o irão ver quando visitarem o seu site.

---
export async function getStaticPaths() {
  return [
    { params: { /* obrigatório */ }, props: { /* opcional */ } },
    { params: { ... } },
    { params: { ... } },
    // ...
  ];
}
---
<!-- O seu template HTML aqui. -->

A função getStaticPaths() deve retornar um array de objetos para determinar quais caminhos serão pré-renderizados pelo Astro.

Ela também pode ser utilizada para endpoints de arquivos estáticos para roteamento dinâmico.

Dica

Ao usar TypeScript, use a utilidade de tipo GetStaticPaths para garantir acesso seguro de tipos de seus params e props.

Cuidado

A função getStaticPaths() é executada em seu próprio escopo isolado unicamente, antes de qualquer página carregar. Portanto você não pode referenciar nada de seu escopo parente além de importações de arquivos. O compilador irá te avisar se você quebrar esse requisito.

params

Seção intitulada params

A chave params de todos os objetos retornados diz ao Astro quais rotas construir. Os parâmetros retornados devem ser mapeados de volta para os parâmetros dinâmicos e rest definidos no caminho de arquivo do seu componente.

params são codificados na URL, então apenas strings são suportadas como valores. O valor para cada objeto params deve corresponder aos parâmetros utilizados no nome da página.

Por exemplo, suponha que você tem uma página em src/pages/postagens/[id].astro. Se você exportar getStaticPaths dessa página e retornar os seguintes caminhos:

---
export async function getStaticPaths() {
  return [
    { params: { id: '1' } },
    { params: { id: '2' } },
    { params: { id: '3' } }
  ];
}

const { id } = Astro.params;
---
<h1>{id}</h1>

Então Astro irá estaticamente gerar postagens/1,, postagens/2, e postagens/3 em tempo de build.

Passagem de Dados com props

Seção intitulada Passagem de Dados com props

Para passar dados adicionais para cada página gerada, você também pode definir um valor a props para cada objeto de caminho retornado. Diferente de params, props não são codificadas na URL, então não estão limitadas a apenas strings.

Por exemplo, supomos que você gera páginas baseando-se em dados buscados a partir de uma API remota. Você pode passar o objeto inteiro dos dados para o componente da página dentro de getStaticPaths:

---
export async function getStaticPaths() {
  const dados = await fetch('...').then(resposta => resposta.json());

  return dados.map((postagem) => {
    return {
      params: { id: postagem.id },
      props: { postagem },
    };
  });
}

const { id } = Astro.params;
const { postagem } = Astro.props;
---
<h1>{id}: {postagem.nome}</h1>

Você também pode passar um array normal, que pode ser útil quando for gerar ou esboçar uma lista conhecida de rotas.

---
export async function getStaticPaths() {
  const postagens = [
    {id: '1', categoria: "astro", titulo: "Referência da API"},
    {id: '2', categoria: "react", titulo: "Criando um contador com React!"}
  ];
  return postagens.map((postagem) => {
    return {
      params: { id: postagem.id },
      props: { postagem }
    };
  });
}
const {id} = Astro.params;
const {postagem} = Astro.props;
---
<body>
  <h1>{id}: {postagem.titulo}</h1>
  <h2>Categoria: {postagem.categoria}</h2>
</body>

Então Astro irá estaticamente gerar postagens/1 e postagens/2 em tempo de build utilizando o componente da página em pages/postagens/[id].astro. A página pode referenciar esses dados utilizando Astro.props:

paginate()

Seção intitulada paginate()

Paginação é um caso de uso comum para websites que Astro nativamente suporta através da função paginate(). paginate() irá automaticamente gerar o array para retornar de getStaticPaths() que cria uma URL para cada página da coleção paginada. O número da página será passado como um parâmetro, e os dados da página serão passados como a prop page.

export async function getStaticPaths({ paginate }) {
  // Carregue seus dados com fetch(), Astro.glob(), etc.
  const resposta = await fetch(`https://pokeapi.co/api/v2/pokemon?limit=150`);
  const resultado = await resposta.json();
  const todosPokemons = resultado.results;

  // Retorna a coleção paginada de caminhos para todas as postagens
  return paginate(todosPokemons, { pageSize: 10 });/*-
}

// Se configurado propriamente, a prop page agora tem tudo
// o que você precisa para renderizar uma única página (veja a próxima seção)
const { page } = Astro.props;

paginate() possui os seguintes argumentos:

• data - array contendo os dados passados da página para a função paginate()
• options - Objeto opcional com as seguintes propriedades:
  • pageSize - O número de itens mostrados por página (10 por padrão)
  • params - Envia parâmetros adicionais para criar rotas dinâmicas
  • props - Envia props adicionais disponibilizadas em cada página

paginate() assume um nome de arquivo [page].astro ou [...page].astro. O parâmetro page torna-se o número da página em sua URL:

• /posts/[page].astro geraria as URLs /posts/1, /posts/2, /posts/3, etc.
• /posts/[...page].astro geraria as URLs /posts, /posts/2, /posts/3, etc.

A prop page da paginação

Seção intitulada A prop page da paginação

Tipo: Page<TData>

A paginação irá passar a prop page para cada página renderizada que representa uma única página de dados na coleção paginada. Isso inclui dados que você paginou (page.data) assim como metadados para a página (page.url, page.start, page.end, page.total, etc). Estes metadados são úteis para coisas como um botão de “Próxima Página” ou uma mensagem “Mostrando 1-10 de 100”.

page.data

Seção intitulada page.data

Tipo: Array<TData>

Array de dados retornados pela função paginate() para a página atual.

page.start

Seção intitulada page.start

Tipo: number

Índice do primeiro item na página atual, começando em 0. (por exemplo, se pageSize: 25, isso seria 0 na página 1, 25 na página 2, etc.)

page.end

Seção intitulada page.end

Tipo: number

Índice do último item na página atual.

page.size

Seção intitulada page.size

Tipo: number
Padrão: 10

Quantidade de itens por página.

page.total

Seção intitulada page.total

Tipo: number

O número total de itens em todas as páginas.

page.currentPage

Seção intitulada page.currentPage

Tipo: number

O número da página atual, começando em 1.

page.lastPage

Seção intitulada page.lastPage

Tipo: number

O número total de páginas.

page.url.current

Seção intitulada page.url.current

Tipo: string

Obtém a URL da página atual (útil para URLs canônicas).

page.url.prev

Seção intitulada page.url.prev

Tipo: string | undefined

Obtém a URL da página anterior (será undefined se estiver na página 1). Se um valor for definido para base, adicione o caminho base à URL.

page.url.next

Seção intitulada page.url.next

Tipo: string | undefined

Obtém a URL da próxima página (será undefined se não houver mais páginas). Se um valor for definido para base, adicione o caminho base à URL.

page.url.first

Seção intitulada page.url.first

Tipo: string | undefined

Adicionado em: astro@4.12.0

Obtém a URL da primeira página (será undefined se estiver na página 1). Se um valor for definido para base, adicione o caminho base à URL.

page.url.last

Seção intitulada page.url.last

Tipo: string | undefined

Adicionado em: astro@4.12.0

Obtém a URL da última página (será undefined se não houver mais páginas). Se um valor for definido para base, adicione o caminho base à URL.

import.meta

Seção intitulada import.meta

Todos os módulos ESM incluem a propriedade import.meta. Astro adiciona import.meta.env pelo Vite.

import.meta.env.SSR pode ser utilizado para saber quando se está renderizando no servidor. As vezes você pode querer uma lógica diferente, por exemplo, para um componente que deve ser apenas renderizado no cliente:

export default function () {
  return import.meta.env.SSR ? <div class="spinner"></div> : <ComponenteComplexo />;
}