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
Titre de la section ExemplesLes 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
Titre de la section Référence rapide de l’APIinterface 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 :
astro:config:setup
Titre de la section astro:config:setupProchain 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>;
Option config
Titre de la section Option configType: 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
Titre de la section Option commandType : 'dev' | 'build' | 'preview' | 'sync'
dev
- Le projet est exécuté avecastro dev
build
- Le projet est exécuté avecastro build
preview
- Le projet est exécuté avecastro preview
sync
- Le projet est exécuté avecastro sync
Option isRestart
Titre de la section Option isRestartType : boolean
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()
Titre de la section 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()
Titre de la section 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 callbackrenderToString
de React est un exemple classique.
Ajouté à la version :
astro@5.0.0
Les fonctions clientEntrypoint
et serverEntrypoint
acceptent une URL
.
Option addWatchFile()
Titre de la section Option addWatchFile()Type : (path: URL | string) => void
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));
Option addClientDirective()
Titre de la section Option addClientDirective()Type : (directive:
ClientDirectiveConfig
) => void;
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 :
import { defineConfig } from 'astro/config';import clickDirective from './astro-click-directive/register.js'
// https://astro.build/configexport 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()
Titre de la section Option addDevToolbarApp()Type : (entrypoint: DevToolbarAppEntry) => void;
astro@3.4.0
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/configexport default defineConfig({ integrations: [ devToolbarIntegration() ],});
/** * @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" }); }, },});
/** * @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()
Titre de la section Option addMiddleware()Type : (middleware:
AstroIntegrationMiddleware
) => void;
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
).
/** * @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.
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()
Titre de la section 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 pattern
et un entrypoint
.
pattern
- lorsque la route doit être affichée dans le navigateur, par exemple/foo/bar
. Unpattern
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 lepattern
.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 lepattern
.prerender
- un booléen à définir si Astro ne peut pas détecter votre exportationprerender
.
Exemple d’utilisation
Titre de la section Exemple d’utilisationinjectRoute({ // 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
:
{ "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()
Titre de la section 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 globalAstro
n’est pas disponible et votre script ne sera exécuté qu’une seule fois lorsque l’instructionimport
est évalué pour la première fois.La principale utilisation de l’étape
page-ssr
est l’injection d’unimport
CSS dans chaque page à optimiser et à résoudre par Vite :injectScript('page-ssr', 'import "global-styles.css";');
createCodegenDir
Titre de la section createCodegenDirType : () => URL;
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:route:setup
Titre de la section 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 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>;
Option route
Titre de la section Option routeType : 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
.
route.component
Titre de la section route.componentType : string
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
Titre de la section route.prerenderType : boolean
Par défaut : undefined
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
.
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
Titre de la section 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
Titre de la section Option routesType : 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) }, } }}
astro:config:done
Titre de la section astro:config:doneHook 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>;
Option config
Titre de la section Option configType : 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()
Titre de la section Option setAdapter()Type : (adapter: AstroAdapter) => void;
Transforme l’intégration en adaptateur. Pour en savoir plus, consultez l’API de l’adaptateur.
Options injectTypes()
Titre de la section Options injectTypes()Type : (injectedType: { filename: string; content: string }) => URL
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
buildOutput
option
Titre de la section buildOutput optionType : 'static' | 'server'
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
Titre de la section astro:server:setupHook 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
Titre de la section Option serverType : 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
Titre de la section Option toolbarType : ReturnType<typeof getToolbarServerCommunicationHelpers>
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.
onAppInitialized()
Titre de la section 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.
onAppToggled()
Titre de la section 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.
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()
Titre de la section Option refreshContent()Type : (options: { loaders?: Array<string>; context?: Record<string, any>; }) => Promise<void>
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
Titre de la section astro:server:startHook 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
Titre de la section Option addressType : AddressInfo
L’adresse, la famille et le numéro de port fournis par le module Node.js Net.
astro:server:done
Titre de la section astro:server:doneHook 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
Titre de la section astro:build:startHook 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>;
astro:build:setup
Titre de la section astro:build:setupHook 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>;
Option vite
Titre de la section Option viteType : 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; }, }}
Option pages
Titre de la section Option pagesType : 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); } }); }, }}
Option target
Titre de la section Option targetType : '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 } }, }}
Option updateConfig()
Titre de la section Option updateConfig()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()], }) } }}
astro:build:ssr
Titre de la section astro:build:ssrHook 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>;
Option manifest
Titre de la section Option manifestType : 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 } }, },}
Option entryPoints
Titre de la section Option entryPointsType : Map<IntegrationRouteData, URL>
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); }); }, },}
Option middlewareEntryPoint
Titre de la section Option middlewareEntryPointType : URL | undefined
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 } }, },}
astro:build:generated
Titre de la section 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 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>;
Option dir
Titre de la section Option dirType : 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)); } }}
astro:build:done
Titre de la section astro:build:doneHook 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>;
Option dir
Titre de la section Option dirType : 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
Titre de la section Option routesCette propriété est obsolète 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 projetpathname
- l’URL du fichier de sortie (non définie pour les routes utilisant les paramètres[dynamic]
et[...spread]
)
Option assets
Titre de la section Option assetsType : Map<string, URL[]>
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
Titre de la section Option pagesType : { 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.
Hooks personnalisés
Titre de la section Hooks personnalisésDes 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é.
Référence des types des intégrations
Titre de la section Référence des types des intégrationsAstroIntegrationLogger
Titre de la section AstroIntegrationLoggerUne 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.
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 :
[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 :
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é :
[astro-format] Intégration prête.[astro-format/build] Construction terminée.
HookParameters
Titre de la section HookParametersVous 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 IntegrationResolvedRouteinterface 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';}
pattern
Titre de la section patternType : 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]
patternRegex
Titre de la section patternRegexType : 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
.
entrypoint
Titre de la section entrypointType : string
L’URL d’accès du composant source.
isPrerendered
Titre de la section isPrerenderedType : 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 pasconst prerender = true
output: 'server'
quand la route exporteconst prerender = false
redirectRoute
Titre de la section redirectRouteType : IntegrationResolvedRoute | undefined
Lorsque la valeur de IntegrationResolvedRoute.type
est redirect
, la valeur sera la IntegrationResolvedRoute
vers laquelle rediriger. Sinon, la valeur sera indéfinie.
generate()
Titre de la section 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 :
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']
.
pathname
Titre de la section pathnameType : 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.
segments
Titre de la section segmentsType : 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 Astroendpoint
: 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 terminaisonredirect
: une route qui pointe vers une autre route qui se trouve dans le système de fichiersfallback
: 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
redirect
Titre de la section redirectType : 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 IntegrationRouteDataCe type est obsolète depuis la v5.0. Utilisez plutôt IntegrationResolvedRoute
.
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 Astroendpoint
: 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 terminaisonredirect
: une route qui pointe vers une autre route qui se trouve dans le système de fichiersfallback
: 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
component
Titre de la section componentType : string
Vous permet d’accéder à l’URL du chemin d’accès du composant source.
pathname
Titre de la section pathnameType : 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.
pattern
Titre de la section patternType : 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']
.
segments
Titre de la section segmentsType : { 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 } ]]
.
generate()
Titre de la section 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 :
console.log(generate({ id: 'presentation' })) // affichera `/blog/presentation`
prerender
Titre de la section prerenderType : boolean
Détermine si la route est pré-rendue ou non.
distURL
Titre de la section distURLType : 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.
redirect
Titre de la section redirectType : 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.
redirectRoute
Titre de la section redirectRouteType : 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 addLa 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()],})
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
Titre de la section Ordre des intégrationsToutes 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églagesUne 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
Titre de la section 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