API des adaptateurs d'Astro

Astro est conçu pour faciliter le déploiement vers n’importe quel fournisseur de cloud pour le rendu à la demande, également appelé rendu côté serveur (SSR). Cette capacité est fournie par des adaptateurs, qui sont des intégrations. Consultez le guide de rendu à la demande pour apprendre à utiliser un adaptateur existant.

Qu’est-ce qu’un adaptateur ?

Un adaptateur est un type particulier d’intégration qui fournit un point d’entrée pour le rendu côté serveur au moment de la demande. Un adaptateur a accès à l’intégralité de l’API des intégrations et a deux fonctions :

Il implémente des API spécifiques à l’hôte pour la gestion des requêtes.
Il configure la compilation selon les conventions de l’hôte.

Création d’un adaptateur

Créez une intégration et appelez la fonction setAdapter() dans le hook astro:config:done. Cela vous permet de définir un point d’entrée pour le serveur et les fonctionnalités prises en charge par votre adaptateur.

L’exemple suivant crée un adaptateur avec un point d’entrée pour le serveur et une prise en charge stable du mode de sortie statique d’Astro :

export default function createIntegration() {
  return {
    name: '@exemple/mon-adaptateur',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@exemple/mon-adaptateur',
          serverEntrypoint: '@exemple/mon-adaptateur/serveur.js',
          supportedAstroFeatures: {
            staticOutput: 'stable'
          }
        });
      },
    },
  };
}

La fonction setAdapter() accepte un objet contenant les propriétés suivantes :

`name`

Type : string

Définit un nom unique pour votre adaptateur. Ce nom sera utilisé pour la journalisation.

`serverEntrypoint`

Type : string | URL

Définit le point d’entrée pour le rendu à la demande.

Apprenez-en davantage sur la création d’un point d’entrée de serveur.

`supportedAstroFeatures`

Type : AstroAdapterFeatureMap

Ajouté à la version : astro@3.0.0

Une table des correspondance des fonctionnalités intégrées à Astro prises en charge par l’adaptateur. Cela permet à Astro de déterminer quelles fonctionnalités sont prises en charge par un adaptateur, afin de pouvoir fournir des messages d’erreur appropriés.

Découvrez les fonctionnalités d’Astro disponibles configurables par un adaptateur.

`adapterFeatures`

Type : AstroAdapterFeatures

Ajouté à la version : astro@3.0.0

Un objet qui spécifie quelles fonctionnalités d’adaptateur modifiant la sortie de la compilation sont prises en charge par l’adaptateur.

`args`

Type : any

Une valeur sérialisable en JSON qui sera transmise au point d’entrée du serveur de l’adaptateur au moment de l’exécution. Ceci est utile pour transmettre un objet contenant la configuration de compilation (par exemple, les chemins d’accès, les secrets) au code de l’environnement d’exécution de votre serveur.

L’exemple suivant définit un objet args avec une propriété qui identifie l’emplacement des ressources générées par Astro :

export default function createIntegration() {
  return {
    name: '@exemple/mon-adaptateur',
    hooks: {
      'astro:config:done': ({ config, setAdapter }) => {
        setAdapter({
          name: '@exemple/mon-adaptateur',
          serverEntrypoint: '@exemple/mon-adaptateur/serveur.js',
          args: {
            assets: config.build.assets
          }
        });
      },
    },
  };
}

`client`

Type : { internalFetchHeaders?: Record<string, string> | () => Record<string, string>; assetQueryParams?: URLSearchParams; }

Ajouté à la version : astro@5.15.0 Nouveau

Un objet de configuration pour le code côté client d’Astro.

`internalFetchHeaders`

Type : Record<string, string> | () => Record<string, string>

Définit les en-têtes à injecter dans les appels de récupération internes d’Astro (par exemple, les actions, les transitions de vue, les îlots de serveur, le préchargement). Il peut s’agir d’un objet d’en-têtes ou d’une fonction renvoyant des en-têtes.

L’exemple suivant récupère un identifiant de déploiement (DEPLOY_ID) à partir des variables d’environnement et, s’il est fourni, renvoie un objet avec le nom de l’en-tête en tant que nom de propriété et l’identifiant du déploiement en tant que valeur :

export default function createIntegration() {
  return {
    name: '@exemple/mon-adaptateur',
    hooks: {
      'astro:config:done': ({ config, setAdapter }) => {
        setAdapter({
          name: '@exemple/mon-adaptateur',
          serverEntrypoint: '@exemple/mon-adaptateur/serveur.js',
          client: {
            internalFetchHeaders: () => {
              const deployId = process.env.DEPLOY_ID;
              return deployId ? { 'ID-De-Votre-En-Tete': deployId } : {};
            },
          },
        });
      },
    },
  };
}

