API d'intégration 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 : tailwind, partytown
Caractéristiques : 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: (pluginEntrypoint: string) => void;
      injectScript: (stage: InjectedScriptStage, content: string) => void;
      injectRoute: (injectedRoute: { pattern: string; entrypoint: string; prerender?: boolean }) => void;
      createCodegenDir: () => URL;
      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: { filename: string; content: string }) => URL;
      logger: AstroIntegrationLogger;
      }) => void | Promise<void>;
    'astro:route:setup'?: (options: { route: RouteOptions; logger: AstroIntegrationLogger; }) => void | Promise<void>;
    'astro:server:setup'?: (options: { server: vite.ViteDevServer; logger: AstroIntegrationLogger; }) => 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:generated'?: (options: { dir: URL; logger: AstroIntegrationLogger; }) => void | Promise<void>;
    'astro:build:ssr'?: (options: {
        manifest: SerializedSSRManifest;
        entryPoints: Map<IntegrationRouteData, URL>;
        logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:build:done'?: (options: {
      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>;

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

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

`astro:config:setup`

Prochain hook : astro:config:done

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 plugins 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: (pluginEntrypoint: string) => void;
  addWatchFile: (path: URL | string) => void;
  injectScript: (stage: InjectedScriptStage, content: string) => void;
  injectRoute: (injectedRoute: { pattern: string; entrypoint: string; prerender?: boolean }) => 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. Ceci est résolu 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

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 callback 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 les clés !

Par exemple, disons que vous devez fournir un plugin 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 callback pour ajouter un framework de composants (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 constructions statiques chaque fois que votre composant est utilisé. Ceux-ci devraient afficher les composants en balisage statique, avec des crochets pour l’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 : URL | string

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 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/user/.../my-config.json');
addWatchFile(new URL('./tailwind.config.js', config.root));

Option `addClientDirective`

Ajouté à la version : astro@2.6.0

Type : (directive: ClientDirectiveConfig ) => void;

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

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

Exemple d’utilisation :

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

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

/**
 * @type {() => import('astro').AstroIntegration}
 */
export default () => ({
  name: "client:click",
  hooks: {
    "astro:config:setup": ({ addClientDirective }) => {
      addClientDirective({
        name: "click",
        entrypoint: "./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 :

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

Option `addDevToolbarApp`

Ajouté à la version : astro@3.4.0

Type : (pluginEntrypoint: string) => void;

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

Exemple d’utilisation :

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

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

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

/**
 * @type {import('astro').DevToolbarApp}
 */
export default {
  id: "my-plugin",
  name: "My Plugin",
  icon: "<svg>...</svg>",
  init() {
    console.log("I'm a dev toolbar app!")
  },
};

Option `addMiddleware`

Ajouté à la version : astro@3.5.0

Type : (middleware: AstroIntegrationMiddleware ) => void;

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

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

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

import { defineMiddleware } from 'astro:middleware';

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

  return next();
});

Ajouté à la version : astro@5.0.0

La fonction accepte également une URL pour entrypoint :

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

Option `injectRoute`

Type : ({ pattern: string; entrypoint: string; pattern?: 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 pattern et un entrypoint.

pattern - lorsque la route doit être affichée dans le navigateur, par exemple /foo/bar. Un 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 le 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 le pattern.
prerender - un booléen à définir si Astro ne peut pas détecter votre exportation prerender.

Exemple d’utilisation

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

Pour une intégration conçue pour être installée dans d’autres projets, utilisez son nom de paquetage 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 :

{
  "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.

Le stage indique comment ce script (le contenu) doit être inséré. Certaines étapes 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 étape importe votre script, le global Astro n’est pas disponible et votre script ne sera exécuté qu’une seule fois lorsque l’instruction import est évalué pour la première fois.

La principale utilisation de l’étape page-ssr est l’injection d’un import CSS 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 :

import { writeFileSync } from 'node:fs'

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

`astro:routes:resolved`

Ajouté à la version : astro@5.0.0

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

Prochain hook : 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 :

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

                console.log(projectRoutes)
            },
        }
    }
}

Référence du type `IntegrationResolvedRoute`

interface IntegrationResolvedRoute {
  /**
   * Le **modèle** actuel de l'itinéraire. Par exemple :
   * - `src/pages/index.astro` a le modèle `/`
   * - `src/pages/blog/[...slug].astro` a le modèle `/blog/[...slug]`
   * - `src/pages/site/[blog]/[...slug].astro` a le modèle `/site/[blog]/[...slug]`
   */
  pattern: RouteData['route'];

  /**
   *
   * expression régulière utilisée pour faire correspondre une URL d'entrée à une route demandée
   * par ex. "[fruit]/about.astro" générera le modèle : /^\/([^/]+?)\/about\/?$/
   * où pattern.test("banana/about") renvoie "true"
   *
   * ## Exemple
   *
   * ```js
   * if (route.pattern.test('/blog')) {
   *  // faire quelque chose
   * }
   * ```
   */
  patternRegex: RouteData['pattern'];

  /**
   *  URL du composant source
   */
  entrypoint: RouteData['component'];

  /**
   * Définit si la route doit être pré-rendue ou non
   */
  isPrerendered: RouteData['prerender'];

  /**
   * La route {@link IntegrationResolvedRoute} vers laquelle rediriger. Elle est présente lorsque `IntegrationResolvedRoute.type` est `redirect`.
   */
  redirectRoute?: IntegrationResolvedRoute;

  /**
   * @param {any} data Les paramètres optionnels de la route
   *
   * @description
   * Une fonction qui accepte une liste de paramètres, les interpole avec le modèle de route et renvoie le nom de chemin de la route.
   *
   * ## Exemple
   *
   * Pour une route telle que `/blog/[...id].astro`, la fonction `generate` renverrait quelque chose comme ceci :
   *
   * ```js
   * console.log(generate({ id: 'presentation' })) // affichera `/blog/presentation`
   * ```
   */
  generate: (data?: any) => string;

  /**
   * Paramètres de route dynamiques et étendues
   * par ex. "/pages/[lang]/[...slug].astro" affichera les paramètres ['lang', '...slug']
   */
  params: string[];

  /**
   * Nom du chemin de l'URL de sortie où cette route sera desservie
   * remarque : ne sera pas défini pour les routes [dynamic] et [...spread]
   */
  pathname?: string;

  /**
   * Similaire au champ « params », mais avec davantage de métadonnées associées. Par exemple, pour `/site/[blog]/[...slug].astro`, les segments sont :
   *
   * 1. `{ content: 'site', dynamic: false, spread: false }`
   * 2. `{ content: 'blog', dynamic: true, spread: false }`
   * 3. `{ content: '...slug', dynamic: true, spread: true }`
   */
  segments: RoutePart[][];

  /**
   *
   * Le type de route. Il peut s'agir de :
   * - `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 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 le middleware
   */
  type: RouteType;

  /**
   * La route vers laquelle rediriger. Elle contient des informations concernant le code d'état et sa destination.
   */
  redirect?: RedirectConfig;

  /**
   * Détermine si la route provient du noyau Astro, d'une intégration ou du projet de l'utilisateur
   */
  origin: 'internal' | 'external' | 'project';
}

`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 crochets 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: { filename: string; content: string }) => URL;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Option `config`

Type : AstroConfig

Une copie en lecture seule de la configuration Astro fournie par l’utilisateur. Ce problème est résolu 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 de l’adaptateur.

Options `injectTypes`

Ajouté à la version : astro@4.14.0

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

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

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

 {
    name: 'my-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('Method Not Allowed');
                  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: ['my-loader']
                        });
                        res.writeHead(200, { 'Content-Type': 'application/json' });
                        res.end(JSON.stringify({ message: 'Content refreshed successfully' }));
                    } catch (error) {
                        res.writeHead(500, { 'Content-Type': 'application/json' });
                        res.end(JSON.stringify({ error: 'Failed to refresh content: ' + 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 }) => void | Promise<void>;

Option `address`

Type : AddressInfo

L’adresse, la famille et le numéro de port fournis par le module Node.js Net.

`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'?: () => 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 construction de la production.

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

'astro:build:start'?: () => void | Promise<void>;

`astro:build:setup`

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

Hook suivant : astro:build:ssr

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

Pourquoi : A ce stade, la configuration de Vite pour la construction a été complètement construite, 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 crochet 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>;

`astro:build:generated`

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

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

Pourquoi : Accéder aux routes et aux ressources générées avant que les artefacts de construction 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 }) => void | Promise<void>;

`astro:build:ssr`

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

Quand : Après la construction d’un SSR en production.

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 SSR personnalisés dans des plugins ou des intégrations.

entryPoints fait correspondre une route de page au fichier physique émis après la construction ;
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
}) => void | Promise<void>;

`astro:build:done`

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

Quand : Après l’achèvement d’une construction de production (SSG ou SSR).

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

'astro:build:done'?: (options: {
  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. Notez que si vous avez besoin d’un chemin absolu valide, vous devriez utiliser l’utilitaire intégré de Node fileURLToPath.

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('./my-integration.json', dir));
        await writeFile(outFile, JSON.stringify(metadata));
      }
    }
  }
}

