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ébergeur pour la gestion des requêtes.
Il configure la compilation selon les conventions de l’hébergeur.

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',
          entrypointResolution: 'auto',
          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.

`entrypointResolution`

Type : "explicit" | "auto"
Par défaut : "explicit"

Ajouté à la version : astro@6.0.0

Spécifie la méthode qu’Astro utilisera pour résoudre le point d’entrée du serveur : "auto" (recommandée) ou "explicit" (par défaut, mais dépréciée) :

"auto" (recommandée) : Vous êtes responsable de fournir un module valide comme point d’entrée en utilisant soit serverEntrypoint soit, si vous avez besoin d’une personnalisation supplémentaire au niveau de Vite, en utilisant vite.build.rollupOptions.input.
"explicite" (dépréciée) : Vous devez fournir les exportations requises par l’hébergeur dans le point d’entrée du serveur à l’aide d’une fonction createExports() avant de les transmettre à setAdapter() sous forme d’une liste d’exportations (exports). Cela prend en charge les adaptateurs créés à l’aide de la version Astro 5 de l’API des adaptateurs. Par défaut, tous les adaptateurs recevront cette valeur afin d’assurer la rétrocompatibilité. Toutefois, aucun nouvel adaptateur ne doit être créé avec cette valeur. Les adaptateurs existants doivent remplacer cette valeur par défaut par « auto » dès qu’ils sont compatibles avec la nouvelle API v6.

L’exemple suivant définit entrypointResolution et serverEntrypoint pour indiquer à Astro qu’un point d’entrée personnalisé est fourni :

export default function createIntegration() {
  return {
    name: '@exemple/mon-adaptateur',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@exemple/mon-adaptateur',
          entrypointResolution: 'auto',
          serverEntrypoint: '@exemple/mon-adaptateur/point-entree-personnalise.js',
        });
      },
    },
  };
}

L’exemple suivant définit entrypointResolution et les options de Rollup pour indiquer à Astro qu’un point d’entrée personnalisé est fourni :

export default function createIntegration() {
  return {
    name: '@exemple/mon-adaptateur',
    hooks: {
      'astro:config:setup': ({ updateConfig }) => {
        updateConfig({
          vite: {
            build: {
              rollupOptions: {
                input: '@exemple/mon-adaptateur/point-entree-personnalise.js'
              }
            }
          }
        })
      },
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@exemple/mon-adaptateur',
          entrypointResolution: 'auto',
        });
      },
    },
  };
}

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

`serverEntrypoint`

Type : string | URL

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

`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.

`client`

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

Ajouté à la version : astro@5.15.0

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

`client.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',
          entrypointResolution: 'auto',
          serverEntrypoint: '@exemple/mon-adaptateur/serveur.js',
          client: {
            internalFetchHeaders: () => {
              const deployId = process.env.DEPLOY_ID;
              return deployId ? { 'ID-De-Votre-En-Tete': deployId } : {};
            },
          },
        });
      },
    },
  };
}

`client.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',
          entrypointResolution: 'auto',
          serverEntrypoint: '@exemple/mon-adaptateur/serveur.js',
          client: {
            assetQueryParams: process.env.DEPLOY_ID
              ? new URLSearchParams({ yourParam: process.env.DEPLOY_ID })
              : undefined,
          },
        });
      },
    },
  };
}

`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',
          entrypointResolution: 'auto',
          serverEntrypoint: '@exemple/mon-adaptateur/serveur.js',
          previewEntrypoint: '@exemple/mon-adaptateur/previsualisation.js',
        });
      },
    },
  };
}

`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',
          entrypointResolution: 'explicit',
          args: {
            assets: config.build.assets
          },
          serverEntrypoint: '@exemple/mon-adaptateur/serveur.js'
        });
      },
    },
  };
}

`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',
          entrypointResolution: 'explicit',
          exports: ['handler'],
          serverEntrypoint: '@exemple/mon-adaptateur/serveur.js'
        });
      },
    },
  };
}

Moteur de prérendu personnalisé

Ajouté à la version : astro@6.0.0

Les adaptateurs peuvent fournir un moteur de prérendu personnalisé pour contrôler la façon dont les pages sont prérendues en utilisant la fonction setPrerenderer() dans le hook astro:build:start.

L’exemple suivant montre comment un adaptateur peut définir un moteur de prérendu personnalisé :