`assetQueryParams`

Type : URLSearchParams

Définit les paramètres de requête à ajouter à toutes les URL des ressources (images, feuilles de style, scripts, etc.). Ceci est utile pour les adaptateurs qui doivent suivre les versions de déploiement ou d’autres métadonnées.

L’exemple suivant récupère un identifiant de déploiement (DEPLOY_ID) à partir des variables d’environnement et, s’il est fourni, renvoie un objet avec un nom de paramètre de recherche personnalisé comme nom de propriété et l’identifiant de déploiement comme valeur :

export default function createIntegration() {
  return {
    name: '@exemple/mon-adaptateur',
    hooks: {
      'astro:config:done': ({ config, setAdapter }) => {
        setAdapter({
          name: '@exemple/mon-adaptateur',
          serverEntrypoint: '@exemple/mon-adaptateur/serveur.js',
          client: {
            assetQueryParams: process.env.DEPLOY_ID
              ? new URLSearchParams({ yourParam: process.env.DEPLOY_ID })
              : undefined,
          },
        });
      },
    },
  };
}

`exports`

Type : string[]

Définit un tableau d’exportations nommées à utiliser en conjonction avec la fonction createExports() de votre point d’entrée de serveur.

L’exemple suivant suppose que createExports() fournit une exportation nommée handler :

export default function createIntegration() {
  return {
    name: '@exemple/mon-adaptateur',
    hooks: {
      'astro:config:done': ({ config, setAdapter }) => {
        setAdapter({
          name: '@exemple/mon-adaptateur',
          serverEntrypoint: '@exemple/mon-adaptateur/serveur.js',
          exports: ['handler']
        });
      },
    },
  };
}

`previewEntrypoint`

Type : string | URL

Ajouté à la version : astro@1.5.0

Définit le chemin ou l’ID d’un module dans le paquet de l’adaptateur qui est responsable du démarrage du serveur compilé lorsque astro preview est exécuté.

export default function createIntegration() {
  return {
    name: '@exemple/mon-adaptateur',
    hooks: {
      'astro:config:done': ({ config, setAdapter }) => {
        setAdapter({
          name: '@exemple/mon-adaptateur',
          serverEntrypoint: '@exemple/mon-adaptateur/serveur.js',
          previewEntrypoint: '@exemple/mon-adaptateur/previsualisation.js',
        });
      },
    },
  };
}

Création d’un point d’entrée de serveur

Vous devrez créer un fichier qui s’exécute lors des requêtes côté serveur afin d’activer le rendu à la demande avec votre hôte. L’API des adaptateurs d’Astro tente de fonctionner avec n’importe quel type d’hôte et offre une méthode flexible pour se conformer aux API de l’hôte.

`createExports()`

Type : (manifest: SSRManifest, options: any) => Record<string, any>

Une fonction exportée qui prend un manifeste SSR comme premier argument et un objet contenant les args de votre adaptateur comme second argument. Elle doit fournir les exportations requises par votre hôte.

Par exemple, certains hôtes serverless s’attendent à ce que vous exportiez une fonction handler(). Avec l’API des adaptateurs, vous y parvenez en implémentant createExports() dans votre point d’entrée de serveur :

import { App } from 'astro/app';

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

  const handler = (event, context) => {
    // ...
  };

  return { handler };
}

Ensuite, dans votre intégration, lorsque vous appelez setAdapter(), fournissez ce nom dans exports :

export default function createIntegration() {
  return {
    name: '@exemple/mon-adaptateur',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@exemple/mon-adaptateur',
          serverEntrypoint: '@exemple/mon-adaptateur/serveur.js',
          exports: ['handler'],
        });
      },
    },
  };
}

Vous pouvez accéder aux args définis par votre adaptateur via le deuxième argument de createExports(). Cela peut s’avérer utile lorsque vous avez besoin d’accéder à la configuration de compilation dans le point d’entrée de votre serveur. Par exemple, votre serveur pourrait avoir besoin d’identifier l’emplacement des ressources générées par Astro :

import { App } from 'astro/app';

export function createExports(manifest, args) {
  const assetsPath = args.assets;

  const handler = (event, context) => {
    // ...
  };

  return { handler };
}

`start()`

Type : (manifest: SSRManifest, options: any) => Record<string, any>

Une fonction exportée qui prend un manifeste SSR comme premier argument et un objet contenant les args de votre adaptateur comme deuxième argument.

