Referencia de la API de Middleware

Añadido en: astro@2.6.0

El middleware te permite interceptar solicitudes y respuestas e inyectar comportamientos dinámicamente cada vez que una página o endpoint está a punto de renderizarse. Para características y ejemplos de uso, consulta nuestra guía de middleware.

Importaciones desde astro:middleware

Los siguientes helpers se importan desde el módulo virtual de middleware:

import {
  defineMiddleware,
  sequence,
} from 'astro:middleware';

defineMiddleware()

Type: (fn: MiddlewareHandler) => MiddlewareHandler

Una función para definir una función de middleware con seguridad de tipos. Cuando usas esta utilidad, los argumentos context y next() se tipan automáticamente, y obtendrás un error de TypeScript si intentas devolver un valor no soportado en tu middleware.

src/middleware.ts

import { defineMiddleware } from "astro:middleware";

export const onRequest = defineMiddleware((context, next) => {
  /* your middleware logic */
});

sequence()

Type: (…handlers: MiddlewareHandler[]) => MiddlewareHandler

Una función que acepta funciones de middleware como argumentos, y las ejecutará en el orden en que se pasan.

src/middleware.js

import { sequence } from "astro:middleware";

async function validation(context, next) {/* ... */}
async function auth(context, next) {/* ... */}
async function greeting(context, next) {/* ... */}

export const onRequest = sequence(validation, auth, greeting);

Importaciones desde astro/middleware

Los siguientes helpers pueden importarse desde el módulo regular de middleware cuando construyes una Integración de Astro:

import {
  createContext,
  defineMiddleware,
  sequence,
  trySerializeLocals,
} from "astro/middleware";

createContext()

Type: (context: CreateContext) => APIContext

Añadido en: astro@2.8.0

Una API de bajo nivel para crear un APIContext para pasar a una función onRequest() de middleware de Astro.

Esta función puede ser usada por integraciones/adaptadores para ejecutar programáticamente el middleware de Astro.

defineMiddleware()

Ver defineMiddleware() desde astro:middleware.

sequence()

Ver sequence() desde astro:middleware.

trySerializeLocals()

Type: (value: unknown) => string

Añadido en: astro@2.8.0

Una API de bajo nivel que toma cualquier valor e intenta devolver una versión serializada (un string) del mismo. Si el valor no puede serializarse, la función lanzará un error en runtime.

Tipos de astro/middleware

Los siguientes tipos se importan desde el módulo regular de middleware:

import type {
  CreateContext,
} from "astro/middleware";

CreateContext

Tipo: { request: Request; params?: Params; userDefinedLocales?: string[]; defaultLocale: string; locals: App.Locals; clientAddress?: string }

Añadido en: astro@2.8.0

Un objeto para crear un context para pasar a un middleware de Astro. Esto contiene las siguientes propiedades:

CreateContext.request

Type: Request

El objeto Request entrante.

CreateContext.params

Type: Params

Un objeto que contiene los parámetros opcionales a pasar a Astro.params.

CreateContext.userDefinedLocales

Type: string[]

Añadido en: astro@3.5.0

Una lista de locales soportados definidos en la configuración i18n del usuario.

CreateContext.defaultLocale

Type: string

Añadido en: astro@4.16.0

El locale por defecto definido en la configuración i18n del usuario.

CreateContext.locals

Type: App.Locals

Añadido en: astro@5.0.0

Un objeto para almacenar información arbitraria desde un middleware, accesible para el usuario vía Astro.locals.

Aprende más sobre almacenar datos en locals con ejemplos de uso.

CreateContext.clientAddress

Type: string

Añadido en: astro@6.0.0

La dirección IP de la solicitud.

Esto debe ser proporcionado por el adaptador o plataforma desde una fuente confiable (ej. dirección de socket, header proporcionado por la plataforma).

Si no se proporciona, acceder a clientAddress lanzará un error.

Tipos de astro

import type {
  MiddlewareHandler,
  MiddlewareNext,
  RewritePayload,
} from "astro";

MiddlewareHandler

Tipo: (context: APIContext, next: MiddlewareNext) => Promise<Response> | Response | Promise<void> | void

Representa una función de middleware de Astro. Los handlers de middleware reciben dos argumentos y pueden devolver una Response directamente o llamar a next() para invocar el siguiente middleware en la cadena. Alternativamente, puedes usar defineMiddleware() para obtener seguridad de tipos en tu middleware.

El siguiente ejemplo importa el tipo MiddlewareHandler para obtener seguridad de tipos en la función onRequest():

src/middleware.ts

import type { MiddlewareHandler } from "astro";

export const onRequest: MiddlewareHandler = (context, next) => {
  /* the middleware logic */
};

Un handler de middleware recibe las siguientes propiedades:

context

Type: APIContext

Un objeto de context de Astro que refleja muchas de las propiedades globales de Astro.

next()

Type: MiddlewareNext

Una función que llama a todo el middleware subsiguiente en la cadena y devuelve una Response. Por ejemplo, otro middleware podría modificar el body HTML de una respuesta y esperar el resultado de next() permitiría a tu middleware responder a esos cambios.

Desde Astro v4.13.0, next() acepta un parámetro opcional de ruta URL en forma de string, URL, o Request para hacer un rewrite de la solicitud actual sin desencadenar una nueva fase de renderizado.

El siguiente ejemplo usa next() para servir contenido desde una ruta diferente cuando la ruta actual coincide con /old-path:

src/middleware.ts

import type { MiddlewareHandler } from "astro";

export const onRequest: MiddlewareHandler = (context, next) => {
  if (context.url.pathname === '/old-path') {
    return next('/new-path');
  }
  return next();
};

MiddlewareNext

Type: (rewritePayload?: RewritePayload) => Promise<Response>

Representa la función next() pasada a los handlers de middleware.

RewritePayload

Type: string | URL | Request

Agregado en: astro@4.13.0

Representa el destino de un rewrite cuando se pasa a la función next().

Exports de middleware

Al definir el middleware de tu proyecto en src/middleware.js, exporta las siguientes funciones definidas por el usuario:

onRequest()

Type: MiddlewareHandler

Una función exportada obligatoria desde src/middleware.js que será llamada antes de renderizar cada página o API route. Recibe dos argumentos: context y next(). onRequest() debe devolver una Response: ya sea directamente, o llamando a next().

src/middleware.js

export function onRequest (context, next) {
  // intercept response data from a request
  // optionally, transform the response
  // return a Response directly, or the result of calling `next()`
  return next();
};