export default function createIntegration() {
  return {
    name: '@exemple/mon-adapteur',
    hooks: {
      'astro:build:start': ({ setPrerenderer }) => {
        setPrerenderer((defaultPrerenderer) => ({
          name: 'mon-moteur-de-prerendu',
          async setup() {
            // Démarrer un serveur de prévisualisation
          },
          async getStaticPaths() {
            // Renvoie un tableau de { pathname: string, route: RouteData }
            return defaultPrerenderer.getStaticPaths();
          },
          async render(request, { routeData }) {
            // request: Request, options: { routeData: RouteData }
            // Logique de rendu personnalisée, par exemple, effectuer des requêtes HTTP vers un serveur de prévisualisation
            const response = await fetch(`http://localhost:4321${new URL(request.url).pathname}`);
            return response;
          },
          async teardown() {
            // Arrêter le serveur de prévisualisation
          }
        }));
      },
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@exemple/mon-adapteur',
          entrypointResolution: 'auto',
          serverEntrypoint: '@exemple/mon-adapteur/serveur.js',
        });
      },
    },
  };
}

La fonction de fabrique reçoit le moteur de prérendu par défaut, ce qui vous permet d’encapsuler ou d’étendre son comportement. Ceci est utile lorsque vous n’avez besoin de personnaliser que certains aspects du prérendu.

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ébergeur. L’API des adaptateurs d’Astro tente de fonctionner avec n’importe quel type d’hébergeur et offre une méthode flexible pour se conformer aux API de l’hébergeur.

Vous pouvez importer et utiliser createApp() pour accéder à des méthodes qui vous permettent de travailler avec des objets Request et Response standards.

Ce fichier doit être conforme aux attentes de l’hébergeur. Par exemple, certains hébergeurs serverless exigent que vous exportiez une fonction handler() :

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

const app = createApp();

export async function handler(event, context) {
  // ...
}

Apprenez-en davantage sur les méthodes et les utilitaires disponibles dans la référence de l’API des points d’entrée de serveur des adaptateurs.

Transmission de la configuration de compilation

Si vous devez accéder à la configuration de compilation au niveau du point d’entrée de votre serveur, vous pouvez utiliser un module virtuel. Par exemple, votre serveur pourrait avoir besoin d’identifier l’emplacement des ressources générées par Astro.

Commencez par créer et enregistrer un module d’extension Vite pour sérialiser les données :

const VIRTUAL_MODULE_ID = 'virtual:@exemple/mon-adaptateur:config';
const RESOLVED_VIRTUAL_MODULE_ID = '\0' + VIRTUAL_MODULE_ID;

function createConfigPlugin(config) {
  return {
    name: VIRTUAL_MODULE_ID,
    resolveId: {
      filter: {
        id: new RegExp(`^${VIRTUAL_MODULE_ID}$`),
      },
      handler() {
        return RESOLVED_VIRTUAL_MODULE_ID;
      },
    },
    load: {
      filter: {
        id: new RegExp(`^${RESOLVED_VIRTUAL_MODULE_ID}$`),
      },
      handler() {
        return `
          export const assets = ${JSON.stringify(config.build.assets)};
        `;
      },
    },
  };
}

export default function createIntegration() {
  let _config;
  return {
    name: '@exemple/mon-adaptateur',
    hooks: {
      'astro:config:setup': ({ config, updateConfig }) => {
        _config = config;

        updateConfig({
          vite: {
            plugins: [createConfigPlugin(_config)]
          }
        })
      },
      'astro:config:done': ({ config, setAdapter }) => {
        _config = config;
        setAdapter({
          name: '@exemple/mon-adaptateur',
          entrypointResolution: 'auto',
          serverEntrypoint: '@exemple/mon-adaptateur/serveur.js',
        });
      },
    },
  };
}

Vous pouvez créer des types internes si nécessaire :

declare module 'virtual:@exemple/mon-adaptateur:config' {
  export const assets: string;
}

Vous pouvez ensuite importer le module virtuel :

import { createApp } from 'astro/app/entrypoint';
import { assets } from 'virtual:@exemple/mon-adaptateur:config';

const app = createApp();

export async function handler(event, context) {
  // ...
}

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',
          entrypointResolution: 'auto',
          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',
          entrypointResolution: 'auto',
          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',
          entrypointResolution: 'auto',
          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 { createApp } from 'astro/app/entrypoint';
import { setGetEnv } from "astro/env/setup"

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

const app = createApp();

export async function handler(event, context) {
  // ...
}

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 { createApp } from 'astro/app/entrypoint';
import { setGetEnv } from 'astro/env/setup';

const app = createApp();

export default {
  async fetch(request: Request, env: Record<string, unknown>) {
    setGetEnv((key) => env[key]);

    return await app.render(request);
  }
}