Certains hôtes s’attendent à ce que vous démarriez le serveur vous-même, par exemple en écoutant un port. Pour ces types d’hôtes, l’API des adaptateurs vous permet d’exporter une fonction start(), qui sera appelée lors de l’exécution du script du bundle.

import { App } from 'astro/app';

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

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

`astro/app`

Ce module est utilisé pour afficher les pages qui ont été pré-compilées par astro build. Astro utilise les objets standards Request et Response. Les hôtes qui ont une API différente pour les requêtes/réponses doivent convertir ces types dans leur adaptateur.

Le constructeur d’App accepte un argument obligatoire pour le manifeste SSR et, en option, un argument pour activer ou désactiver le streaming, utilisant true comme valeur par défaut.

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

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

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

Les méthodes suivantes sont proposées :

`app.render()`

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

Une méthode qui accepte un argument request obligatoire et un objet RenderOptions facultatif. Elle appelle la page Astro qui correspond à la requête, la génère et renvoie la promesse d’un objet Response. Cela fonctionne également pour les routes d’API qui ne génèrent pas de pages.

const response = await app.render(request);

`RenderOptions`

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

Un objet qui contrôle le rendu et qui contient les propriétés suivantes :

`addCookieHeader`

Type : boolean
Par défaut : false

Définit s’il faut ou non ajouter automatiquement tous les cookies écrits par Astro.cookie.set() aux en-têtes de la réponse.

Lorsque l’option est définie sur true, ils seront ajoutés à l’en-tête Set-Cookie de la réponse sous forme de paires clé-valeur séparées par des virgules. Vous pouvez utiliser l’API standard response.headers.getSetCookie() pour les lire individuellement. Lorsque l’option est définie sur false (par défaut), les cookies ne seront disponibles qu’à partir de App.getSetCookieFromResponse(response).

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

`clientAddress`

Type : string
Par défaut : request[Symbol.for("astro.clientAddress")]

L’adresse IP du client qui sera disponible en tant que Astro.clientAddress dans les pages, et en tant que ctx.clientAddress dans les routes d’API et le middleware.

L’exemple ci-dessous lit l’en-tête x-forwarded-for et le transmet comme clientAddress. Cette valeur devient disponible pour l’utilisateur en tant que Astro.clientAddress.

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

`locals`

Type : object

L’objet context.locals utilisé pour stocker et accéder aux informations pendant le cycle de vie d’une requête.

L’exemple ci-dessous lit un en-tête nommé x-private-header, tente de l’analyser comme un objet et de le passer à locals, qui peut alors être passé à n’importe quelle fonction 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 });
}

`prerenderedErrorPageFetch`

Type : (url: ErrorPagePath) => Promise<Response>
Par défaut : fetch

Ajouté à la version : astro@5.6.0

Une fonction qui vous permet de fournir des implémentations personnalisées pour récupérer des pages d’erreur pré-rendues.

Ceci est utilisé pour remplacer le comportement par défaut de fetch(), par exemple, lorsque fetch() n’est pas disponible ou lorsque vous ne pouvez pas appeler le serveur depuis lui-même.

L’exemple suivant lit 500.html et 404.html à partir du disque au lieu d’effectuer un appel 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 elle n’est pas fournie, Astro reviendra à son comportement par défaut pour récupérer les pages d’erreur.

`routeData`

Type : RouteData
Par défaut : app.match(request)

Fournit une valeur pour integrationRouteData si vous connaissez déjà la route à afficher. En faisant ceci, vous éviterez l’appel interne à app.match() pour déterminer la route à afficher.

const routeData = app.match(request);
if (routeData) {
  return app.render(request, { routeData });
} else {
  /* Réponse 404 spécifique à l'adaptateur */
  return new Response(..., { status: 404 });
}

`app.match()`

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

Détermine si une requête correspond aux règles de routage de l’application Astro.

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

Vous pouvez généralement appeler app.render(request) sans utiliser .match car Astro gère les 404 si vous fournissez un fichier 404.astro. Utilisez app.match(request) si vous voulez gérer les 404 d’une manière différente.

Par défaut, les routes pré-rendues ne sont pas renvoyées, même si elles correspondent. Vous pouvez modifier ce comportement en utilisant true comme deuxième argument.

`app.getAdapterLogger()`

Type : () => AstroIntegrationLogger

Ajouté à la version : astro@v3.0.0

Renvoie une instance du journaliseur d’Astro disponible pour l’environnement d’exécution de l’adaptateur.