Option `routes`

Type : IntegrationRouteData[]

Une liste de tous les itinéraires générés 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])

Référence du type `IntegrationRouteData`

interface IntegrationRouteData {
  /**
   * Le type de route. Il peut s'agir de :
   *
   * - `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 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 le middleware
   */
  type: 'page' | 'endpoint' | 'redirect' | 'fallback';
  /** URL du composant source */
  component: string;
  /**
   * Chemin d'accès à l'URL de sortie lorsque cette route sera servie
   * note: sera indéfini pour les routes [dynamic] et [...spread].
   */
  pathname?: string;
  /**
   * regex utilisée pour faire correspondre une URL d'entrée à une route demandée
   * ex. "[fruit]/about.astro" génère le modèle: /^\/([^/]+?)\/about\/?$/
   * lorsque pattern.test("banana/about") est "true"
   */
  pattern: RegExp;
  /**
   * Paramètres des routes dynamiques et étendues
   * ex. "/pages/[lang]/[..slug].astro" affichera les paramètres ['lang', '...slug']
   */
  params: string[];
  /**
   * Similaire au champ "params", mais avec plus de métadonnées associées.
   * ex. "/pages/[lang]/index.astro" produira les segments suivants
   * [[ { content: 'lang', dynamic: true, spread: false } ]]
   */
  segments: { content: string; dynamic: boolean; spread: boolean; }[][];
  /**
   * Une fonction qui accepte une liste de paramètres, les interpole avec le modèle de route et renvoie le nom de chemin de la route.
   *
   * ## Exemple
   *
   * Pour une route telle que `/blog/[...id].astro`, la fonction `generate` renverrait quelque chose comme ceci :
   *
   * ```js
   * console.log(generate({ id: 'presentation' })) // affichera `/blog/presentation`
   * ```
   * Ceci est généralement destiné à un usage interne, alors appelez avec prudence !
   */
  generate: (data?: any) => string;
  /**
   * Détermine si la route est pré-rendue ou non.
   */
  prerender: boolean;
  /**
   * Les chemins des fichiers physiques émis par cette route. Lorsqu'une route **n'est pas** pré-rendue, la valeur est soit `undefined` soit un tableau vide.
   */
  distURL?: URL[];
    /**
   * La route vers laquelle rediriger. Elle contient des informations concernant le code d'état et sa destination.
   */
  redirect?: RedirectConfig;
  /**
   * La route `IntegrationRouteData` vers laquelle rediriger. Il est présent lorsque `RouteData.type` est `redirect`.
   */
  redirectRoute?: IntegrationRouteData;
}