`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.

`middlewareMode`

Type : MiddlewareMode
Par défaut : "classic"

Ajouté à la version : astro@6.0.0

Détermine à quelle étape du cycle de vie de la page le middleware est exécuté, et comment le code du middleware est émis dans le résultat de la compilation.

Le mode classic correspond au comportement par défaut d’Astro. Avec les pages pré-rendues, le middleware est exécuté lors de la compilation, et n’est pas réexécuté lorsque la page est demandée. Avec les pages dynamiques, le middleware est exécuté uniquement lors de la requête. Le code du middleware fait partie de votre paquet compilé pour le serveur.

En mode edge, le code middleware peut être déployé indépendamment du paquet compilé pour le serveur, par exemple, en tant que fonction edge.

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

Ensuite, consommez le hook astro:build:ssr, qui vous donnera un point d’entrée de middleware (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',
          entrypointResolution: 'auto',
          serverEntrypoint: '@exemple/mon-adaptateur/server.js',
          adapterFeatures: {
            middlewareMode: 'edge'
          }
        });
      },

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

function createEdgeMiddleware(middlewareEntryPoint) {
  // Émettez un nouveau fichier physique à l'aide de votre outil de regroupement.
}

`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ébergeur. 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',
          entrypointResolution: 'auto',
          serverEntrypoint: '@exemple/mon-adaptateur/serveur.js',
          adapterFeatures: {
            buildOutput: 'static'
          }
        });
      },
    },
  };
}

`staticHeaders`

Type : boolean
Par défaut : false

Ajouté à la version : astro@6.0.0

Indique si l’adaptateur prend en charge la configuration des en-têtes de réponse pour les pages statiques. Lorsque cette fonctionnalité est activée, Astro renvoie une table de correspondance des en-têtes (Headers) émis par les pages statiques. Cette table de correspondance est disponible sous le nom routeToHeaders dans le hook astro:build:generated et peut être utilisée pour générer une sortie spécifique à la plateforme qui contrôle les en-têtes HTTP, par exemple, pour créer un fichier _headers pour les plateformes qui le prennent en charge.

export default function createIntegration() {
  return {
    name: '@exemple/mon-adaptateur',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@exemple/mon-adaptateur',
          entrypointResolution: 'auto',
          serverEntrypoint: '@exemple/mon-adaptateur/serveur.js',
          adapterFeatures: {
            staticHeaders: true,
          },
        });
      },
      'astro:build:generated': ({ routeToHeaders }) => {
        // utiliser `routeToHeaders` pour générer un fichier de configuration
        // pour l'hébergeur 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 routeToHeaders.

`preserveBuildClientDir`

Type : boolean
Par défaut : false

Ajouté à la version : astro@6.0.0

Lorsque cette option est activée (true), les compilations statiques conservent la structure de répertoires client/server au lieu de générer directement le fichier dans outDir. Cela garantit que les compilations statiques utilisent build.client pour les ressources, assurant ainsi la cohérence avec les compilations pour le serveur.

Ceci est utile pour les adaptateurs qui nécessitent une structure de répertoires spécifique quel que soit le type de sortie de la compilation, comme par exemple le déploiement sur des plateformes ayant des exigences spécifiques en matière d’organisation des fichiers.

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

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 :

`AdapterSupportWithMessage.support`

Type : Exclude<AdapterSupportsKind, “stable”>

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

`AdapterSupportWithMessage.message`

Type : string

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

`AdapterSupportWithMessage.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',
          entrypointResolution: 'auto',
          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',
          entrypointResolution: 'auto',
          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'
            }
          }
        });
      },
    },
  };
}

`MiddlewareMode`

Type : "classic" | "edge"

Ajouté à la version : astro@6.0.0

Une union de formats valides pour décrire le mode d’exécution du middleware.

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

entrypointResolution

serverEntrypoint

supportedAstroFeatures

adapterFeatures

client

client.internalFetchHeaders

client.assetQueryParams

previewEntrypoint

args

exports

Moteur de prérendu personnalisé

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

Transmission de la configuration de compilation

Fonctionnalités d’Astro

staticOutput

hybridOutput

serverOutput

i18nDomains

envGetSecret

sharpImageService

Fonctionnalités de l’adaptateur

middlewareMode

buildOutput

staticHeaders

preserveBuildClientDir

Référence des types des adaptateurs

AdapterSupport

AdapterSupportsKind

AdapterSupportWithMessage

AdapterSupportWithMessage.support

AdapterSupportWithMessage.message

AdapterSupportWithMessage.suppress

MiddlewareMode

Autoriser l’installation via astro add

`name`

`entrypointResolution`

`serverEntrypoint`

`supportedAstroFeatures`

`adapterFeatures`

`client`

`client.internalFetchHeaders`

`client.assetQueryParams`

`previewEntrypoint`

`args`

`exports`

`staticOutput`

`hybridOutput`

`serverOutput`

`i18nDomains`

`envGetSecret`

`sharpImageService`

`middlewareMode`

`buildOutput`

`staticHeaders`

`preserveBuildClientDir`

`AdapterSupport`

`AdapterSupportsKind`

`AdapterSupportWithMessage`

`AdapterSupportWithMessage.support`

`AdapterSupportWithMessage.message`

`AdapterSupportWithMessage.suppress`

`MiddlewareMode`

Autoriser l’installation via `astro add`