const logger = app.getAdapterLogger();
try {
  /* Une logique qui peut générer une erreur */
} catch {
  logger.error("Votre message d'erreur personnalisé utilisant le journaliseur d'Astro.");
}

`app.getAllowedDomains()`

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

Ajouté à la version : astro@5.14.2

Renvoie une liste de modèles d’hôtes autorisés pour les requêtes entrantes lors de l’utilisation du rendu à la demande tels que définis dans la configuration de l’utilisateur.

`app.removeBase()`

Type : (pathname: string) => string

Ajouté à la version : astro@1.6.4

Supprime la base du chemin fourni. Ceci est utile lorsque vous devez rechercher des ressources dans le système de fichiers.

`app.setCookieHeaders()`

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

Ajouté à la version : astro@1.4.0

Renvoie un générateur qui produit des valeurs d’en-tête de cookie individuelles à partir d’un objet Response. Ceci permet de gérer correctement plusieurs cookies susceptibles d’avoir été définis lors du traitement d’une requête.

L’exemple suivant ajoute un en-tête Set-Cookie pour chaque en-tête obtenu à partir d’une réponse :

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

`App.getSetCookieFromResponse()`

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

Ajouté à la version : astro@4.2.0

Renvoie un générateur qui produit des valeurs d’en-tête de cookie individuelles à partir d’un objet Response. Cela fonctionne de la même manière que app.setCookieHeaders(), mais peut être utilisé à tout moment car il s’agit d’une méthode statique.

L’exemple suivant ajoute un en-tête Set-Cookie pour chaque en-tête obtenu à partir d’une réponse :

for (const cookie of App.getSetCookieFromResponse(response)) {
  response.headers.append('Set-Cookie', cookie);
}

`App.validateForwardedHost()`

Type : (forwardedHost: string, allowedDomains?: Partial<RemotePattern>[], protocol?: string = 'https') => boolean

Ajouté à la version : astro@5.14.2

Vérifie si un hôte transféré (forwardedHost) correspond à l’un des domaines autorisés (allowedDomains) donnés. Cette méthode statique accepte un troisième argument permettant de remplacer le protocole de l’hôte, par défaut https.

L’exemple suivant récupère l’hôte transféré (forwardedHost) à partir des en-têtes et vérifie s’il correspond à un domaine autorisé :

export function start(manifest) {
  addEventListener('fetch', (event) => {
    const forwardedHost = event.request.headers.get('X-Forwarded-Host');
    if (App.validateForwardedHost(forwardedHost, manifest.allowedDomains)) {
      /* faire quelque chose */
    }
  });
}

`App.sanitizeHost()`

Type : (hostname: string | undefined) => string | undefined

Ajouté à la version : astro@5.15.5 Nouveau

Valide un nom d’hôte en rejetant tout nom contenant des séparateurs de chemin. Lorsque le nom d’hôte est invalide, cette méthode statique renverra undefined.

L’exemple suivant récupère l’hôte transféré (forwardedHost) à partir des en-têtes et le nettoie :

export function start(manifest) {
  addEventListener('fetch', (event) => {
    const forwardedHost = event.request.headers.get('X-Forwarded-Host');
    const sanitized = App.sanitizeHost(forwardedHost);
  });
}

`App.validateForwardedHeaders()`

Type : (forwardedProtocol?: string, forwardedHost?: string, forwardedPort?: string, allowedDomains?: Partial<RemotePattern>[]) => { protocol?: string; host?: string; port?: string }

Ajouté à la version : astro@5.15.5 Nouveau

Valide le protocole, l’hôte et le port transmis par rapport aux domaines autorisés (allowedDomains). Cette méthode statique renvoie des valeurs validées ou undefined pour les en-têtes rejetés.

L’exemple suivant valide les en-têtes transmis par rapport aux domaines autorisés définis dans le manifeste reçu :

export function start(manifest) {
  addEventListener('fetch', (event) => {
    const validated = App.validateForwardedHeaders(
      request.headers.get('X-Forwarded-Proto') ?? undefined,
      request.headers.get('X-Forwarded-Host') ?? undefined,
      request.headers.get('X-Forwarded-Port') ?? undefined,
      manifest.allowedDomains,
    );
  });
}

`astro/app/node`

Tout comme astro/app, ce module est utilisé pour le rendu des pages qui ont été pré-générées via astro build. Il permet de créer une NodeApp offrant toutes les méthodes disponibles dans App ainsi que des méthodes supplémentaires utiles pour les environnements Node.

Le constructeur de NodeApp accepte un argument de manifeste SSR obligatoire et, en option, un argument pour activer ou désactiver le streaming, par défaut true.

