Aller au contenu

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.

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

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

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 :

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 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: (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>;

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.

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

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.

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()],
}
})
}
}
}

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.

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

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 intégré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
}
}

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: "my-plugin",
name: "My Plugin"
});
},
},
});
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!")
},
};

Type : (middleware: AstroIntegrationMiddleware ) => void;

Ajouté à la version : astro@3.5.0

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

@my-package/integration.js
/**
* @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 paquet avec une fonction onRequest, comme pour le middleware défini par l’utilisateur.

@my-package/middleware.js
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 :

@my-package/integration.js
/**
* @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'
});
},
},
});

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

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

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 :

my-integration.ts
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')
}
}
}

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 module 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 construction ou de la demande, comme l’activation du rendu du serveur à la demande.

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

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.

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.

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.

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

Type : IntegrationResolvedRoute[]

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

Exemple d’utilisation :

my-integration.mjs
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)
},
}
}
}

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: InjectedType) => URL;
logger: AstroIntegrationLogger;
buildOutput: 'static' | 'server';
}) => void | Promise<void>;

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.

Type : (adapter: AstroAdapter) => void;

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

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

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.

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

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

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:

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.

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.

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.

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.

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.

my-integration.ts
{
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.

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

Type : AddressInfo

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

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

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'?: (options: {
logger: AstroIntegrationLogger;
}) => void | Promise<void>;

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

Type : InlineConfig

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

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

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

Type : Map<string, PageBuildData>

Une Map avec une liste de pages comme clé et leurs données de construction comme valeur.

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

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

Type : 'client' | 'server'

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

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

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

Type : (newConfig: InlineConfig) => void

Une fonction de rappel pour mettre à jour les options Vite utilisées dans la construction. 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 plugin au projet de l’utilisateur :

import awesomeCssPlugin from 'awesome-css-vite-plugin';
export default {
name: 'my-integration',
hooks: {
'astro:build:setup': ({ updateConfig }) => {
updateConfig({
plugins: [awesomeCssPlugin()],
})
}
}
}

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

Hook suivant : astro:build:generated

Quand : Une fois la construction SSR de 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 builds 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 | undefined;
logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Type : SerializedSSRManifest

Vous permet de créer une construction personnalisée en accédant au manifeste SSR.

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

Type : Map<IntegrationRouteData, URL>

Ajouté à la version : astro@2.7.0

Une Map des points d’entrée émis avec IntegrationRouteData comme clé et l’URL du fichier physique comme valeur.

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

Type : URL | undefined

Ajouté à la version : astro@2.8.0

Expose le chemin du fichier middleware.

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

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 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;
logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Type : URL

Un chemin URL vers le répertoire de sortie de la construction. Notez que si vous avez besoin d’une chaîne de chemin absolu valide, vous devez utiliser l’utilitaire intégré fileURLToPath de Node.

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

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

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

Pourquoi : Pour accéder aux routes et aux ressources générées pour l’extension (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 Plugin 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>;

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

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

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.

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.

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

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

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 info fourni :

Fenêtre du terminal
[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("Construction terminée.")
}
}
}
}

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

Fenêtre du terminal
[astro-format] Intégration prête.
[astro-format/build] Construction terminée.

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

Référence du type IntegrationResolvedRoute

Titre de la section Référence du type IntegrationResolvedRoute
interface IntegrationResolvedRoute {
pattern: RouteData['route'];
patternRegex: RouteData['pattern'];
entrypoint: RouteData['component'];
isPrerendered: RouteData['prerender'];
redirectRoute?: IntegrationResolvedRoute;
generate: (data?: any) => string;
params: string[];
pathname?: string;
segments: RoutePart[][];
type: RouteType;
redirect?: RedirectConfig;
origin: 'internal' | 'external' | 'project';
}

Type : string

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]

Type : RegExp

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.

Type : string

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

Type : boolean

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

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.

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 :

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

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'].

Type : string | undefined

Pour les routes régulières, 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.

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 } ]
]

Type : RouteType

Permet d’identifier le type de route. Les valeurs possibles sont :

  • 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 le middleware

Type : RedirectConfig | undefined

Permet d’accéder à la route vers laquelle rediriger. 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.

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

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

Référence du type IntegrationRouteData

Titre de la section Référence du type IntegrationRouteData

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

interface IntegrationRouteData {
type: RouteType;
component: string;
pathname?: string;
pattern: RegExp;
params: string[];
segments: { content: string; dynamic: boolean; spread: boolean; }[][];
generate: (data?: any) => string;
prerender: boolean;
distURL?: URL[];
redirect?: RedirectConfig;
redirectRoute?: IntegrationRouteData;
}

Type : RouteType

Permet d’identifier le type de route. Les valeurs possibles sont :

  • 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 le middleware

Type : string

Vous permet d’accéder à l’URL du chemin d’accès du composant source.

Type : string | undefined

Pour les routes régulières, 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.

Type : RegExp

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.

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'].

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

Vous 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 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/[lang]/index.astro affichera les segments [[ { content: 'lang', dynamic: true, spread: false } ]].

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 :

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

Type : boolean

Détermine si la route est pré-rendue ou non.

Type : URL[] | undefined

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.

Type : RedirectConfig | undefined

Permet d’accéder à la route vers laquelle rediriger. 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.

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

Titre de la section 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()],
})

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

Titre de la section 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()
]
Contribuer Communauté Parrainer