Utiliser les Intégrations

Les intégrations Astro permettent d’ajouter de nouvelles fonctionnalités et de nouveaux comportements à votre projet en quelques lignes de code. Vous pouvez utiliser une intégration officielle, des intégrations créées par la communauté ou même créer vous-même une intégration personnalisée.

Les intégrations peuvent…

• Débloquer React, Vue, Svelte, Solid et d’autres frameworks UI populaires.
• Intégrer des outils comme Tailwind et Partytown avec quelques lignes de code.
• Ajouter de nouvelles fonctionnalités à votre projet, comme la génération automatique de sitemap.
• Écrire du code personnalisé qui s’accroche au processus de construction, au serveur de développement, et plus encore.

Répertoire des intégrations

Parcourez ou recherchez des centaines d’intégrations officielles et communautaires dans notre répertoire d’intégrations. Trouvez des packages à ajouter à votre projet Astro pour l’authentification, l’analyse, la performance, le référencement (SEO), l’accessibilité, l’interface utilisateur, les outils de développement, et plus encore.

Intégrations Officielles

Titre de la section Intégrations Officielles

Les intégrations suivantes sont gérées par Astro.

Framework d'interface utilisateur

• 

  @astrojs/alpinejs

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

Adaptateurs SSR

• 

  @astrojs/cloudflare

• 

  @astrojs/netlify

• 

  @astrojs/node

• 

  @astrojs/vercel

Autres intégrations

• 

  @astrojs/db

• 

  @astrojs/markdoc

• 

  @astrojs/mdx

• 

  @astrojs/partytown

• 

  @astrojs/sitemap

• 

  @astrojs/tailwind

Configuration automatique des intégrations

Titre de la section Configuration automatique des intégrations

Astro inclut une commande astro add pour automatiser la mise en place des intégrations officielles. Plusieurs plugins communautaires peuvent également être ajoutés en utilisant cette commande. Veuillez consulter la documentation de chaque intégration pour savoir si astro add est supporté, ou si vous devez installer manuellement.

Exécutez la commande astro add en utilisant le gestionnaire de paquets de votre choix et notre assistant d’intégration automatique mettra à jour votre fichier de configuration et installera toutes les dépendances nécessaires.

npm

npx astro add react

pnpm

pnpm astro add react

Yarn

yarn astro add react

Il est même possible d’ajouter plusieurs intégrations en même temps !

npm

npx astro add react tailwind partytown

pnpm

pnpm astro add react tailwind partytown

Yarn

yarn astro add react tailwind partytown

Gestion des dépendances d’intégration

Si vous voyez des avertissements comme Cannot find package '[package-name]' après avoir ajouté une intégration, votre gestionnaire de paquets peut ne pas avoir installé les dépendances des pairs pour vous. Pour installer ces paquets manquants, lancez npm install [nom-du-paquet].

Installation manuelle

Titre de la section Installation manuelle

Les intégrations Astro sont toujours ajoutées via la propriété integrations dans votre fichier astro.config.mjs.

Il y a trois façons d’importer une intégration dans votre projet Astro :

1. En installant un paquet d’intégration npm.
2. En important votre propre intégration depuis un fichier local dans votre projet.
3. En écrivant votre intégration en ligne, directement dans votre fichier de configuration.

astro.config.mjs

import { defineConfig } from 'astro/config';
import installedIntegration from '@astrojs/vue';
import localIntegration from './my-integration.js';

export default defineConfig({
  integrations: [
    // 1. Importer à partir d'un paquet npm installé
    installedIntegration(),
    // 2. Importer depuis un fichier JS local
    localIntegration(),
    // 3. Depuis un objet en ligne
    {name: 'namespace:id', hooks: { /* ... */ }},
  ]
})

Consultez l’API intégration de référence pour connaître les différentes façons d’écrire une intégration.

Installation d’un paquet NPM

Titre de la section Installation d’un paquet NPM

Installez une intégration en utilisant un gestionnaire de paquet, puis mettez à jour astro.config.mjs manuellement.

Par exemple, pour installer l’intégration @astrojs/sitemap :