import { NodeApp } from 'astro/app/node';
import http from 'http';

export function start(manifest) {
  const nodeApp = new NodeApp(manifest);

  addEventListener('fetch', event => {
    event.respondWith(
      nodeApp.render(event.request)
    );
  });
}

Les méthodes supplémentaires suivantes sont disponibles :

`nodeApp.render()`

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

Ajouté à la version : astro@4.0.0

Étend app.render() pour accepter également les objets IncomingMessage de Node.js en plus des objets Request standard comme premier argument. Le deuxième argument est un objet optionnel vous permettant de contrôler le rendu.

const response = await nodeApp.render(request);

`nodeApp.match()`

Type : (req: NodeRequest | Request, allowPrerenderedRoutes?: boolean) => RouteData | undefined

Étend app.match() pour accepter également les objets IncomingMessage de Node.js en plus des objets Request standard.

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

`nodeApp.headersMap`

Type : NodeAppHeadersJson | undefined
Default: undefined

Ajouté à la version : astro@5.11.0

Un tableau contenant la configuration des en-têtes. Chaque entrée associe un chemin d’accès à une liste d’en-têtes à appliquer à cette route. Ceci est utile pour appliquer des en-têtes tels que les directives CSP aux routes pré-rendues.

`nodeApp.setHeadersMap()`

Type : (headers: NodeAppHeadersJson) => void

Ajouté à la version : astro@5.11.0

Charge la configuration des en-têtes dans l’instance NodeApp.

nodeApp.setHeadersMap([
  {
    pathname: "/blog",
    headers: [
      { key: "Content-Security-Policy", value: "default-src 'self'" },
    ]
  }
]);

`NodeApp.createRequest()`

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

Ajouté à la version : astro@4.2.0

Convertit un objet IncomingMessage de NodeJS en un objet Request standard. Cette méthode statique accepte un objet optionnel comme deuxième argument, vous permettant de définir si le corps du message doit être ignoré, par défaut false, et les domaines autorisés (allowedDomains).

L’exemple suivant crée un objet Request et le transmet à app.render() :

import { NodeApp } from 'astro/app/node';
import { createServer } from 'node:http';

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

`NodeApp.writeResponse()`

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

Ajouté à la version : astro@4.2.0

Transmet une réponse Response standard du Web vers une réponse de serveur NodeJS. Cette méthode statique prend un objet Response et la réponse initiale du serveur (ServerResponse) avant de renvoyer une promesse d’un objet ServerResponse.

L’exemple suivant crée un objet Request, le transmet à app.render() et écrit la réponse :

import { NodeApp } from 'astro/app/node';
import { createServer } from 'node:http';

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

Fonctionnalités d’Astro

Les fonctionnalités Astro permettent à un adaptateur d’indiquer à Astro s’il est en mesure de prendre en charge une fonctionnalité, ainsi que le niveau de prise en charge de l’adaptateur.

Lors de l’utilisation de ces propriétés, Astro :

exécutera une validation spécifique,
émettra des informations contextuelles dans les journaux.

Ces opérations sont exécutées en fonction des fonctionnalités prises en charge ou non, de leur niveau de prise en charge, de la quantité de journalisation souhaitée et de la configuration propre à l’utilisateur.

La configuration suivante indique à Astro que cet adaptateur dispose d’une prise en charge expérimentale du service d’image intégré et alimenté par Sharp :

export default function createIntegration() {
  return {
    name: '@exemple/mon-adaptateur',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@exemple/mon-adaptateur',
          serverEntrypoint: '@exemple/mon-adaptateur/serveur.js',
          supportedAstroFeatures: {
            sharpImageService: 'experimental'
          }
        });
      },
    },
  };
}

Si le service d’image Sharp est utilisé, Astro affichera un avertissement et une erreur dans le terminal en fonction de la prise en charge de votre adaptateur :

[@exemple/mon-adaptateur] The feature is experimental and subject to issues or changes.

[@exemple/mon-adaptateur] The currently selected adapter `@exemple/mon-adaptateur` is not compatible with the service "Sharp". Your project will NOT be able to build.

Un message peut également être fourni pour donner plus de contexte à l’utilisateur :

export default function createIntegration() {
  return {
    name: '@exemple/mon-adaptateur',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@exemple/mon-adaptateur',
          serverEntrypoint: '@exemple/mon-adaptateur/serveur.js',
          supportedAstroFeatures: {
            sharpImageService: {
              support: 'limited',
              message: 'Cet adaptateur a une prise en charge limitée pour Sharp. Certaines fonctionnalités peuvent ne pas fonctionner comme prévu.'
            }
          }
        });
      },
    },
  };
}

