Referencia de la API de Adapter Server Entrypoint

Este módulo ayuda a los autores de adapters a construir un server entrypoint mientras soporta páginas renderizadas en modo desarrollo o que han sido prebuild a través de astro build.

astro/app se usa internamente para los adapters oficiales de servidor de Astro, y también está disponible públicamente para que construyas un adapter personalizado para tu runtime o host de despliegue específico.

Publicar tu adapter

Usa las palabras clave apropiadas cuando publiques tu adapter en NPM para que tu adapter aparezca en nuestro Directorio de Integraciones.

Astro usa los objetos estándar Request y Response. Los hosts que usan una API diferente para peticiones/respuestas deberían convertir a estos tipos en su adapter. Por ejemplo, Astro expone helpers para trabajar con NodeJS.

Importaciones desde astro/app/entrypoint

Los siguientes helpers se importan desde el directorio entrypoint en el módulo app:

import {
  createApp
} from "astro/app/entrypoint";

createApp()

Type: (options?: { streaming: boolean }) => App

Añadido en: astro@6.0.0

Devuelve una instancia de App que incluye métodos para trabajar con objetos Request y Response estándar al construir un server entrypoint de un adapter.

import { createApp } from "astro/app/entrypoint";
import http from "http";

const app = createApp();

addEventListener("fetch", event => {
  event.respondWith(
    app.render(event.request)
  );
});

Opciones

La función createApp() acepta las siguientes opciones.

Opción options.streaming

Type: boolean
Default: true

Define si el HTML streaming está habilitado. En la mayoría de los casos, no se recomienda deshabilitar el streaming ya que mejora el rendimiento y generalmente proporciona una mejor experiencia al visitante.

El HTML streaming divide un documento en chunks para enviarlos por la red y renderizarlos en la página en orden. Esto normalmente resulta en que los visitantes vean tu HTML lo más rápido posible, pero factores como las condiciones de la red y la espera de data fetches pueden bloquear el renderizado de la página.

Sin embargo, cuando necesitas deshabilitar el HTML streaming (ej. tu host solo soporta caché HTML no streamada a nivel CDN), puedes optar por no usar el comportamiento por defecto pasando streaming: false a createApp():

import { createApp } from 'astro/app/entrypoint'

const app = createApp({ streaming: false })

La instancia de App

La función createApp() devuelve una instancia de clase con los siguientes métodos.

app.render()

Type: (request: Request, options?: RenderOptions) => Promise<Response>

Llama a la página de Astro que coincide con el Request, la renderiza, y devuelve una promise a un objeto Response. Esto también funciona para rutas de API que no renderizan páginas.

const response = await app.render(request);

app.match()

Type: (request: Request, allowPrerenderedRoutes = false) => RouteData | undefined

Determina si una petición coincide con las reglas de routing de la app de Astro.

if(app.match(request)) {
  const response = await app.render(request);
}

Normalmente puedes llamar a app.render(request) sin usar .match porque Astro maneja los 404 si proporcionas un archivo 404.astro. Usa app.match(request) si quieres manejar los 404 de una manera diferente.

Por defecto, las rutas prerenderizadas no se devuelven, incluso si coinciden. Puedes cambiar este comportamiento usando true como segundo argumento.

app.getAdapterLogger()

Type: () => AstroIntegrationLogger

Añadido en: astro@v3.0.0

Devuelve una instancia del logger de Astro disponible para el entorno de runtime del adapter.

const logger = app.getAdapterLogger();
try {
  /* Some logic that can throw */
} catch {
  logger.error("Your custom error message using Astro logger.");
}

app.getAllowedDomains()

Type: () => Partial<RemotePattern>[] | undefined

Añadido en: astro@5.14.2

Devuelve una lista de patrones de host permitidos para peticiones entrantes cuando se usa renderizado on-demand como está configurado en security.allowedDomains.

app.removeBase()

Type: (pathname: string) => string

Añadido en: astro@1.6.4

Elimina el base del path dado. Esto es útil cuando necesitas buscar assets desde el sistema de archivos.

app.setCookieHeaders()

Type: (response: Response) => Generator<string, string[], any>

Añadido en: astro@1.4.0

Devuelve un generador que produce valores individuales de headers de cookie desde un objeto Response. Esto se usa para manejar correctamente múltiples cookies que pueden haberse establecido durante el procesamiento de la petición.

El siguiente ejemplo añade un header Set-Cookie por cada header obtenido de una respuesta:

for (const setCookieHeader of app.setCookieHeaders(response)) {
  response.headers.append('Set-Cookie', setCookieHeader);
}

Importaciones desde astro/app/node

Los siguientes helpers se importan desde el directorio node en el módulo app:

import {
  createRequest,
  writeResponse
} from "astro/app/node";

Este módulo se usa en conjunto con los métodos proporcionados por createApp() para convertir un IncomingMessage de NodeJS en un Request estándar web y streamar un Response estándar web a un ServerResponse de NodeJS.

createRequest()

Type: (req: NodeRequest, options?: { skipBody?: boolean; allowedDomains?: Partial<RemotePattern>[]; }) => Request

Añadido en: astro@6.0.0

Convierte un IncomingMessage de NodeJS en un objeto Request estándar. Se puede pasar un objeto opcional como segundo argumento para controlar aún más cómo se crea la petición. Esto es útil si quieres ignorar el body (por defecto es false) o pasar los allowedDomains configurados a la petición.

