API de Adaptadores do Astro

Astro foi projetado para ser fácil realizar deploy em qualquer provedor da nuvem para SSR (renderização no lado do servidor). Essa habilidade é providenciada por adaptadores, que são integrações.

Um adaptador é um tipo especial de integração que providencia um ponto de entrada para a renderização no lado do servidor. Um adaptador faz duas coisas:

• Implementa APIs específicas de uma hospedagem para lidar com requisições.
• Configura a construção final de acordo com as convenções da hospedagem.

Um adaptador é uma integração e pode fazer tudo que uma integração pode.

Um adaptador deve chamar a API setAdapter no hook astro:config:done assim:

export default function createIntegration() {
  return {
    name: '@matthewp/meu-adaptador',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@matthewp/meu-adaptador',
          serverEntrypoint: '@matthewp/meu-adaptador/server.js'
        });
      },
    },
  };
}

O objeto passado para setAdapter é definido como:

interface AstroAdapter {
  name: string;
  serverEntrypoint?: string;
  exports?: string[];
}

As propriedades são:

• name: Um nome único para seu adaptador, usado em logs.
• serverEntrypoint: O ponto de entrada para renderização no lado do servidor.
• exports: Um array de exportações nomeadas quando utilizado em conjunto com createExports (explicado abaixo).

A API de adaptadores do Astro tenta trabalhar com qualquer tipo de hospedagem e dá uma forma flexível de se adequar com as APIs da hospedagem.

Algumas hospedagens serverless esperam que você exporte uma função, como handler:

export function handler(evento, contexto) {
  // ...
}

Com a API de adaptadores você alcança isso implementando createExports em seu serverEntrypoint:

import { App } from 'astro/app';

export function createExports(manifesto) {
  const app = new App(manifesto);

  const handler = (evento, contexto) => {
    // ...
  };

  return { handler };
}

E então em sua integração, quando você chamar setAdapter, providencie o nome em exports:

export default function createIntegration() {
  return {
    name: '@matthewp/meu-adaptador',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@matthewp/meu-adaptador',
          serverEntrypoint: '@matthewp/meu-adaptador/server.js',
+         exports: ['handler'],
        });
      },
    },
  };
}

Algumas hospedagens esperam que você inicie o servidor por si mesmo, por exemplo, observando uma porta. Para esses tipos de hospedagens, a API de adaptadores permite que você exporte uma função start que será chamado quando o script de construção é executado.

import { App } from 'astro/app';

export function start(manifesto) {
  const app = new App(manifesto);

  addEventListener('fetch', evento => {
    // ...
  });
}

Este módulo é utilizado para renderizar páginas que foram pré-construídas através de astro build. Astro utiliza os objetos padrões Request e Response. Hospedagens que têm uma API diferente para requisições/respostas devem ser convertidos para estes tipos em seus adaptadores.

import { App } from 'astro/app';
import http from 'http';

export function start(manifesto) {
  const app = new App(manifesto);

  addEventListener('fetch', evento => {
    evento.respondWith(
      app.render(evento.request)
    );
  });
}

Os métodos a seguir são fornecidos:

Este método chama a página Astro que corresponde a requisição, a renderiza e retorna uma Promise a um objeto Response. Isso também funciona para rotas de API, que não renderizam páginas.

const resposta = await app.render(requisicao);

Este método é utilizado para determinar se uma requisição é correspondida pelas regras de roteamento da aplicação Astro.

if(app.match(requisicao)) {
  const resposta = await app.render(requisicao);
}

Você geralmente pode chamar app.render(requisicao) sem utilizar .match pois Astro lida com 404s se você providenciar um arquivo 404.astro. Utilize app.match(requisicao) se você quiser lidar com 404s de forma diferente.

O comando astro add permite que usuários facilmente adicionem integrações e adaptadores em seus projetos. Se você quiser que seu adaptador seja instalável com essa ferramenta, adicione astro-adapter no campo keywords do seu package.json:

{
  "name": "exemplo",
  "keywords": ["astro-adapter"],
}

Assim que você publicar seu adaptador no npm, executar astro add exemplo irá instalar seu pacote com quaisquer dependências de pares especificadas em seu package.json. Nós também iremos instruir usuários a atualizarem a configuração de seus projetos manualmente.