Cet objet contient les fonctionnalités configurables suivantes :

`staticOutput`

Type : AdapterSupport

Indique si l’adaptateur est capable de servir des pages statiques.

`hybridOutput`

Type : AdapterSupport

Indique si l’adaptateur est capable de gérer des sites comprenant un mélange de pages statiques et de pages rendues à la demande.

`serverOutput`

Type : AdapterSupport

Indique si l’adaptateur est capable de servir des pages rendues à la demande.

`i18nDomains`

Type : AdapterSupport

Ajouté à la version : astro@4.3.0

Définit si l’adaptateur est capable de prendre en charge les domaines i18n.

`envGetSecret`

Type : AdapterSupport

Ajouté à la version : astro@4.10.0

Définit si l’adaptateur est capable de prendre en charge getSecret() exporté depuis astro:env/server. Lorsqu’elle est activée, cette fonctionnalité permet à votre adaptateur de récupérer les secrets configurés par les utilisateurs dans env.schema.

L’exemple suivant active cette fonctionnalité en transmettant une valeur AdapterSupportsKind valide à l’adaptateur :

export default function createIntegration() {
  return {
    name: '@exemple/mon-adaptateur',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@exemple/mon-adaptateur',
          serverEntrypoint: '@exemple/mon-adaptateur/serveur.js',
          adapterFeatures: {
            envGetSecret: 'stable'
          }
        });
      },
    },
  };
}

Le module astro/env/setup vous permet de fournir une implémentation pour getSecret(). Dans le point d’entrée de votre serveur, appelez setGetEnv() dès que possible :

import { App } from 'astro/app';
import { setGetEnv } from "astro/env/setup"

setGetEnv((key) => process.env[key])

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

  const handler = (event, context) => {
    // ...
  };

  return { handler };
}

Si l’adaptateur prend en charge les secrets, veillez à appeler setGetEnv() avant getSecret() lorsque des variables d’environnement sont liées à la requête :

import type { SSRManifest } from 'astro';
import { App } from 'astro/app';
import { setGetEnv } from 'astro/env/setup';
import { createGetEnv } from '../utils/env.js';

type Env = {
  [key: string]: unknown;
};

export function createExports(manifest: SSRManifest) {
  const app = new App(manifest);

  const fetch = async (request: Request, env: Env) => {
    setGetEnv(createGetEnv(env));

    const response = await app.render(request);

    return response;
  };

  return { default: { fetch } };
}

`sharpImageService`

Type : AdapterSupport

Ajouté à la version : astro@5.0.0

Définit si l’adaptateur prend en charge la transformation d’images à l’aide du service d’images Sharp intégré.

Fonctionnalités de l’adaptateur

Un ensemble de fonctionnalités qui modifient le format des fichiers générés. Lorsqu’un adaptateur active ces fonctionnalités, il recevra des informations supplémentaires dans des hooks spécifiques et devra implémenter la logique appropriée pour gérer les différents formats de sortie.

`edgeMiddleware`

Type : boolean

Définit si un code middleware de rendu à la demande sera regroupé lors de la compilation.

Lorsque cette option est activée, elle empêche le code middleware d’être regroupé et importé par toutes les pages pendant la compilation :

export default function createIntegration() {
  return {
    name: '@exemple/mon-adaptateur',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@exemple/mon-adaptateur',
          serverEntrypoint: '@exemple/mon-adaptateur/serveur.js',
          adapterFeatures: {
            edgeMiddleware: true
          }
        });
      },
    },
  };
}

Ensuite, utilisez le hook astro:build:ssr, qui vous donnera un middlewareEntryPoint, une URL vers le fichier physique sur le système de fichiers.

export default function createIntegration() {
  return {
    name: '@exemple/mon-adaptateur',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@exemple/mon-adaptateur',
          serverEntrypoint: '@exemple/mon-adaptateur/serveur.js',
          adapterFeatures: {
            edgeMiddleware: true
          }
        });
      },

      'astro:build:ssr': ({ middlewareEntryPoint }) => {
        // n'oubliez pas de vérifier si cette propriété existe, elle sera `undefined` si l'adaptateur n'accepte pas la fonctionnalité
        if (middlewareEntryPoint) {
          createEdgeMiddleware(middlewareEntryPoint)
        }
      }
    },
  };
}

function createEdgeMiddleware(middlewareEntryPoint) {
  // émet un nouveau fichier physique en utilisant votre bundler
}

buildOutput

Type : 'static' | 'server'
Par défaut : "server"