Option `assets`

Ajouté à la version : astro@5.0.0

Type : Map<string, URL[]>

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

Option `pages`

Type : { pathname: string }[]

Une liste de toutes les pages générées. Il s’agit d’un objet avec une propriété.

pathname - le chemin finalisé de la page.

`astro:route:setup`

Ajouté à la version : astro@4.14.0

Quand : Dans astro dev, chaque fois qu’une route est demandée. Dans astro build, tout en regroupant et en transformant un fichier de route.

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

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

Option `route`

Type : RouteOptions

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.

La propriété component est un chemin en lecture seule relatif à la racine du projet, par exemple "src/pages/blog/[slug].astro".

`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 (EN) 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.

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.

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 {
      'your: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é.

`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({ /* ... */ });
}

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 :

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

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

`AstroIntegrationLogger`

Une instance du logger Astro, utile pour écrire des logs. Ce logger utilise le même niveau de log configuré via le CLI.

Méthodes disponibles pour écrire dans le terminal :

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

Méthodes disponibles pour écrire dans le terminal :

import type { AstroIntegration } from "astro";
export function formatIntegration(): AstroIntegration {
    return {
        name: "astro-format",
        hooks: {
            "astro:build:done": ({ logger }) => {
                // fait quelque chose
                logger.info("Integration ready.");
            }
        }
    }
}