1. Installez l’intégration dans les dépendances de votre projet en utilisant votre gestionnaire de paquets préféré :

   npm

   npm install @astrojs/sitemap

   pnpm

   pnpm add @astrojs/sitemap

   Yarn

   yarn add @astrojs/sitemap

2. Importez l’intégration dans votre fichier astro.config.mjs, et ajoutez-la à votre tableau integrations[], avec toutes les options de configuration :

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import sitemap from '@astrojs/sitemap';
   
   export default defineConfig({
     // ...
     integrations: [sitemap()],
     // ...
   });

   Notez que les différentes intégrations peuvent avoir des paramètres de configuration différents. Lisez la documentation de chaque intégration, et appliquez toutes les options de configuration nécessaires à l’intégration choisie dans astro.config.mjs

Options personnalisées

Titre de la section Options personnalisées

Les intégrations sont presque toujours conçues comme des fonctions “factory” qui renvoient l’objet d’intégration proprement dit. Cela vous permet de passer des arguments et des options à la fonction “factory” afin de personnaliser l’intégration pour votre projet.

integrations: [
  // Exemple : Personnalisez votre intégration avec des arguments de fonction
  sitemap({filter: true})
]

Activer/Désactiver une intégration

Titre de la section Activer/Désactiver une intégration

Les intégrations Falsy sont ignorées, vous pouvez donc les activer et les désactiver sans vous soucier des valeurs undefined et booléennes laissées en suspens.

integrations: [
  // Exemple : Sauter la construction d'un plan du site sous Windows
  process.platform !== 'win32' && sitemap()
]

Mise à jour des intégrations

Titre de la section Mise à jour des intégrations

Pour mettre à jour toutes les intégrations officielles en une seule fois, lancez la commande @astrojs/upgrade. Cela mettra à jour Astro et toutes les intégrations officielles vers leurs dernières versions.

Mise à jour automatique

Titre de la section Mise à jour automatique

npm

# Mise à jour d'Astro et des intégrations officielles vers la version la plus récente
npx @astrojs/upgrade

pnpm

# Mise à jour d'Astro et des intégrations officielles vers la version la plus récente
pnpm dlx @astrojs/upgrade

Yarn

# Mise à jour d'Astro et des intégrations officielles vers la version la plus récente
yarn dlx @astrojs/upgrade

Mise à jour manuelle

Titre de la section Mise à jour manuelle

Pour mettre à jour manuellement une ou plusieurs intégrations, utilisez la commande appropriée de votre gestionnaire de paquets.

npm

# Exemple : mise à jour des intégrations React et Tailwind
npm install @astrojs/react@latest @astrojs/tailwind@latest

pnpm

# Exemple : mise à jour des intégrations React et Tailwind
pnpm add @astrojs/react@latest @astrojs/tailwind@latest

Yarn

# Exemple : mise à jour des intégrations React et Tailwind
yarn add @astrojs/react@latest @astrojs/tailwind@latest

Supprimer une Intégration

Titre de la section Supprimer une Intégration

Pour supprimer une intégration, désinstallez d’abord l’intégration de votre projet

npm

npm uninstall @astrojs/react

pnpm

pnpm remove @astrojs/react

Yarn

yarn remove @astrojs/react

Ensuite, supprimez l’intégration de votre fichier astro.config.* :

astro.config.mjs

import { defineConfig } from 'astro/config';

import react from '@astrojs/react';

export default defineConfig({
  integrations: [
    react()
  ]
})

Trouver d’autres intégrations

Titre de la section Trouver d’autres intégrations

Vous trouverez de nombreuses intégrations développées par la communauté dans le répertoire des intégrations d’Astro. Suivez les liens pour obtenir des instructions détaillées d’utilisation et de configuration

Construire votre propre intégration

Titre de la section Construire votre propre intégration

L’API d’intégration d’Astro s’inspire de Rollup et de Vite, et est conçue pour être familière à quiconque a déjà écrit un plugin Rollup ou Vite.

Consultez l’API intégration de référence pour apprendre ce que les intégrations peuvent faire et comment en écrire une vous-même.