Ajouté à la version : astro@5.0.0

Permet de forcer un format de sortie spécifique pour la compilation. Cela peut s’avérer utile pour les adaptateurs qui ne fonctionnent qu’avec un type de sortie spécifique. Par exemple, votre adaptateur peut s’attendre à un site web statique, mais utiliser un adaptateur pour créer des fichiers spécifiques à l’hôte. La valeur par défaut est server si elle n’est pas spécifiée.

export default function createIntegration() {
  return {
    name: '@exemple/mon-adaptateur',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@exemple/mon-adaptateur',
          serverEntrypoint: '@exemple/mon-adaptateur/serveur.js',
          adapterFeatures: {
            buildOutput: 'static'
          }
        });
      },
    },
  };
}

experimentalStaticHeaders

Type : boolean

Ajouté à la version : astro@5.9.3

Indique si l’adaptateur dispose d’une prise en charge expérimentale pour configurer les en-têtes de réponse avec les pages statiques. Lorsque cette fonctionnalité est activée, Astro renvoie une table de correspondance des en-têtes émis par les pages statiques. Cette table experimentalRouteToHeaders est disponible dans le hook astro:build:generated pour générer des fichiers tels que _headers qui vous permet de modifier l’en-tête HTTP par défaut.

export default function createIntegration() {
  return {
    name: '@exemple/mon-adaptateur',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@exemple/mon-adaptateur',
          serverEntrypoint: '@exemple/mon-adaptateur/serveur.js',
          adapterFeatures: {
            experimentalStaticHeaders: true,
          },
        });
      },
      'astro:build:generated': ({ experimentalRouteToHeaders }) => {
        // utiliser `experimentalRouteToHeaders` pour générer un fichier de configuration
        // pour l'hôte virtuel de votre choix
      },
    },
  };
}

La valeur des en-têtes peut varier selon les fonctionnalités activées ou utilisées par l’application. Par exemple, si la politique de sécurité du contenu (CSP) est activée, l’élément <meta http-equiv="content-security-policy"> n’est pas ajouté à la page statique. À la place, son contenu (content) est disponible dans la table de correspondance experimentalRouteToHeaders.

Référence des types des adaptateurs

`AdapterSupport`

Type : AdapterSupportsKind | AdapterSupportWithMessage

Ajouté à la version : astro@5.0.0

Une union de formats valides pour décrire le niveau de prise en charge d’une fonctionnalité.

`AdapterSupportsKind`

Type : "deprecated" | "experimental" | "limited" | "stable" | "unsupported"

Définit le niveau de prise en charge d’une fonctionnalité par votre adaptateur :

Utilisez "deprecated" lorsque votre adaptateur abandonne la prise en charge d’une fonctionnalité avant de la supprimer complètement dans une version ultérieure.
Utilisez "experimental" lorsque votre adaptateur ajoute la prise en charge d’une fonctionnalité, mais que des problèmes ou des changements incompatibles sont à prévoir.
Utilisez "limited" lorsque votre adaptateur ne prend en charge qu’un sous-ensemble des fonctionnalités complètes.
Utilisez "stable" lorsque la fonctionnalité est entièrement prise en charge par votre adaptateur.
Utilisez "unsupported" pour avertir les utilisateurs qu’ils pourraient rencontrer des problèmes de compilation dans leur projet, car cette fonctionnalité n’est pas prise en charge par votre adaptateur.

`AdapterSupportWithMessage`

Ajouté à la version : astro@5.0.0

Un objet qui vous permet de définir un niveau de prise en charge pour une fonctionnalité et un message à afficher dans la console de l’utilisateur. Cet objet contient les propriétés suivantes :

`support`

Type : Exclude<AdapterSupportsKind, “stable”>

Définit le niveau de prise en charge d’une fonctionnalité par votre adaptateur.

`message`

Type : string

Définit un message personnalisé à afficher concernant la prise en charge d’une fonctionnalité par votre adaptateur.

`suppress`

Type : 'default' | 'all'

Ajouté à la version : astro@5.9.0

Une option permettant d’empêcher l’affichage de certains ou de tous les messages de journalisation concernant la prise en charge d’une fonctionnalité par un adaptateur.

Si le message de journalisation par défaut d’Astro est redondant ou déroutant pour l’utilisateur en combinaison avec votre message personnalisé, vous pouvez utiliser suppress: "default" pour supprimer le message par défaut et journaliser uniquement votre message :