El siguiente ejemplo crea un Request y lo pasa a app.render():

import { createApp } from "astro/app/entrypoint";
import { createRequest } from "astro/app/node";
import { createServer } from "node:http";

const app = createApp();

const server = createServer(async (req, res) => {
  const request = createRequest(req);
  const response = await app.render(request);
})

writeResponse()

Type: (source: Response, destination: ServerResponse) => Promise<ServerResponse<IncomingMessage> | undefined>

Añadido en: astro@6.0.0

Streama un Response estándar web a una respuesta de servidor NodeJS. Esta función toma un objeto Response y el ServerResponse inicial antes de devolver una promise de un objeto ServerResponse.

El siguiente ejemplo crea un Request, lo pasa a app.render(), y escribe la respuesta:

import { createApp } from "astro/app/entrypoint";
import { createRequest, writeResponse } from "astro/app/node";
import { createServer } from "node:http";

const app = createApp();

const server = createServer(async (req, res) => {
  const request = createRequest(req);
  const response = await app.render(request);
  await writeResponse(response, res);
})

Tipos de astro/app

Los siguientes tipos se importan desde el módulo app:

import type {
  RenderOptions,
} from "astro/app";

RenderOptions

Type: {addCookieHeader?: boolean; clientAddress?: string; locals?: object; prerenderedErrorPageFetch?: (url: ErrorPagePath) => Promise<Response>; waitUntil?: (promise: Promise<unknown>) => void; routeData?: RouteData;}

Describe las opciones para controlar el renderizado de rutas.

RenderOptions.addCookieHeader

Type: boolean
Default: false

Si añadir o no automáticamente todas las cookies escritas por Astro.cookie.set() a los headers de respuesta.

Cuando se establece a true, se añadirán al header Set-Cookie de la respuesta como pares clave-valor separados por comas. Puedes usar la API estándar response.headers.getSetCookie() para leerlos individualmente.

const response = await app.render(request, { addCookieHeader: true });

RenderOptions.clientAddress

Type: string
Default: request[Symbol.for("astro.clientAddress")]

La dirección IP del cliente que estará disponible como Astro.clientAddress en páginas, y como ctx.clientAddress en rutas de API y middleware.

El ejemplo siguiente lee el header x-forwarded-for y lo pasa como clientAddress. Este valor se vuelve disponible para el usuario como Astro.clientAddress.

const clientAddress = request.headers.get("x-forwarded-for");
const response = await app.render(request, { clientAddress });

RenderOptions.locals

Type: object

El objeto context.locals usado para almacenar y acceder a información durante el ciclo de vida de una petición.

El ejemplo siguiente lee un header llamado x-private-header, intenta parsearlo como un objeto, y lo pasa a locals, que luego puede pasarse a cualquier función de middleware.

const privateHeader = request.headers.get("x-private-header");
let locals = {};
try {
  if (privateHeader) {
    locals = JSON.parse(privateHeader);
  }
} finally {
  const response = await app.render(request, { locals });
}

RenderOptions.prerenderedErrorPageFetch()

Type: (url: ErrorPagePath) => Promise<Response>
Default: fetch

Añadido en: astro@5.6.0

Una función que te permite proporcionar implementaciones personalizadas para obtener páginas de error prerenderizadas.

Esto se usa para sobrescribir el comportamiento por defecto de fetch(), por ejemplo, cuando fetch() no está disponible o cuando no puedes llamar al servidor desde sí mismo.

El siguiente ejemplo lee 500.html y 404.html desde el disco en lugar de realizar una llamada HTTP:

return app.render(request, {
  prerenderedErrorPageFetch: async (url: string): Promise<Response> => {
    if (url.includes("/500")) {
      const content = await fs.promises.readFile("500.html", "utf-8");
      return new Response(content, {
        status: 500,
        headers: { "Content-Type": "text/html" },
      });
    }

    const content = await fs.promises.readFile("404.html", "utf-8");
    return new Response(content, {
      status: 404,
      headers: { "Content-Type": "text/html" },
    });
  }
});

Si no se proporciona, Astro recurrirá a su comportamiento por defecto para obtener páginas de error.

RenderOptions.waitUntil()

Type: (promise: Promise<unknown>) => void

Añadido en: astro@6.2.0

Un hook de runtime opcional para trabajo en background después de que se envía la respuesta.

Los adapters pueden pasar esto para permitir que los proveedores de caché de runtime programen trabajo como escrituras de caché o stale-while-revalidate sin bloquear el path de respuesta.

El siguiente ejemplo reenvía una implementación de waitUntil() del runtime a app.render() en un server entrypoint de adapter:

import { createApp } from 'astro/app/entrypoint';

const app = createApp();

export async function handler(event, context) {
  // ...
  return app.render(event.request, {
    waitUntil: context.waitUntil.bind(context),
  });
}

RenderOptions.routeData

Type: RouteData
Default: app.match(request)

Define la información sobre una ruta. Esto es útil cuando ya conoces la ruta a renderizar. Hacerlo omitirá la llamada interna a app.match() para determinar la ruta a renderizar.

const routeData = app.match(request);
if (routeData) {
  return app.render(request, { routeData });
} else {
  /* adapter-specific 404 response */
  return new Response(..., { status: 404 });
}