L’exemple ci-dessus enregistre un message qui comprend le message info fourni :

[astro-format] Integration ready.

Pour enregistrer certains messages avec un libellé différent, utilisez la méthode .fork pour spécifier une alternative au name par défaut :

import type { AstroIntegration } from "astro";
export function formatIntegration(): AstroIntegration {
    return {
        name: "astro-format",
        hooks: {
            "astro:config:done": ({ logger }) => {
                // fait quelque chose
                logger.info("Integration ready.");
            },
            "astro:build:done": ({ logger }) => {
                const buildLogger = logger.fork("astro-format/build");
                // fait quelque chose
                buildLogger.info("Build finished.")
            }
        }
    }
}

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

[astro-format] Integration ready.
[astro-format/build] Build finished.

Commande d’intégration

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 décrite comme une collection de plusieurs intégrations plus petites. Au lieu de créer une fonction d’usine qui renvoie un objet d’intégration unique, nous appelons ces collections présets, un preset renvoie un array d’objets d’intégration. Cette fonction 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

Build your own Astro Integrations - de Emmanuel Ohans on FreeCodeCamp
Astro Integration Template - de Florian Lefebvre on GitHub

Contribuer

Communauté

API d'intégration d'Astro

Exemples

Référence rapide de l’API

Hooks

astro:config:setup

Option config

Option command

Option isRestart

Option updateConfig

Option addRenderer

Option addWatchFile

Option addClientDirective

Option addDevToolbarApp

Option addMiddleware

Option injectRoute

Exemple d’utilisation

Option injectScript

createCodegenDir

astro:routes:resolved

Option routes

Référence du type IntegrationResolvedRoute

astro:config:done

Option config

Option setAdapter

Options injectTypes

astro:server:setup

Option server

Option refreshContent

astro:server:start

Option address

astro:server:done

astro:build:start

astro:build:setup

astro:build:generated

astro:build:ssr

astro:build:done

Option dir

Option routes

Référence du type IntegrationRouteData

Option assets

Option pages

astro:route:setup

Option route

route.prerender

Hooks personnalisés

HookParameters

Autoriser l’installation avec astro add

AstroIntegrationLogger

Commande d’intégration

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

Ressources communautaires

`astro:config:setup`

Option `config`

Option `command`

Option `isRestart`

Option `updateConfig`

Option `addRenderer`

Option `addWatchFile`

Option `addClientDirective`

Option `addDevToolbarApp`

Option `addMiddleware`

Option `injectRoute`

Option `injectScript`

`createCodegenDir`

`astro:routes:resolved`

Option `routes`

Référence du type `IntegrationResolvedRoute`

`astro:config:done`

Option `config`

Option `setAdapter`

Options `injectTypes`

`astro:server:setup`

Option `server`

Option `refreshContent`

`astro:server:start`

Option `address`

`astro:server:done`

`astro:build:start`

`astro:build:setup`

`astro:build:generated`

`astro:build:ssr`

`astro:build:done`

Option `dir`

Option `routes`

Référence du type `IntegrationRouteData`

Option `assets`

Option `pages`

`astro:route:setup`

Option `route`

`route.prerender`

`HookParameters`

Autoriser l’installation avec `astro add`

`AstroIntegrationLogger`