export default function createIntegration() {
  return {
    name: '@exemple/mon-adaptateur',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@exemple/mon-adaptateur',
          serverEntrypoint: '@exemple/mon-adaptateur/serveur.js',
          supportedAstroFeatures: {
            sharpImageService: {
              support: 'limited',
              message: "L'adaptateur possède une prise en charge limitée de Sharp. Il sera utilisé pour les images lors de la compilation, mais ne fonctionnera pas à l'exécution.",
              suppress: 'default' // le message personnalisé est plus détaillé que le message par défaut
            }
          }
        });
      },
    },
  };
}

Vous pouvez également utiliser suppress: "all" pour supprimer tous les messages concernant la prise en charge de la fonctionnalité. Ceci est utile lorsque ces messages sont inutiles pour les utilisateurs dans un contexte spécifique, par exemple lorsqu’un paramètre de configuration les empêche d’utiliser cette fonctionnalité. Par exemple, vous pouvez choisir d’empêcher la journalisation de tout message concernant la prise en charge de Sharp à partir de votre adaptateur :

export default function createIntegration() {
  return {
    name: '@exemple/mon-adaptateur',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@exemple/mon-adaptateur',
          serverEntrypoint: '@exemple/mon-adaptateur/serveur.js',
          supportedAstroFeatures: {
            sharpImageService: {
              support: 'limited',
              message: 'Cet adaptateur possède une prise en charge limitée de Sharp. Certaines fonctionnalités peuvent ne pas fonctionner correctement.',
              suppress: 'all'
            }
          }
        });
      },
    },
  };
}

Autoriser l’installation via `astro add`

La commande astro add permet aux utilisateurs d’ajouter facilement des intégrations et des adaptateurs à leur projet. Si vous voulez que votre adaptateur soit installable avec cet outil, ajoutez astro-adapter au champ keywords de votre fichier package.json :

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

Une fois que vous publiez votre adaptateur sur npm, l’exécution de astro add example installera votre paquet avec toutes les dépendances homologues spécifiées dans votre fichier package.json et demandera aux utilisateurs de mettre à jour manuellement la configuration de leur projet.

Contribuer Communauté Parrainer

API des adaptateurs d'Astro

Qu’est-ce qu’un adaptateur ?

Création d’un adaptateur

name

serverEntrypoint

supportedAstroFeatures

adapterFeatures

args

client

internalFetchHeaders

assetQueryParams

exports

previewEntrypoint

Création d’un point d’entrée de serveur

createExports()

start()

astro/app

app.render()

RenderOptions

addCookieHeader

clientAddress

locals

prerenderedErrorPageFetch

routeData

app.match()

app.getAdapterLogger()

app.getAllowedDomains()

app.removeBase()

app.setCookieHeaders()

App.getSetCookieFromResponse()

App.validateForwardedHost()

App.sanitizeHost()

App.validateForwardedHeaders()

astro/app/node

nodeApp.render()

nodeApp.match()

nodeApp.headersMap

nodeApp.setHeadersMap()

NodeApp.createRequest()

NodeApp.writeResponse()

Fonctionnalités d’Astro

staticOutput

hybridOutput

serverOutput

i18nDomains

envGetSecret

sharpImageService

Fonctionnalités de l’adaptateur

edgeMiddleware

buildOutput

experimentalStaticHeaders

Référence des types des adaptateurs

AdapterSupport

AdapterSupportsKind

AdapterSupportWithMessage

support

message

suppress

Autoriser l’installation via astro add

`name`

`serverEntrypoint`

`supportedAstroFeatures`

`adapterFeatures`

`args`

`client`

`internalFetchHeaders`

`assetQueryParams`

`exports`

`previewEntrypoint`

`createExports()`

`start()`

`astro/app`

`app.render()`

`RenderOptions`

`addCookieHeader`

`clientAddress`

`locals`

`prerenderedErrorPageFetch`

`routeData`

`app.match()`

`app.getAdapterLogger()`

`app.getAllowedDomains()`

`app.removeBase()`

`app.setCookieHeaders()`

`App.getSetCookieFromResponse()`

`App.validateForwardedHost()`

`App.sanitizeHost()`

`App.validateForwardedHeaders()`

`astro/app/node`

`nodeApp.render()`

`nodeApp.match()`

`nodeApp.headersMap`

`nodeApp.setHeadersMap()`

`NodeApp.createRequest()`

`NodeApp.writeResponse()`

`staticOutput`

`hybridOutput`

`serverOutput`

`i18nDomains`

`envGetSecret`

`sharpImageService`

`edgeMiddleware`

`AdapterSupport`

`AdapterSupportsKind`

`AdapterSupportWithMessage`

`support`

`message`

`suppress`

Autoriser l’installation via `astro add`