Référence de l'API Middleware

Ajouté à la version : astro@2.6.0

Un middleware vous permet d’intercepter les requêtes et les réponses et d’injecter des comportements de manière dynamique chaque fois qu’une page ou un point de terminaison est sur le point d’être rendu. Pour les fonctionnalités et les exemples d’utilisation, consultez notre guide Middleware.

Importations depuis astro:middleware

Les fonctions d’assistance suivantes sont importées du module middleware virtuel :

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

defineMiddleware()

Type : (fn: MiddlewareHandler) => MiddlewareHandler

Une fonction permettant de définir une fonction middleware avec sûreté du typage. Lorsque vous utilisez cet utilitaire, les arguments context et next() sont automatiquement typés, et vous obtiendrez une erreur Typescript si vous essayez de renvoyer une valeur non prise en charge dans votre middleware.

src/middleware.ts

import { defineMiddleware } from "astro:middleware";

export const onRequest = defineMiddleware((context, next) => {
  /* la logique de votre middleware */
});

sequence()

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

Une fonction qui accepte des fonctions de middleware comme arguments et les exécutera dans l’ordre dans lequel elles sont transmises.

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);

Importations depuis astro/middleware

Les fonctions d’assistance suivantes peuvent être importées depuis le module middleware standard lors de la création d’une intégration Astro :

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

createContext()

Type : (context: CreateContext) => APIContext

Ajouté à la version : astro@2.8.0

Une API de bas niveau pour créer un objet APIContext à transmettre à une fonction onRequest() d’un middleware d’Astro.

Cette fonction peut être utilisée par les intégrations/adaptateurs pour exécuter par programmation le middleware d’Astro.

defineMiddleware()

Voir defineMiddleware() de astro:middleware.

sequence()

Voir sequence() de astro:middleware.

trySerializeLocals()

Type : (value: unknown) => string

Ajouté à la version : astro@2.8.0

Une API de bas niveau qui prend n’importe quelle valeur et tente d’en renvoyer une version sérialisée (une chaîne de caractères). Si la valeur ne peut pas être sérialisée, la fonction générera une erreur d’exécution.

Types d’astro/middleware

Les types suivants sont importés du module middleware standard :

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

CreateContext

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

Ajouté à la version : astro@2.8.0

Un objet pour créer un contexte à transmettre à un middleware Astro. Il contient les propriétés suivantes :

request

Type : Request

L’objet Request entrant.

params

Type : Params

Un objet contenant les paramètres optionnels à transmettre à Astro.params.

userDefinedLocales

Type : string[]

Ajouté à la version : astro@3.5.0

Une liste des paramètres régionaux pris en charge définis dans la configuration i18n de l’utilisateur.

defaultLocale

Type : string

Ajouté à la version : astro@4.16.0

Le paramètre régional par défaut défini dans la configuration i18n de l’utilisateur.

locals

Type : App.Locals

Ajouté à la version : astro@5.0.0

Un objet permettant de stocker des informations arbitraires provenant d’un middleware, accessible à l’utilisateur via Astro.locals.

Apprenez-en davantage sur le stockage des données dans locals avec un exemple d’utilisation.

Types d’astro

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

MiddlewareHandler

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

Représente une fonction middleware pour Astro. Les gestionnaires de middleware reçoivent deux arguments et peuvent soit renvoyer directement un objet Response, soit appeler next() pour invoquer le middleware suivant dans la chaîne. Vous pouvez également utiliser defineMiddleware() pour garantir la sûreté du typage pour votre middleware.

L’exemple suivant importe le type MiddlewareHandler pour garantir la sûreté du typage dans la fonction onRequest() :

src/middleware.ts

import type { MiddlewareHandler } from "astro";

export const onRequest: MiddlewareHandler = (context, next) => {
  /* la logique du middleware */
};

Un gestionnaire de middleware reçoit les propriétés suivantes :

context

Type : APIContext

Un objet de contexte Astro reflétant de nombreuses propriétés globales disponibles dans Astro.

next()

Type : MiddlewareNext

Une fonction qui appelle tous les middlewares suivants dans la chaîne et renvoie un objet Response. Par exemple, d’autres middlewares pourraient modifier le corps HTML d’une réponse et l’attente du résultat de next() permettrait à votre middleware de réagir à ces modifications.

Depuis Astro v4.13.0, next() accepte un paramètre de chemin d’URL facultatif sous la forme d’une chaîne de caractères, d’une URL ou d’un objet Request pour réécrire la requête actuelle sans déclencher une nouvelle phase de rendu.

L’exemple suivant utilise next() pour diffuser du contenu à partir d’un chemin différent lorsque le chemin actuel correspond à /ancien-chemin :

src/middleware.ts

import type { MiddlewareHandler } from "astro";

export const onRequest: MiddlewareHandler = (context, next) => {
  if (context.url.pathname === '/ancien-chemin') {
    return next('/nouveau-chemin');
  }
  return next();
};

MiddlewareNext

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

Représente la fonction next() transmise aux gestionnaires de middleware.

RewritePayload

Type : string | URL | Request

Ajouté à la version : astro@4.13.0

Représente la destination d’une réécriture lorsqu’elle est transmise à la fonction next().

Exportations depuis un middleware

Lors de la définition du middleware de votre projet dans src/middleware.js, exportez les fonctions définies par l’utilisateur suivantes :

onRequest()

Type : MiddlewareHandler

Une fonction requise exportée depuis src/middleware.js qui sera appelée avant le rendu de chaque page ou route d’API. Elle reçoit deux arguments : context et next(). onRequest() doit renvoyer une réponse (Response) : soit directement, soit en appelant next().

src/middleware.js

export function onRequest (context, next) {
    // intercepte les données de réponse d'une requête
    // éventuellement, transforme la réponse
    // renvoie directement une réponse, ou le résultat de l'appel de `next()`
    return next();
};