API des intégrations d'Astro

Les intégrations d’Astro ajoutent de nouvelles fonctionnalités et de nouveaux comportements à votre projet avec seulement quelques lignes de code.

Cette page de référence est destinée aux personnes qui écrivent leur propre intégration. Pour apprendre à utiliser une intégration dans votre projet, consultez plutôt notre guide sur l’utilisation des intégrations.

Exemples

Les intégrations officielles d’Astro peuvent vous servir de référence pour construire vos propres intégrations.

• Moteurs de rendu : svelte, react, preact, vue, solid
• Bibliothèques : partytown
• Fonctionnalités : sitemap

Référence rapide de l’API

interface AstroIntegration {
  name: string;
  hooks: {
    'astro:config:setup'?: (options: {
      config: AstroConfig;
      command: 'dev' | 'build' | 'preview' | 'sync';
      isRestart: boolean;
      updateConfig: (newConfig: DeepPartial<AstroConfig>) => AstroConfig;
      addRenderer: (renderer: AstroRenderer) => void;
      addWatchFile: (path: URL | string) => void;
      addClientDirective: (directive: ClientDirectiveConfig) => void;
      addMiddleware: (middleware: AstroIntegrationMiddleware) => void;
      addDevToolbarApp: (entrypoint: DevToolbarAppEntry) => void;
      injectScript: (stage: InjectedScriptStage, content: string) => void;
      injectRoute: (injectedRoute: InjectedRoute) => void;
      createCodegenDir: () => URL;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:route:setup'?: (options: {
      route: RouteOptions;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:routes:resolved'?: (options: {
      routes: IntegrationResolvedRoute[];
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:config:done'?: (options: {
      config: AstroConfig;
      setAdapter: (adapter: AstroAdapter) => void;
      injectTypes: (injectedType: InjectedType) => URL;
      logger: AstroIntegrationLogger;
      buildOutput: 'static' | 'server';
    }) => void | Promise<void>;
    'astro:server:setup'?: (options: {
      server: vite.ViteDevServer;
      logger: AstroIntegrationLogger;
      toolbar: ReturnType<typeof getToolbarServerCommunicationHelpers>;
      refreshContent?: (options: RefreshContentOptions) => Promise<void>;
    }) => void | Promise<void>;
    'astro:server:start'?: (options: {
      address: AddressInfo;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:server:done'?: (options: {
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:build:start'?: (options: {
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:build:setup'?: (options: {
      vite: vite.InlineConfig;
      pages: Map<string, PageBuildData>;
      target: 'client' | 'server';
      updateConfig: (newConfig: vite.InlineConfig) => void;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:build:ssr'?: (options: {
      manifest: SerializedSSRManifest;
      entryPoints: Map<IntegrationRouteData, URL>;
      middlewareEntryPoint: URL | undefined;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:build:generated'?: (options: {
      dir: URL;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:build:done'?: (options: {
      pages: { pathname: string }[];
      dir: URL;
      assets: Map<string, URL[]>;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;

    // ... tous les hooks personnalisés provenant des intégrations
  };
}

Hooks

Astro fournit des hooks que les intégrations peuvent implémenter pour s’exécuter pendant certaines parties du cycle de vie d’Astro. Les hooks Astro sont définis dans l’interface IntegrationHooks, qui fait partie de l’espace de noms global Astro. Chaque hook dispose d’une option logger qui vous permet d’utiliser le logger d’Astro pour écrire des journaux.

Les hooks suivants sont intégrés à Astro :

astro:config:setup

Prochain hook : astro:route:setup

Quand : Lors de l’initialisation, avant que les configurations de Vite ou d’Astro ne soient résolues.

Pourquoi : Pour étendre la configuration du projet. Cela comprend la mise à jour de la configuration Astro, l’application des modules d’extension de Vite, l’ajout de moteurs de rendu de composants et l’injection de scripts dans la page.

'astro:config:setup'?: (options: {
  config: AstroConfig;
  command: 'dev' | 'build' | 'preview' | 'sync';
  isRestart: boolean;
  updateConfig: (newConfig: DeepPartial<AstroConfig>) => AstroConfig;
  addRenderer: (renderer: AstroRenderer) => void;
  addClientDirective: (directive: ClientDirectiveConfig) => void;
  addMiddleware: (middleware: AstroIntegrationMiddleware) => void;
  addDevToolbarApp: (entrypoint: DevToolbarAppEntry) => void;
  addWatchFile: (path: URL | string) => void;
  injectScript: (stage: InjectedScriptStage, content: string) => void;
  injectRoute: (injectedRoute: InjectedRoute) => void;
  createCodegenDir: () => URL;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Option config

Type : AstroConfig

Une copie en lecture seule de la configuration Astro fournie par l’utilisateur. Celle-ci est résolue avant que toutes les autres intégrations aient été exécutées. Si vous avez besoin d’une copie de la configuration après que toutes les intégrations ont terminé leurs mises à jour, consultez le hook astro:config:done.

Option command

Type : 'dev' | 'build' | 'preview' | 'sync'

• dev - Le projet est exécuté avec astro dev
• build - Le projet est exécuté avec astro build
• preview - Le projet est exécuté avec astro preview
• sync - Le projet est exécuté avec astro sync

Option isRestart

Type : boolean

Ajouté à la version : astro@1.5.0

false lorsque le serveur de développement démarre, true lorsqu’un rechargement est déclenché. Utile pour détecter si cette fonction est appelée plus d’une fois.

Option updateConfig()

Type : (newConfig: DeepPartial<AstroConfig>) => AstroConfig;

Une fonction de rappel pour mettre à jour la config d’Astro fournie par l’utilisateur. Toute configuration que vous fournissez sera fusionnée avec la configuration de l’utilisateur + les mises à jour effectuées par d’autres intégrations, vous êtes donc libre d’ignorer des noms de propriétés !

Par exemple, disons que vous devez fournir un module d’extension pour Vite au projet de l’utilisateur :

import bananaCSS from '@vitejs/official-banana-css-plugin';

export default {
  name: 'banana-css-integration',
  hooks: {
    'astro:config:setup': ({ updateConfig }) => {
      updateConfig({
        vite: {
          plugins: [bananaCSS()],
        }
      })
    }
  }
}

Option addRenderer()

Type : (renderer: AstroRenderer) => void;
Exemples : svelte, react, preact, vue, solid

Une fonction de rappel pour ajouter un moteur de rendu de composants de framework (c’est-à-dire React, Vue, Svelte, etc.). Vous pouvez consulter les exemples et la définition des types ci-dessus pour des options plus avancées, mais voici les deux principales options à connaître :

• clientEntrypoint - chemin d’accès à un fichier qui s’exécute sur le client chaque fois que votre composant est utilisé. Ce fichier sert principalement à afficher ou à hydrater votre composant avec JS.
• serverEntrypoint - chemin d’accès à un fichier qui s’exécute lors des requêtes côté serveur ou des compilations statiques, chaque fois que votre composant est utilisé. Ces fichiers devraient restituer les composants en un balisage statique, avec des hooks d’hydratation, le cas échéant. Le callback renderToString de React est un exemple classique.

Ajouté à la version : astro@5.0.0

Les fonctions clientEntrypoint et serverEntrypoint acceptent une URL.

Option addWatchFile()

Type : (path: URL | string) => void

Ajouté à la version : astro@1.5.0

Si votre intégration dépend d’un fichier de configuration que Vite ne surveille pas et/ou qui nécessite un redémarrage complet du serveur de développement pour prendre effet, ajoutez-le avec addWatchFile(). Chaque fois que ce fichier changera, le serveur de développement d’Astro sera rechargé (vous pouvez vérifier quand un rechargement a lieu avec isRestart).

Exemple d’utilisation :

// Il doit s'agir d'un chemin d'accès absolu !
addWatchFile('/home/utilisateur/.../ma-config.json');
addWatchFile(new URL('./ec.config.mjs', config.root));

Option addClientDirective()

Type : (directive: ClientDirectiveConfig) => void;

Ajouté à la version : astro@2.6.0

Ajoute une directive client personnalisée à utiliser dans les fichiers .astro.

Notez que les points d’entrée des directives ne sont regroupés qu’à travers esbuild et qu’ils doivent rester petits afin de ne pas ralentir l’hydratation des composants.

Exemple d’utilisation :

astro.config.mjs

import { defineConfig } from 'astro/config';
import clickDirective from './astro-click-directive/register.js'

// https://astro.build/config
export default defineConfig({
  integrations: [
    clickDirective()
  ],
});

astro-click-directive/register.js

/**
 * @type {() => import('astro').AstroIntegration}
 */
export default () => ({
  name: "client:click",
  hooks: {
    "astro:config:setup": ({ addClientDirective }) => {
      addClientDirective({
        name: "click",
        entrypoint: "./astro-click-directive/click.js",
      });
    },
  },
});

astro-click-directive/click.js

/**
 * Hydrate au premier clic sur la fenêtre
 * @type {import('astro').ClientDirective}
 */
export default (load, opts, el) => {
  window.addEventListener('click', async () => {
    const hydrate = await load()
    await hydrate()
  }, { once: true })
}

Vous pouvez également ajouter des types pour les directives dans le fichier de définition des types de votre bibliothèque :

astro-click-directive/index.d.ts

import 'astro'
declare module 'astro' {
  interface AstroClientDirectives {
    'client:click'?: boolean
  }
}

Option addDevToolbarApp()

Type : (entrypoint: DevToolbarAppEntry) => void;

Ajouté à la version : astro@3.4.0

Ajoute une application de barre d’outils de développement personnalisée.

Exemple d’utilisation :

astro.config.mjs

import { defineConfig } from 'astro/config';
import devToolbarIntegration from './astro-dev-toolbar-app/integration.js'

// https://astro.build/config
export default defineConfig({
  integrations: [
    devToolbarIntegration()
  ],
});

astro-dev-toolbar-app/integration.js

/**
 * @type {() => import('astro').AstroIntegration}
 */
export default () => ({
  name: "dev-toolbar-app",
  hooks: {
    "astro:config:setup": ({ addDevToolbarApp }) => {
      addDevToolbarApp({
        entrypoint: "./astro-dev-toolbar-app/plugin.js",
        id: "mon-module-extension",
        name: "Mon module d'extension"
      });
    },
  },
});

astro-dev-toolbar-app/plugin.js

/**
 * @type {import('astro').DevToolbarApp}
 */
export default {
  id: "mon-module-extension",
  name: "Mon module d'extension",
  icon: "<svg>...</svg>",
  init() {
    console.log("Je suis une application de barre d'outils de développement !")
  },
};

Option addMiddleware()

Type : (middleware: AstroIntegrationMiddleware) => void;

Ajouté à la version : astro@3.5.0

Ajoute un middleware à exécuter pour chaque requête. Prend le point d’entrée du module (entrypoint) qui contient le middleware, et un ordre (order) pour spécifier s’il doit s’exécuter avant (pre) les autres middlewares ou après (post).

@mon-paquet/integration.js

/**
 * @type {() => import('astro').AstroIntegration}
 */
export default () => ({
  name: "mon-paquet-middleware",
  hooks: {
    "astro:config:setup": ({ addMiddleware }) => {
        addMiddleware({
          entrypoint: '@mon-paquet/middleware',
          order: 'pre'
        });
    },
  },
});

Le middleware est défini dans un paquet avec une fonction onRequest(), comme pour le middleware défini par l’utilisateur.

@mon-paquet/middleware.js

import { defineMiddleware } from 'astro:middleware';

export const onRequest = defineMiddleware(async (context, next) => {
  if(context.url.pathname === '/chemin-de-test') {
    return Response.json({
      ok: true
    });
  }

  return next();
});

Ajouté à la version : astro@5.0.0

La fonction accepte également une URL pour entrypoint :

@mon-paquet/integration.js

/**
 * @type {() => import('astro').AstroIntegration}
 */
export default () => ({
  name: "mon-paquet-middleware",
  hooks: {
    "astro:config:setup": ({ addMiddleware }) => {
        addMiddleware({
          entrypoint: new URL('./middleware.js', import.meta.url),
          order: 'pre'
        });
    },
  },
});

Option injectRoute()

Type : ({ pattern: string; entrypoint: string | URL; prerender?: boolean }) => void;

Une fonction de rappel pour injecter des routes dans un projet Astro. Les routes injectées peuvent être des pages .astro ou des gestionnaires de routes .js et .ts.

injectRoute() prend un objet avec un modèle (pattern) et un point d’entrée (entrypoint).

• pattern - où la route doit être affichée dans le navigateur, par exemple /foo/bar. Un modèle (pattern) peut utiliser la syntaxe de chemin de fichier d’Astro pour indiquer des routes dynamiques, par exemple /foo/[bar] ou /foo/[...bar]. Notez qu’une extension de fichier n’est pas nécessaire dans pattern.
• entrypoint - un spécificateur de module nu pointant vers la page .astro ou le gestionnaire de route .js/.ts qui gère la route indiquée dans pattern.
• prerender - un booléen à définir si Astro ne peut pas détecter votre exportation de prerender.

Exemple d’utilisation

injectRoute({
  // Utilise la syntaxe Astro pour les routes dynamiques.
  pattern: '/sous-dossier/[dynamic]',
  // Utilise la syntaxe du chemin relatif pour une route locale.
  entrypoint: './src/page-dynamique.astro'
  // À utiliser uniquement si Astro ne peut pas détecter votre exportation de `prerender`
  prerender: false
});

Pour une intégration conçue pour être installée dans d’autres projets, utilisez le nom de son paquet pour faire référence au point d’entrée de la route. L’exemple suivant montre un paquet publié sur npm sous le nom @fancy/dashboard injectant une route de tableau de bord :

injectRoute({
  pattern: '/fancy-dashboard',
  entrypoint: '@fancy/dashboard/dashboard.astro'
});

Lorsque vous publiez votre paquet (@fancy/dashboard, dans ce cas) sur npm, vous devez exporter dashboard.astro dans votre package.json :

package.json

{
  "name": "@fancy/dashboard",
  // ...
  "exports": { "./dashboard.astro": "./dashboard.astro" }
}

Ajouté à la version : astro@5.0.0

La fonction accepte également une URL pour entrypoint :

injectRoute({
  pattern: '/fancy-dashboard',
  entrypoint: new URL('./dashboard.astro', import.meta.url)
});

Option injectScript()

Type : (stage: InjectedScriptStage, content: string) => void;

Une fonction de rappel pour injecter une chaîne de contenu JavaScript sur chaque page.

La phase (stage) indique comment ce script (content) doit être inséré. Certaines phases permettent d’insérer des scripts sans modification, tandis que d’autres permettent une optimisation pendant l’étape de regroupement de Vite :

• "head-inline" : Injecté dans une balise script dans le <head> de chaque page. Non optimisé ou interprété par Vite.

• "before-hydration" : Importé côté client, avant l’exécution du script d’hydratation. Optimisé et interprété par Vite.

• "page" : Similaire à head-inline, sauf que l’extrait injecté est traité par Vite et regroupé avec toutes les autres balises <script> définies à l’intérieur des composants Astro sur la page. Le script sera chargé avec un <script type="module"> dans la sortie finale de la page, optimisé et interprété par Vite.

• "page-ssr" : Importé en tant que module séparé dans le frontmatter de chaque composant de page Astro. Parce que cette phase importe votre script, l’objet global Astro n’est pas disponible et votre script ne sera exécuté qu’une seule fois lorsque l’instruction import est évaluée pour la première fois.

  La principale utilisation de la phase page-ssr est l’injection d’une importation CSS (import) dans chaque page à optimiser et à résoudre par Vite :

  injectScript('page-ssr', 'import "global-styles.css";');

createCodegenDir()

Type : () => URL;

Ajouté à la version : astro@5.0.0

Une fonction qui crée le dossier <root>/.astro/integrations/<normalized_integration_name> et renvoie son chemin.

Cela vous permet d’avoir un dossier dédié, évitant ainsi les conflits avec une autre intégration ou Astro lui-même. Ce répertoire est créé en appelant cette fonction, il est donc sûr d’y écrire directement des fichiers :

mon-integration.ts

import { writeFileSync } from 'node:fs'

const integration = {
    name: 'mon-integration',
    hooks: {
        'astro:config:setup': ({ createCodegenDir }) => {
            const codegenDir = createCodegenDir()
            writeFileSync(new URL('cache.json', codegenDir), '{}', 'utf-8')
        }
    }
}

astro:route:setup

Ajouté à la version : astro@4.14.0

Hook précédent : astro:config:setup

Hook suivant : astro:routes:resolved

Quand : Avec astro build, avant le début du regroupement. Avec astro dev, lors de la construction du graphe des modules et à chaque modification d’une route basée sur un fichier (ajoutée/supprimée/mise à jour).

Pourquoi : Pour définir les options d’une route au moment de la compilation ou de la demande, comme l’activation du rendu du serveur à la demande.

'astro:route:setup'?: (options: {
  route: RouteOptions;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Option route

Type : { readonly component: string; prerender?: boolean; }

Un objet avec une propriété component pour identifier la route et les valeurs supplémentaires suivantes pour vous permettre de configurer la route générée : prerender.

route.component

Type : string

Ajouté à la version : astro@4.14.0

La propriété component indique le point d’entrée qui sera rendu sur la route. Vous pouvez accéder à cette valeur avant la création des routes afin de configurer le rendu du serveur à la demande pour cette page.

route.prerender

Type : boolean
Par défaut : undefined

Ajouté à la version : astro@4.14.0

La propriété prerender est utilisée pour configurer le rendu du serveur à la demande pour une route. Si le fichier de route contient une valeur explicite export const prerender, la valeur sera utilisée comme valeur par défaut au lieu de undefined.

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  integrations: [setPrerender()],
});

function setPrerender() {
  return {
    name: 'set-prerender',
    hooks: {
      'astro:route:setup': ({ route }) => {
        if (route.component.endsWith('/blog/[slug].astro')) {
          route.prerender = true;
        }
      },
    },
  };
}

Si la valeur finale après l’exécution de tous les hooks est undefined, la route reviendra à une valeur par défaut de pré-rendu basée sur l’option output : pré-rendu pour le mode static et rendu à la demande pour le mode server.

astro:routes:resolved

Ajouté à la version : astro@5.0.0

Hook précédent : astro:config:setup

Hook suivant : astro:config:done

Quand : Dans astro dev, il s’exécute également si une route basée sur un fichier change (ajoutée/supprimée/mise à jour).

Pourquoi : Pour accéder aux routes et à leurs métadonnées

'astro:routes:resolved'?: (options: {
  routes: IntegrationResolvedRoute[];
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Option routes

Type : IntegrationResolvedRoute[]

Une liste de toutes les routes avec leurs métadonnées associées.

Exemple d’utilisation :

mon-integration.mjs

const integration = () => {
    return {
        name: 'mon-integration',
        hooks: {
            'astro:routes:resolved': ({ routes }) => {
                const projectRoutes = routes.filter(r => r.origin === 'projet').map(r => r.pattern)

                console.log(projectRoutes)
            },
        }
    }
}

astro:config:done

Hook précédent : astro:config:setup

Hook suivant : astro:server:setup en mode « dev », ou astro:build:start en mode « production ».

Quand : Après que la configuration Astro a été résolue et que les autres intégrations aient exécuté leurs hooks astro:config:setup.

Pourquoi : Pour récupérer la configuration finale afin de l’utiliser dans d’autres hooks.

'astro:config:done'?: (options: {
  config: AstroConfig;
  setAdapter: (adapter: AstroAdapter) => void;
  injectTypes: (injectedType: InjectedType) => URL;
  logger: AstroIntegrationLogger;
  buildOutput: 'static' | 'server';
}) => void | Promise<void>;

Option config

Type : AstroConfig

Une copie en lecture seule de la configuration Astro fournie par l’utilisateur. Celle-ci est résolue après l’exécution des autres intégrations.

Option setAdapter()

Type : (adapter: AstroAdapter) => void;

Transforme l’intégration en adaptateur. Pour en savoir plus, consultez l’API des adaptateurs.

Option injectTypes()

Type : (injectedType: { filename: string; content: string }) => URL

Ajouté à la version : astro@4.14.0

Permet d’injecter des types dans le projet de votre utilisateur en ajoutant un nouveau fichier *.d.ts.

La propriété filename sera utilisée pour générer un fichier dans /.astro/integrations/<normalized_integration_name>/<normalized_filename>.d.ts et doit se terminer par ".d.ts".

La propriété content créera le corps du fichier et doit utiliser une syntaxe TypeScript valide.

De plus, injectTypes() renvoie une URL vers le chemin normalisé afin que vous puissiez écraser son contenu ultérieurement ou le manipuler comme vous le souhaitez.

const path = injectTypes({
  filename: "types.d.ts",
  content: "declare module 'virtual:integration' {}"
})
console.log(path) // URL

Option buildOutput

Type : 'static' | 'server'

Ajouté à la version : astro@5.0.0

Permet d’adapter la logique de votre intégration en fonction du rendu du projet de l’utilisateur.

astro:server:setup

Hook précédent : astro:config:done

Hook suivant : astro:server:start

Quand : Juste après la création du serveur Vite en mode « dev », mais avant que l’événement listen() ne soit déclenché. Voir l’API createServer de Vite pour plus d’informations.

Pourquoi : Pour mettre à jour les options du serveur Vite et le middleware, ou activer la prise en charge de l’actualisation de la couche de contenu.

'astro:server:setup'?: (options: {
  server: vite.ViteDevServer;
  logger: AstroIntegrationLogger;
  toolbar: ReturnType<typeof getToolbarServerCommunicationHelpers>;
  refreshContent: (options: {
    loaders?: Array<string>;
    context?: Record<string, any>;
  }) => Promise<void>;
}) => void | Promise<void>;

Option server

Type : ViteDevServer

Une instance mutable du serveur Vite utilisée en mode « dev ». Par exemple, c’est utilisé par notre intégration Partytown pour injecter le serveur Partytown en tant que middleware :

export default {
  name: 'partytown',
  hooks: {
    'astro:server:setup': ({ server }) => {
      server.middlewares.use(
        function middleware(req, res, next) {
          // traite les demandes
        }
      );
    }
  }
}

Option toolbar

Type : ReturnType<typeof getToolbarServerCommunicationHelpers>

Ajouté à la version : astro@4.7.0

Un objet fournissant des fonctions de rappel pour interagir avec la barre d’outils de développement:

toolbar.on()

Type : <T>(event: string, callback: (data: T) => void) => void

Une fonction qui prend un nom d’événement comme premier argument et une fonction de rappel comme second argument. Cela vous permet de recevoir un message d’une application de barre d’outils de développement avec des données associées à cet événement.

toolbar.onAppInitialized()

Type : (appId: string, callback: (data: Record<string, never>) => void) => void

Une fonction déclenchée lorsqu’une application de barre d’outils de développement est initialisée. Le premier argument est l’ID de l’application qui a été initialisée. Le deuxième argument est une fonction de rappel à exécuter lorsque l’application est initialisée.

toolbar.onAppToggled()

Type : (appId: string, callback: (data: { state: boolean; }) => void) => void

Une fonction déclenchée lorsqu’une application de barre d’outils de développement est activée ou désactivée. Le premier argument est l’ID de l’application qui a été activée ou désactivée. Le deuxième argument est une fonction de rappel fournissant l’état à exécuter lorsque l’application est activée ou désactivée.

toolbar.send()

Type : <T>(event: string, payload: T) => void

Une fonction qui envoie un message à la barre d’outils de développement qu’une application peut écouter. Cela prend un nom d’événement comme premier argument et une charge utile comme deuxième argument qui peut être n’importe quelle donnée sérialisable.

Option refreshContent()

Type : (options: { loaders?: Array<string>; context?: Record<string, any>; }) => Promise<void>

Ajouté à la version : astro@5.0.0

Une fonction permettant aux intégrations de déclencher une mise à jour de la couche de contenu pendant astro dev. Cela peut être utilisé, par exemple, pour enregistrer un point de terminaison webhook pendant le développement, ou pour ouvrir un socket vers un CMS pour écouter les modifications.

Par défaut, refreshContent() actualise toutes les collections. Vous pouvez éventuellement transmettre une propriété loaders, qui est un tableau de noms de chargeurs. Si elle est fournie, seules les collections qui utilisent ces chargeurs seront actualisées. Par exemple, une intégration CMS pourrait utiliser cette propriété pour actualiser uniquement ses propres collections.

Vous pouvez également transmettre un objet context aux chargeurs. Il peut être utilisé pour transmettre des données arbitraires telles que le corps du webhook ou un événement du websocket.

mon-integration.ts

{
  name: 'mon-integration',
  hooks: {
    'astro:server:setup': async ({ server, refreshContent }) => {
      // Enregistrer un point de terminaison webhook de serveur de développement
      server.middlewares.use('/_refresh', async (req, res) => {
        if(req.method !== 'POST') {
          res.statusCode = 405
          res.end('Méthode non autorisée');
          return
        }
        let body = '';
        req.on('data', chunk => {
          body += chunk.toString();
        });
        req.on('end', async () => {
          try {
            const webhookBody = JSON.parse(body);
            await refreshContent({
              context: { webhookBody },
              loaders: ['mon-chargeur']
            });
            res.writeHead(200, { 'Content-Type': 'application/json' });
            res.end(JSON.stringify({ message: 'Contenu actualisé avec succès' }));
          } catch (error) {
            res.writeHead(500, { 'Content-Type': 'application/json' });
            res.end(JSON.stringify({ error: "Échec de l'actualisation du contenu : " + error.message }));
          }
        });
      });
    }
  }
}

Le chargeur peut ensuite accéder à la propriété refreshContextData pour obtenir le corps du webhook. Consultez la propriété refreshContextData pour plus d’informations.

astro:server:start

Hook précédent : astro:server:setup

Hook suivant : astro:server:done

Quand : Juste après que l’événement listen() du serveur se soit déclenché.

Pourquoi : Intercepter les requêtes réseau à l’adresse spécifiée. Si vous avez l’intention d’utiliser cette adresse pour un middleware, pensez à utiliser astro:server:setup à la place.

'astro:server:start'?: (options: {
  address: AddressInfo;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Option address

Type : AddressInfo

L’adresse, la famille et le numéro de port fournis par la méthode server.address() du module Net de Node.js.

astro:server:done

Hook précédent : astro:server:start

Quand : Juste après la fermeture du serveur de développement.

Pourquoi : Pour exécuter les événements de nettoyage que vous pouvez déclencher pendant les hooks astro:server:setup ou astro:server:start.

'astro:server:done'?: (options: {
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

astro:build:start

Hook précédent : astro:config:done

Hook suivant : astro:build:setup

Quand : Après l’événement astro:config:done, mais avant le début de la compilation pour la production.

Pourquoi : Pour configurer les objets globaux ou les clients nécessaires lors d’une compilation pour la production. Cela peut également étendre les options de configuration de la compilation dans l’API des adaptateurs.

'astro:build:start'?: (options: {
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

astro:build:setup

Hook précédent : astro:build:start

Hook suivant : astro:build:ssr

Quand : Après le hook astro:build:start, s’exécute immédiatement avant la compilation.

Pourquoi : A ce stade, la configuration de Vite pour la compilation a été complètement assemblée, c’est votre dernière chance de la modifier. Cela peut être utile, par exemple, pour écraser certains paramètres par défaut. Si vous n’êtes pas sûr de devoir utiliser ce hook ou astro:build:start, utilisez plutôt astro:build:start.

'astro:build:setup'?: (options: {
  vite: vite.InlineConfig;
  pages: Map<string, PageBuildData>;
  target: 'client' | 'server';
  updateConfig: (newConfig: vite.InlineConfig) => void;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Option vite

Type : InlineConfig

Un objet qui vous permet d’accéder à la configuration de Vite utilisée pour la compilation.

Cela peut être utile si vous avez besoin d’accéder aux options de configuration dans votre intégration :

export default {
  name: 'mon-integration',
  hooks: {
    'astro:build:setup': ({ vite }) => {
      const { publicDir, root } = vite;
    },
  }
}

Option pages

Type : Map<string, PageBuildData>

Un objet Map avec une liste de pages comme nom de propriété et leurs données de compilation comme valeur.

Cela peut être utilisé pour effectuer une action si une route correspond à un critère :

export default {
  name: 'mon-integration',
  hooks: {
    'astro:build:setup': ({ pages }) => {
      pages.forEach((data) => {
        if (data.route.pattern.test("/blog")) {
          console.log(data.route.type);
        }
      });
    },
  }
}

L’objet PageBuildData

Décrit comment compiler une page.

PageBuildData.key

Type : string

Ajouté à la version : astro@4.8.0

Spécifie un identifiant unique pour la page.

PageBuildData.component

Type : string

Spécifie l’URL du composant source.

PageBuildData.route

Type : RouteData

Décrit les informations relatives à la route de la page.

PageBuildData.moduleSpecifier

Type : string

Définit une chaîne de caractères pouvant être résolue en un chemin d’accès au fichier pour le module.

PageBuildData.styles

Type : Array<{ depth: number; order: number; sheet: { type: 'inline'; content: string } | { type: 'external'; src: string } }>

Ajouté à la version : astro@2.4.0

Une liste des styles à afficher dans la page. Chaque style indique sa profondeur dans l’arborescence des composants (depth) et son ordre d’affichage sur la page (order), ainsi que s’il doit être appliqué en tant que style incorporé à la page ou style externe.

Option target

Type : 'client' | 'server'

La compilation est divisée en deux phases distinctes : client et server. Cette option vous permet de déterminer la phase de compilation en cours.

Cela peut être utilisé pour effectuer une action uniquement dans une phase spécifique :

export default {
  name: 'mon-integration',
  hooks: {
    'astro:build:setup': ({ target }) => {
      if (target === "server") {
        // faire quelque chose dans la phase de compilation du serveur
      }
    },
  }
}

Option updateConfig()

Type : (newConfig: InlineConfig) => void

Une fonction de rappel pour mettre à jour les options de Vite utilisées dans la compilation. Toute configuration que vous fournissez sera fusionnée avec la configuration utilisateur + d’autres mises à jour de configuration d’intégration, vous êtes donc libre d’omettre des clés !

Par exemple, cela peut être utilisé pour fournir un module d’extension au projet de l’utilisateur :

import awesomeCssPlugin from 'module-extension-css-genial-vite';

export default {
  name: 'mon-integration',
  hooks: {
    'astro:build:setup': ({ updateConfig }) => {
      updateConfig({
        plugins: [awesomeCssPlugin()],
      })
    }
  }
}

astro:build:ssr

Hook précédent : astro:build:setup

Hook suivant : astro:build:generated

Quand : Une fois la compilation SSR pour la production terminée.

Pourquoi : Pour accéder au manifeste SSR et à la carte des points d’entrée émis. Ceci est utile lors de la création de compilations SSR personnalisées dans des modules d’extension ou des intégrations.

• entryPoints fait correspondre une route de page au fichier physique émis après la compilation,
• middlewareEntryPoint est le chemin d’accès au système de fichiers du middleware.

'astro:build:ssr'?: (options: {
  manifest: SerializedSSRManifest;
  entryPoints: Map<IntegrationRouteData, URL>;
  middlewareEntryPoint: URL | undefined;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Option manifest

Type : SerializedSSRManifest

Permet de créer une compilation personnalisée en accédant à une version sérialisée du SSRManifest. Celle-ci contient les mêmes informations que SSRManifest, certaines propriétés ayant été converties en formats sérialisables.

L’exemple suivant vérifie la configuration i18n.strategy enregistrée dans le manifest :

export default {
  name: 'mon-integration',
  hooks: {
    'astro:build:ssr': ({ manifest }) => {
      const { i18n } = manifest;
      if (i18n?.strategy === "domains-prefix-always") {
        // faire quelque chose
      }
    },
  },
}

manifest.routes

Type : SerializedRouteInfo[]

Définit une liste d’informations de routage sérialisées. Chaque route contient les mêmes propriétés que SSRManifest.routes, avec routeData converti au format sérialisable JSON.

manifest.assets

Type : string[]

Définit une liste de chemins d’accès aux fichiers de ressources sérialisés.

manifest.componentMetadata

Type : [string, SSRComponentMetadata][]

Ajouté à la version : astro@2.1.7

Définit un tableau de paires clé-valeur où le premier élément est l’identifiant du composant et le second est un objet décrivant les métadonnées de compilation.

manifest.inlinedScripts

Type : [string, string][]

Définit un tableau de paires clé-valeur où chaque entrée est un tuple. Le premier élément est l’identifiant du script et le second est le contenu du script.

manifest.clientDirectives

Type : [string, string][]

Ajouté à la version : astro@2.5.0

Définit un tableau de paires clé-valeur où le premier élément est le nom de la directive (par exemple load, visible) et le second est le code d’implémentation de la directive.

manifest.serverIslandNameMap

Type : [string, string][]

Ajouté à la version : astro@4.12.0

Définit un tableau de paires clé-valeur où chaque entrée est un tuple. Le premier élément est le chemin du composant et le second est le nom attribué.

manifest.key

Type : string

Ajouté à la version : astro@4.13.4

Spécifie la clé cryptographique, sérialisée sous forme de chaîne de caractères, utilisée pour chiffrer les propriétés de l’îlôt de serveur.

Option entryPoints

Type : Map<IntegrationRouteData, URL>

Ajouté à la version : astro@2.7.0

Un objet Map des points d’entrée émis avec IntegrationRouteData comme nom de propriété et l’URL du fichier physique comme valeur.

export default {
  name: 'mon-integration',
  hooks: {
    'astro:build:ssr': ({ entryPoints }) => {
      entryPoints.forEach((url) => {
        console.log(url.href);
      });
    },
  },
}

Option middlewareEntryPoint

Type : URL | undefined

Ajouté à la version : astro@2.8.0

Expose le chemin du fichier middleware.

export default {
  name: 'mon-integration',
  hooks: {
    'astro:build:ssr': ({ middlewareEntryPoint }) => {
      if (middlewareEntryPoint) {
        // effectuer certaines opérations si un middleware existe
      }
    },
  },
}

astro:build:generated

Ajouté à la version : astro@1.3.0

Hook précédent : astro:build:setup

Hook suivant : astro:build:done

Quand : Une fois qu’une version statique de production a fini de générer les routes et les ressources.

Pourquoi : Accéder aux routes et aux ressources générées avant que les artefacts de compilation ne soient nettoyés. C’est un cas d’utilisation très rare. Nous recommandons d’utiliser astro:build:done à moins que vous n’ayez vraiment besoin d’accéder aux fichiers générés avant le nettoyage.

'astro:build:generated'?: (options: {
  dir: URL;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Option dir

Type : URL

Un chemin URL vers le répertoire de sortie de la compilation.

L’exemple suivant utilise l’utilitaire fileURLToPath() intégré à Node pour calculer une chaîne de chemin absolu valide pour un fichier fourni par l’intégration :

import { fileURLToPath } from 'node:url';

export default {
  name: 'mon-integration',
  hooks: {
    'astro:build:generated': ({ dir }) => {
      const outFile = fileURLToPath(new URL('./mon-integration.json', dir));
    }
  }
}

astro:build:done

Hook précédent :astro:build:generated

Quand : Après l’achèvement d’une compilation pour la production (SSG ou SSR).

Pourquoi : Pour accéder aux routes et aux ressources générées pour l’extension (p. ex. copier le contenu dans le répertoire /assets généré). Si vous envisagez de transformer les ressources générées, nous vous recommandons d’explorer l’API des modules d’extension de Vite et de configurer via astro:config:setup à la place.

'astro:build:done'?: (options: {
  pages: { pathname: string }[];
  dir: URL;
  /** @deprecated Utilisez la Map `assets` et le nouveau hook `astro:routes:resolved`*/
  routes: IntegrationRouteData[];
  assets: Map<string, URL[]>;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Option dir

Type : URL

Un chemin URL vers le répertoire de sortie de la compilation.

L’exemple suivant utilise l’utilitaire fileURLToPath() intégré à Node pour calculer une chaîne de chemin absolu valide pour un fichier fourni par l’intégration avant d’écrire à l’intérieur :

import { writeFile } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';

export default function myIntegration() {
  return {
    hooks: {
      'astro:build:done': async ({ dir }) => {
        const metadata = await getIntegrationMetadata();
        // Utilisez fileURLToPath pour obtenir une chaîne de chemin absolu valide et multiplateforme.
        const outFile = fileURLToPath(new URL('./mon-integration.json', dir));
        await writeFile(outFile, JSON.stringify(metadata));
      }
    }
  }
}

Option routes

Attention

Cette propriété est dépréciée depuis la version 5.0. Consultez le guide de migration.

Type : IntegrationRouteData[]

Une liste de toutes les routes générées avec leurs métadonnées associées.

Vous pouvez référencer le type IntegrationRouteData complet ci-dessous, mais les propriétés les plus courantes sont les suivantes :

• component - le chemin du fichier d’entrée par rapport à la racine du projet
• pathname - l’URL du fichier de sortie (non définie pour les routes utilisant les paramètres [dynamic] et [...spread])

Option assets

Type : Map<string, URL[]>

Ajouté à la version : astro@5.0.0

Contient les URL vers les chemins des fichiers de sortie, regroupés par la propriété pattern de IntegrationResolvedRoute.

Option pages

Type : { pathname: string }[]

Une liste de toutes les pages générées. Chaque entrée est un objet possédant une seule propriété :

• pathname - le chemin finalisé de la page.

Hooks personnalisés

Des hooks personnalisés peuvent être ajoutés aux intégrations en étendant l’interface IntegrationHooks via augmentation globale.

declare global {
  namespace Astro {
    export interface IntegrationHook {
      'votre:hook': (params: YourHookParameters) => Promise<void>
    }
  }
}

Astro réserve le préfixe astro: pour les futurs hooks intégrés. Veuillez choisir un préfixe différent lorsque vous nommez votre hook personnalisé.

Référence des types des intégrations

Les types suivants peuvent être importés depuis le module astro :

import type {
  AstroIntegrationLogger,
  AstroIntegrationMiddleware,
  AstroMiddlewareInstance,
  AstroRenderer,
  ClientDirectiveConfig,
  HookParameters,
  IntegrationResolvedRoute,
  RedirectConfig,
  RouteData,
  RoutePart,
  RouteType,
  SSRComponentMetadata,
  SSRLoadedRenderer,
  SSRLoadedRendererValue,
  SSRManifest,
  ValidRedirectStatus,
  // Les éléments suivants sont dépréciés :
  IntegrationRouteData,
} from "astro";

AstroIntegrationLogger

Une instance du logger d’Astro, utile pour écrire des journaux. Ce logger utilise le même niveau de journalisation configuré via la CLI.

Méthodes disponibles pour écrire dans le terminal :

• logger.info("Message");
• logger.warn("Message");
• logger.error("Message");
• logger.debug("Message");

Tous les messages sont précédés d’une étiquette qui a la même valeur que le nom de l’intégration.

integration.ts

import type { AstroIntegration } from "astro";
export function formatIntegration(): AstroIntegration {
  return {
    name: "astro-format",
    hooks: {
      "astro:build:done": ({ logger }) => {
        // faire quelque chose
        logger.info("Intégration prête.");
      }
    }
  }
}

L’exemple ci-dessus écrira un message qui inclut le message d’info fourni :

[astro-format] Intégration prête.

Pour écrire certains messages avec une étiquette différente, utilisez la méthode .fork pour spécifier une alternative au nom (name) par défaut :

integration.ts

import type { AstroIntegration } from "astro";
export function formatIntegration(): AstroIntegration {
  return {
    name: "astro-format",
    hooks: {
      "astro:config:done": ({ logger }) => {
        // faire quelque chose
        logger.info("Intégration prête.");
      },
      "astro:build:done": ({ logger }) => {
        const buildLogger = logger.fork("astro-format/build");
        // faire quelque chose
        buildLogger.info("Compilation terminée.")
      }
    }
  }
}

L’exemple ci-dessus produira des journaux avec [astro-format] par défaut, et [astro-format/build] lorsqu’il est spécifié :

[astro-format] Intégration prête.
[astro-format/build] Compilation terminée.

AstroIntegrationMiddleware

Type : { order: "pre" | "post"; entrypoint: string | URL; }

Décrit un middleware ajouté par une intégration.

AstroIntegrationMiddleware.order

Type : "pre" | "post"

Spécifie si le middleware doit s’exécuter avant (pre) ou après (post) les autres middlewares.

AstroIntegrationMiddleware.entrypoint

Type : string | URL

Définit le chemin d’importation du middleware.

AstroMiddlewareInstance

Type : { onRequest?: MiddlewareHandler; }

Un objet contenant une propriété onRequest() définie avec la fonction middleware du projet lorsqu’elle existe.

AstroRenderer

Type : { name: string; clientEntrypoint?: string | URL; serverEntrypoint: string | URL; }

Décrit un moteur de rendu de composants de framework ajouté par une intégration.

AstroRenderer.name

Type : string

Le nom du moteur de rendu de composants de framework.

AstroRenderer.clientEntrypoint

Type : string | URL

Définit le chemin d’importation du moteur de rendu qui s’exécute côté client chaque fois que votre composant est utilisé.

AstroRenderer.serverEntrypoint

Type : string | URL

Définit le chemin d’importation du moteur de rendu qui s’exécute lors des requêtes côté serveur ou des compilations statiques chaque fois que votre composant est utilisé.

ClientDirectiveConfig

Type : { name: string; entrypoint: string | URL; }

Décrit une directive client personnalisée ajoutée par une intégration.

ClientDirectiveConfig.name

Type : string

Un nom personnalisé pour l’événement déclenché par la directive.

ClientDirectiveConfig.entrypoint

Type : string | URL

Définit le chemin d’importation du code exécuté chaque fois que la directive est utilisée.

HookParameters

Vous pouvez obtenir le type des arguments d’un hook en transmettant le nom du hook à l’utilitaire de typage HookParameters.

Dans l’exemple suivant, l’argument options d’une fonction est typé pour correspondre aux paramètres du hook astro:config:setup :

import type { HookParameters } from 'astro';

function mySetup(options: HookParameters<'astro:config:setup'>) {
  options.updateConfig({ /* ... */ });
}

IntegrationResolvedRoute

Un sous-ensemble de RouteData avec des propriétés réattribuées.

interface IntegrationResolvedRoute extends Pick<
    RouteData,
    'generate' | 'params' | 'pathname' | 'segments' | 'type' | 'redirect' | 'origin'
  > & {
  pattern: RouteData['route'];
  patternRegex: RouteData['pattern'];
  entrypoint: RouteData['component'];
  isPrerendered: RouteData['prerender'];
  redirectRoute?: IntegrationResolvedRoute;
}

IntegrationResolvedRoute.pattern

Type : RouteData['route']

Permet d’identifier le type de route en fonction de son chemin. Voici quelques exemples de chemins associés à leur motif :

• src/pages/index.astro sera /
• src/pages/blog/[...slug].astro sera /blog/[...slug]
• src/pages/site/[blog]/[...slug].astro sera /site/[blog]/[...slug]

IntegrationResolvedRoute.patternRegex

Type : RouteData['pattern']

Vous permet d’accéder à une expression régulière utilisée pour faire correspondre une URL d’entrée à une route demandée.

Par exemple, étant donné un chemin [fruit]/about.astro, l’expression régulière sera /^\/([^/]+?)\/about\/?$/. L’utilisation de pattern.test("banana/about") renverra true.

IntegrationResolvedRoute.entrypoint

Type : RouteData['component']

L’URL d’accès du composant source.

IntegrationResolvedRoute.isPrerendered

Type : RouteData['prerender']

Détermine si la route utilise le rendu à la demande. La valeur sera true pour les projets configurés avec :

• output: 'static' quand la route n’exporte pas const prerender = true
• output: 'server' quand la route exporte const prerender = false

IntegrationResolvedRoute.redirectRoute

Type : IntegrationResolvedRoute | undefined

Lorsque la valeur de IntegrationResolvedRoute.type est redirect, la valeur sera la IntegrationResolvedRoute vers laquelle rediriger. Sinon, la valeur sera indéfinie.

RedirectConfig

Type : string | { status: ValidRedirectStatus; destination: string; }

Décrit la destination d’une redirection. Il peut s’agir d’une chaîne de caractères ou d’un objet contenant des informations sur le code d’état et sa destination.

RouteData

Décrit les informations à propos d’une route.

RouteData.route

Type : string

Définit le modèle de route actuel. Voici quelques exemples de chemins associés à leur modèle :

• src/pages/index.astro sera /
• src/pages/blog/[...slug].astro sera /blog/[...slug]
• src/pages/site/[blog]/[...slug].astro sera /site/[blog]/[...slug]

RouteData.component

Type : string

Spécifie l’URL du composant source.

RouteData.generate()

Type : (data?: any) => string

Fonction qui fournit les paramètres facultatifs de la route, les interpole avec le modèle de route et renvoie le nom de chemin de la route.

Par exemple, avec une route telle que /blog/[...id].astro, la fonction generate() pourrait renvoyer :

generate({ id: 'presentation' }) // affichera `/blog/presentation`

RouteData.params

Type : string[]

Permet d’accéder aux paramètres (params) de la route. Par exemple, lorsqu’un projet utilise les routes dynamiques suivantes /pages/[lang]/[...slug].astro, la valeur sera ['lang', '...slug'].

RouteData.pathname

Type : string | undefined

Pour les routes classiques, la valeur sera le chemin d’accès de l’URL où cette route sera desservie. Lorsqu’un projet utilise les routes dynamiques (c’est-à-dire [dynamic] ou [...spread]), le chemin sera indéfini.

RouteData.distURL

Type : URL[] | undefined

Ajouté à la version : astro@5.0.0

Définit les chemins d’accès aux fichiers physiques émis par cette route. Lorsqu’une route n’est pas pré-rendue, la valeur est soit undefined, soit un tableau vide.

RouteData.pattern

Type : RegExp

Spécifie une expression régulière à utiliser pour faire correspondre une URL d’entrée à une route demandée.

Par exemple, étant donné un chemin [fruit]/about.astro, l’expression régulière sera /^\/([^/]+?)\/about\/?$/. L’utilisation de pattern.test("banana/about") renverra true.

RouteData.segments

Type : RoutePart[][]

Permet d’accéder aux paramètres (params) de la route avec des métadonnées supplémentaires. Chaque objet contient les propriétés suivantes :

• content : le nom du paramètre,
• dynamic : si la route est dynamique ou non,
• spread : si la route dynamique utilise la syntaxe de décomposition ou non.

Par exemple, la route suivante /pages/[blog]/[...slug].astro générera les segments :

[
  [ { content: 'pages', dynamic: false, spread: false } ],
  [ { content: 'blog', dynamic: true, spread: false } ],
  [ { content: '...slug', dynamic: true, spread: true } ]
]

RouteData.type

Type : RouteType

Permet d’identifier le type de route.

RouteData.prerender

Type : boolean

Détermine si une route utilise le rendu à la demande ou est pré-rendue statiquement au moment de la compilation.

Voir aussi prerendered dans la référence du routage.

RouteData.redirect

Type : RedirectConfig | undefined

Permet d’accéder à la route vers laquelle rediriger.

RouteData.redirectRoute

Type : RouteData | undefined

Spécifie les données de la route (RouteData) vers laquelle rediriger lorsque RouteData.type est redirect.

RouteData.fallbackRoutes

Type : RouteData[]

Ajouté à la version : astro@3.5.6

Définit une liste de données de routes vers lesquelles se rabattre lorsque i18n.fallback a une liste de paramètres régionaux.

RouteData.isIndex

Type : boolean

Spécifie si la route est un index de dossier (par exemple src/pages/index.astro, src/pages/blog/index.astro).

RouteData.origin

Type : 'internal' | 'external' | 'project'

Ajouté à la version : astro@5.0.0

Détermine si une route provient du noyau Astro (internal), d’une intégration (external) ou du projet de l’utilisateur (project).

RoutePart

Type : { content: string; dynamic: boolean; spread: boolean; }

Décrit un segment de route.

RoutePart.content

Type : string

Spécifie le nom du paramètre pour la route. Par exemple :

• about.astro porte le nom about
• [slug].astro porte le nom slug
• [...id].astro porte le nom id

RoutePart.dynamic

Type : boolean

Détermine si la route est dynamique ou non.

RoutePart.spread

Type : boolean

Détermine si la route dynamique utilise ou non la syntaxe de décomposition.

RouteType

Type : 'page' | 'endpoint' | 'redirect' | 'fallback'

Une union des types de route pris en charge :

• page : une route qui réside dans le système de fichiers, généralement un composant Astro
• endpoint : une route qui réside dans le système de fichiers, généralement un fichier JS qui expose les méthodes des points de terminaison
• redirect : une route qui pointe vers une autre route qui se trouve dans le système de fichiers
• fallback : une route qui n’existe pas dans le système de fichiers et qui doit être gérée par d’autres moyens, généralement un middleware

SSRComponentMetadata

Type : { propagation: PropagationHint; containsHead: boolean; }

Décrit les métadonnées de compilation d’un composant rendu par le serveur.

SSRComponentMetadata.propagation

Type : 'none' | 'self' | 'in-tree'

Une description de la manière d’afficher le contenu de l’en-tête à partir de ce composant, y compris si l’environnement d’exécution Astro doit attendre un composant :

• none : Le composant ne propage pas le contenu de l’en-tête.
• self : Ce composant ajoute le contenu de l’en-tête.
• in-tree : Un autre composant de l’arbre de dépendances de ce composant ajoute le contenu d’en-tête.

SSRComponentMetadata.containsHead

Type : boolean

Détermine si le composant contient le contenu de l’en-tête.

SSRLoadedRenderer

Type : { name: string; clientEntrypoint?: string | URL; ssr: SSRLoadedRendererValue; }

Décrit un moteur de rendu disponible pour le serveur. Il s’agit d’un sous-ensemble de AstroRenderer avec des propriétés supplémentaires.

SSRLoadedRenderer.ssr

Type : SSRLoadedRendererValue

Définit les fonctions et la configuration utilisées par le serveur pour ce framework.

SSRLoadedRendererValue

Contient les fonctions et la configuration nécessaires pour générer les composants sur le serveur à partir d’un framework d’interface utilisateur spécifique.

SSRLoadedRendererValue.name

Type : string

Spécifie le nom identifiant le moteur de rendu.

SSRLoadedRendererValue.check()

Type : AsyncRendererComponentFn<boolean>

Détermine si le moteur de rendu doit gérer le composant.

SSRLoadedRendererValue.renderToStaticMarkup()

Type : AsyncRendererComponentFn<{ html: string; attrs?: Record<string, string>; }>

Génère un composant de framework sous forme de balisage HTML statique sur le serveur.

SSRLoadedRendererValue.supportsAstroStaticSlot

Type : boolean

Ajouté à la version : astro@2.5.0

Indique si le moteur de rendu prend en charge l’optimisation des slots statiques d’Astro. Lorsque cette option est activée, Astro empêche la suppression des slots imbriqués au sein des îlots.

SSRLoadedRendererValue.renderHydrationScript()

Type : () => string

Ajouté à la version : astro@4.1.0

Renvoie un script d’hydratation spécifique au framework qui doit être injecté dans le HTML avant le premier composant utilisant ce moteur de rendu.

SSRManifest

Un objet contenant la configuration de compilation et les métadonnées du projet que les adaptateurs serveur utilisent au moment de l’exécution pour servir des pages rendues à la demande.

SSRManifest.hrefRoot

Type : string

Ajouté à la version : astro@4.12.0

Spécifie le chemin racine utilisé pour générer les URL.

SSRManifest.adapterName

Type : string

Définit le nom de l’adaptateur serveur utilisé pour le rendu à la demande.

SSRManifest.routes

Type : RouteInfo[]

Une liste d’informations à propos des routes disponibles dans ce projet. Chaque entrée contient les propriétés suivantes.

SSRManifest.routeData

Type : RouteData

Un objet décrivant les informations connues concernant une route.

SSRManifest.file

Type : string

Spécifie le chemin d’accès au fichier de point d’entrée pour la route générée.

SSRManifest.links

Type : string[]

Définit une liste d’éléments HTML link requis par cette route.

SSRManifest.scripts

Type : Array<{ children: string; stage: string } | { type: 'inline' | 'external'; value: string }>

Définit une liste des scripts associés à cette route. Cela inclut à la fois les scripts injectés par intégration avec les propriétés children et stage et les scripts hissés avec les propriétés type et value.

SSRManifest.styles

Type : Array<{ type: "inline"; content: string; } | { type: "external"; src: string; }>

Ajouté à la version : astro@2.4.0

Définit la liste des feuilles de style associées à cette route. Cela inclut à la fois les styles incorporés à la page et les URL de feuilles de style.

SSRManifest.site

Type : string

Spécifie le site configuré.

SSRManifest.base

Type : string

Spécifie le chemin de base configuré vers lequel déployer.

SSRManifest.userAssetsBase

Type : string | undefined

Ajouté à la version : astro@5.3.1

Spécifie le chemin de base à utiliser en mode développement pour les ressources générées par l’utilisateur, telles que les scripts et les styles.

SSRManifest.trailingSlash

Type : AstroConfig['trailingSlash']

Ajouté à la version : astro@3.5.4

Spécifie le comportement configuré pour les barres obliques finales en mode développement et pour les pages rendues à la demande.

SSRManifest.buildFormat

Type : NonNullable<AstroConfig['build']>['format']

Ajouté à la version : astro@4.2.2

Spécifie le format configuré pour le fichier de sortie.

SSRManifest.compressHTML

Type : boolean

Ajouté à la version : astro@2.7.2

Détermine si la minification HTML est activée dans la configuration du projet.

SSRManifest.assetsPrefix

Type : string | ({ fallback: string; } & Record<string, string>) | undefined

Ajouté à la version : astro@2.3.1

Spécifie le préfixe configuré pour les liens vers les ressources générées par Astro.

SSRManifest.renderers

Type : SSRLoadedRenderer[]

Une liste des moteurs de rendu (par exemple React, Vue, Svelte, MDX) disponibles pour le serveur.

SSRManifest.clientDirectives

Type : Map<string, string>

Ajouté à la version : astro@2.5.0

Définit une correspondance entre les noms des directives client (par exemple, load, visible) et leur code d’implémentation. Cela inclut à la fois les directives client intégrées et les directives client personnalisées.

SSRManifest.entryModules

Type : Record<string, string>

Définit une correspondance entre les points d’entrée et les chemins d’accès de leurs fichiers de sortie.

SSRManifest.inlinedScripts

Type : Map<string, string>

Ajouté à la version : astro@4.5.0

Définit une correspondance entre les identifiants de script et leur contenu pour les scripts qui seront incorporés dans la sortie HTML.

SSRManifest.assets

Type : Set<string>

Définit un ensemble de chemins d’accès aux fichiers pour tous les éléments faisant partie de la compilation.

SSRManifest.componentMetadata

Type : Map<string, SSRComponentMetadata>

Ajouté à la version : astro@2.1.7

Définit une correspondance entre les identifiants des composants et leurs métadonnées de compilation. Chaque entrée contient des informations sur le comportement de propagation et indique si elle contient des éléments d’en-tête.

SSRManifest.pageModule

Type : { page: ImportComponentInstance; onRequest?: MiddlewareHandler; renderers: SSRLoadedRenderer[]; }

Ajouté à la version : astro@2.7.0

Spécifie les informations relatives à un module de page.

SSRManifest.pageModule.page()

Type : () => Promise<ComponentInstance>

Une fonction permettant de récupérer une instance du composant de page.

SSRManifest.pageModule.onRequest()

Type : MiddlewareHandler

Ajouté à la version : astro@3.0.3

Une fonction middleware Astro lorsqu’elle est définie dans le projet utilisateur.

SSRManifest.pageModule.renderers

Type : SSRLoadedRenderer[]

Une liste des moteurs de rendu qu’un serveur peut utiliser pour cette page.

SSRManifest.pageMap

Type : Map<string, () => Promise<typeof pageModule>>

Définit une correspondance entre les chemins des composants et leurs instances importables.

SSRManifest.serverIslandMap

Type : Map<string, () => Promise<ComponentInstance>>

Ajouté à la version : astro@4.12.0

Définit une correspondance entre les identifiants des îlôts de serveur et leurs instances de composants.

SSRManifest.serverIslandNameMap

Type : Map<string, string>

Ajouté à la version : astro@4.12.0

Définit une correspondance entre les chemins d’accès aux composants d’îlôts de serveur et leurs noms attribués.

SSRManifest.key

Type : Promise<CryptoKey>

Ajouté à la version : astro@4.13.4

Détermine la clé cryptographique utilisée pour chiffrer les propriétés des îlôts de serveur.

SSRManifest.i18n

Type : SSRManifestI18n | undefined

Ajouté à la version : astro@3.5.0

Spécifie la configuration i18n résolue lorsqu’elle est activée dans le projet.

SSRManifest.i18n.strategy

Type : "manual" | "pathname-prefix-always" | "pathname-prefix-other-locales" | "pathname-prefix-always-no-redirect" | "domains-prefix-always" | "domains-prefix-other-locales" | "domains-prefix-always-no-redirect"

Définit la stratégie de routage i18n configurée. Celle-ci détermine la manière dont les paramètres régionaux sont gérés dans les URL et si des redirections sont effectuées.

SSRManifest.i18n.locales

Type : Locales

Spécifie une liste des paramètres régionaux pris en charge et configurés dans le projet.

SSRManifest.i18n.defaultLocale

Type : string

Détermine le paramètre régional par défaut configuré dans le projet.

SSRManifest.i18n.fallback

Type : Record<string, string> | undefined

Spécifie une correspondance entre des paramètres régionaux et leurs paramètres régionaux de repli tels que configurés dans i18n.fallback.

SSRManifest.i18n.fallbackType

Type : "redirect" | "rewrite"

Détermine la stratégie de repli configurée pour le projet.

SSRManifest.i18n.domainLookupTable

Type : Record<string, string>

Une correspondance entre les domaines configurés et leurs paramètres régionaux associés.

SSRManifest.middleware

Type : () => Promise<AstroMiddlewareInstance> | AstroMiddlewareInstance

Ajouté à la version : astro@4.2.5

Définit une instance pour charger le middleware.

SSRManifest.actions

Type : () => Promise<{ server: Record<string, ActionClient>; }> | { server: Record<string, ActionClient>; }

Ajouté à la version : astro@5.4.2

Un objet, ou une fonction qui renvoie un objet, avec une propriété server qui associe les noms d’actions à leurs fonctions exécutables.

SSRManifest.checkOrigin

Type : boolean

Ajouté à la version : astro@4.6.0

Détermine si la vérification d’origine est activée dans la configuration de sécurité.

SSRManifest.allowedDomains

Type : Partial<RemotePattern>[]

Spécifie la liste configurée des modèles d’hôtes autorisés pour les requêtes entrantes lors de l’utilisation du rendu à la demande.

SSRManifest.sessionConfig

Type : SessionConfig<TDriver> & { driverModule?: () => Promise<{ default: () => unstorage.Driver }>; }

Ajouté à la version : astro@5.1.0

Un objet contenant la configuration de session résolue et une propriété supplémentaire définissant le pilote utilisé.

SSRManifest.cacheDir

Type : string | URL

Ajouté à la version : astro@5.2.0

Spécifie le répertoire configuré pour la mise en cache des artefacts de compilation.

SSRManifest.srcDir

Type : string | URL

Ajouté à la version : astro@5.2.0

Spécifie le répertoire configuré à partir duquel Astro lira le site.

SSRManifest.outDir

Type : string | URL

Ajouté à la version : astro@5.2.0

Spécifie le répertoire configuré dans lequel écrire la version compilée.

SSRManifest.publicDir

Type : string | URL

Ajouté à la version : astro@5.2.0

Spécifie le répertoire configuré pour les ressources statiques.

SSRManifest.buildClientDir

Type : string | URL

Ajouté à la version : astro@5.2.0

Détermine le chemin d’accès dans le répertoire de compilation où les artefacts de compilation côté client (par exemple, JavaScript, CSS) sont générés.

SSRManifest.buildServerDir

Type : string | URL

Ajouté à la version : astro@5.2.0

Détermine le chemin d’accès où les artefacts de compilation côté serveur sont générés dans le répertoire de compilation.

SSRManifest.csp

Type : SSRManifestCSP | undefined

Ajouté à la version : astro@5.9.0

Décrit la configuration de la stratégie de sécurité du contenu.

SSRManifest.csp.cspDestination

Type : 'adapter' | 'meta' | 'header' | undefined

Spécifie si les directives CSP doivent être injectées en tant qu’élément meta, en tant qu’en-tête de réponse, ou par l’adapter lorsqu’il prend en charge la définition des en-têtes de réponse.

SSRManifest.csp.algorithm

Type : 'SHA-256' | 'SHA-384' | 'SHA-512'

Spécifie la fonction de hachage configurée.

SSRManifest.csp.scriptHashes

Type : string[]

Spécifie une liste des hachages générés pour les scripts du projet et des hachages fournis par l’utilisateur pour les scripts externes.

SSRManifest.csp.scriptResources

Type : string[]

Spécifie une liste de sources valides combinant les ressources de script configurées et les ressources de script injectées.

SSRManifest.csp.isStrictDynamic

Type : boolean

Détermine si la prise en charge de l’injection de script dynamique est activée dans la configuration.

SSRManifest.csp.styleHashes

Type : string[]

Spécifie une liste des hachages générés pour les styles du projet et des hachages fournis par l’utilisateur pour les styles externes.

SSRManifest.csp.styleResources

Type : string[]

Spécifie une liste de sources valides combinant les ressources de style configurées et les ressources de style injectées.

SSRManifest.csp.directives

Type : CspDirective[]

Spécifie la liste configurée des sources valides pour des types de contenu spécifiques.

SSRManifest.internalFetchHeaders

Type : Record<string, string>

Ajouté à la version : astro@5.15.0

Spécifie les en-têtes qui sont automatiquement ajoutés aux requêtes de récupération internes effectuées lors du rendu.

ValidRedirectStatus

Type : 301 | 302 | 303 | 307 | 308 | 300 | 304

Une union des codes d’état de redirection pris en charge.

Importations de types dépréciées

Les types suivants sont dépréciés et seront supprimés dans une future version majeure :

IntegrationRouteData

Attention

Ce type est déprécié depuis la v5.0. Utilisez plutôt IntegrationResolvedRoute.

Une version plus petite de RouteData qui est utilisée dans les intégrations.

type IntegrationRouteData = Omit<
  RouteData,
  'isIndex' | 'fallbackRoutes' | 'redirectRoute' | 'origin'
> & {
  redirectRoute?: IntegrationRouteData;
};

redirectRoute

Type : IntegrationRouteData | undefined

Lorsque la valeur de RouteData.type est redirect, la valeur contiendra les données IntegrationRouteData de la route vers laquelle rediriger. Sinon, la valeur sera indéfinie.

Autoriser l’installation avec 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 intégration soit installable avec cet outil, ajoutez astro-integration au champ keywords dans votre package.json :

{
  "name": "example",
  "keywords": ["astro-integration"],
}

Une fois que vous avez publié votre intégration sur npm, lancer astro add example installera votre paquet avec toutes les dépendances spécifiées dans votre package.json. Cela appliquera également votre intégration au astro.config de l’utilisateur comme suit :

astro.config.mjs

import { defineConfig } from 'astro/config';
 import example from 'example';

export default defineConfig({
  integrations: [example()],
})

Attention

Cela suppose que votre définition d’intégration est 1) une exportation default et 2) une fonction. Assurez-vous que c’est le cas avant d’ajouter le mot-clé astro-integration !

Ordre des intégrations

Toutes les intégrations sont exécutées dans l’ordre dans lequel elles sont configurées. Par exemple, pour le tableau [react(), svelte()] dans le fichier astro.config.* d’un utilisateur, react s’exécutera avant svelte.

Votre intégration devrait idéalement s’exécuter dans n’importe quel ordre. Si ce n’est pas possible, nous recommandons de documenter que votre intégration doit venir en premier ou en dernier dans le tableau de configuration integrations de votre utilisateur.

Combiner les intégrations dans des préréglages

Une intégration peut également être écrite sous la forme d’une collection de plusieurs intégrations plus petites. Nous appelons ces collections des préréglages. Au lieu de créer une fonction d’usine qui renvoie un seul objet d’intégration, un préréglage renvoie un tableau d’objets d’intégration. Cela est utile pour créer des fonctionnalités complexes à partir de plusieurs intégrations.

integrations: [
  // Exemple : lorsque examplePreset() retourne : [integrationOne, integrationTwo, ...etc]
  examplePreset()
]

Ressources communautaires

• Créez vos propres intégrations Astro (en) - par Emmanuel Ohans sur FreeCodeCamp
• Modèle d’Intégration Astro - par Florian Lefebvre sur GitHub