Utiliser les intégrations

Les intégrations d’Astro ajoutent de nouvelles fonctionnalités et de nouveaux comportements à votre projet en quelques lignes de code seulement. 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 d’interface utilisateur populaires avec un moteur de rendu.
Activer le rendu à la demande avec un adaptateur SSR.
Intégrer des outils comme MDX et Partytown en quelques lignes de code.
Ajouter de nouvelles fonctionnalités à votre projet, comme la génération automatique du plan du site.
Écrire du code personnalisé qui se branche au processus de compilation, au serveur de développement, et plus encore.

Intégrations officielles

Les intégrations suivantes sont maintenues par Astro.

Framework d'interface utilisateur

Adaptateurs SSR

Autres intégrations

Configuration automatique des intégrations

Astro inclut une commande astro add pour automatiser la configuration des intégrations officielles. Plusieurs modules d’extension communautaires peuvent également être ajoutés à l’aide de cette commande. Veuillez consulter la documentation de chaque intégration pour voir si astro add est pris en charge ou si vous devez l’installer manuellement.

Exécutez la commande astro add à l’aide du 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.

npx astro add react

pnpm astro add react

yarn astro add react

Il est même possible d’ajouter plusieurs intégrations simultanément !

npx astro add react sitemap partytown

pnpm astro add react sitemap partytown

yarn astro add react sitemap partytown

Si vous voyez des avertissements comme Cannot find package '[package-name]' après avoir ajouté une intégration, il se peut que votre gestionnaire de packages n’ait pas installé les dépendances homologues pour vous. Pour installer ces paquets manquants, exécutez la commande suivante :

npm install [nom-du-paquet]

pnpm add [nom-du-paquet]

yarn add [nom-du-paquet]

Installation manuelle

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

Il existe trois méthodes courantes pour importer une intégration dans votre projet Astro :

Installer une intégration avec un paquet npm.
Importer votre propre intégration à partir d’un fichier local dans votre projet.

Écrire le code de votre intégration directement dans votre fichier de configuration.

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

export default defineConfig({
  integrations: [
    // 1. Importé depuis un paquet npm installé
    installedIntegration(),
    // 2. Importé depuis un fichier JS local
    localIntegration(),
    // 3. Un objet incorporé à la configuration
    { name: 'namespace:id', hooks: { /* ... */ } },
  ]
});

Consultez la référence de l’API des intégrations pour découvrir les différentes façons de créer une intégration.

Installation d’un paquet npm

Installez un paquet npm contenant une intégration à l’aide d’un gestionnaire de paquets, puis mettez à jour astro.config.mjs manuellement.

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

Installez l’intégration dans les dépendances de votre projet à l’aide de votre gestionnaire de paquets préféré :
- npm
- pnpm
- Yarn
Fenêtre du terminal
npm install @astrojs/sitemap
Fenêtre du terminal
pnpm add @astrojs/sitemap
Fenêtre du terminal
yarn add @astrojs/sitemap
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 paramètres de configuration peuvent varier d’une intégration à l’autre. Consultez la documentation de chaque intégration et appliquez les options de configuration nécessaires à l’intégration choisie dans le fichier astro.config.mjs.

Options personnalisées

Les intégrations sont presque toujours conçues comme des fonctions de fabrique (ou « factory functions » en anglais) qui renvoient l’objet d’intégration. Cela vous permet de transmettre des arguments et des options à la fonction de fabrique afin de personnaliser l’intégration pour votre projet.

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

Activer/désactiver une intégration

Les intégrations évaluées comme fausses (« falsy » en anglais) sont ignorées, vous pouvez donc les activer et les désactiver sans vous soucier des valeurs undefined et booléennes laissées de côté.

integrations: [
  // Exemple : Ignorer la création d’un plan de site sous Windows
  process.platform !== 'win32' && sitemap()
]

Mettre à niveau les intégrations

Pour mettre à niveau toutes les intégrations officielles simultanément, exécutez la commande @astrojs/upgrade. Cela permettra de mettre à niveau Astro et toutes les intégrations officielles vers leurs dernières versions.

Mise à niveau automatique

# Mettre à niveau Astro et les intégrations officielles simultanément vers la dernière version.
npx @astrojs/upgrade

# Mettre à niveau Astro et les intégrations officielles simultanément vers la dernière version.
pnpm dlx @astrojs/upgrade

# Mettre à niveau Astro et les intégrations officielles simultanément vers la dernière version.
yarn dlx @astrojs/upgrade

Mise à niveau manuelle

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

# Exemple : mise à niveau des intégrations React et Partytown
npm install @astrojs/react@latest @astrojs/partytown@latest

# Exemple : mise à niveau des intégrations React et Partytown
pnpm add @astrojs/react@latest @astrojs/partytown@latest

# Exemple : mise à niveau des intégrations React et Partytown
yarn add @astrojs/react@latest @astrojs/partytown@latest

Supprimer une intégration

Pour supprimer une intégration, commencez par la désinstaller de votre projet.
- npm
- pnpm
- Yarn
Fenêtre du terminal
npm uninstall @astrojs/react
Fenêtre du terminal
pnpm remove @astrojs/react
Fenêtre du terminal
yarn remove @astrojs/react

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

import { defineConfig } from 'astro/config';
import react from '@astrojs/react';

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

Trouver plus d’intégrations

Vous pouvez trouver 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.

Créer votre propre intégration

L’API des intégrations d’Astro s’inspire de Rollup et Vite, et est conçue pour être familière à tous ceux qui ont déjà écrit un module d’extension pour Rollup ou Vite.

Consultez la référence de l’API des intégrations pour découvrir ce que les intégrations peuvent faire et comment en créer une vous-même.

Publier votre intégration sur npm

Publier un composant Astro est un excellent moyen de réutiliser votre travail existant dans tous vos projets et de le partager avec la communauté d’Astro à grande échelle. Les composants Astro peuvent être publiés et installés directement depuis npm, comme n’importe quel autre paquet JavaScript.

En quête d’inspiration ? Découvrez quelques-uns de nos thèmes et composants préférés de la communauté d’Astro. Vous pouvez également effectuer une recherche sur npm pour consulter l’intégralité du catalogue public.

Démarrage rapide

Pour démarrer rapidement le développement de votre composant, vous pouvez utiliser un modèle déjà configuré pour vous.

# Initialiser le modèle de composant Astro dans un nouveau répertoire
npm create astro@latest mon-nouveau-repertoire-de-composants -- --template component

# Initialiser le modèle de composant Astro dans un nouveau répertoire
pnpm create astro@latest mon-nouveau-repertoire-de-composants -- --template component

# Initialiser le modèle de composant Astro dans un nouveau répertoire
yarn create astro mon-nouveau-repertoire-de-composants --template component

Créer un paquet

Pour créer un nouveau paquet, configurez votre environnement de développement afin d’utiliser des espaces de travail au sein de votre projet. Cela vous permettra de développer votre composant en parallèle d’une copie fonctionnelle d’Astro.

Répertoiremon-nouveau-repertoire-de-composants/
- Répertoiredemo/
  - … pour les tests et les démonstrations
- package.json
- Répertoirepaquets/
  - Répertoiremon-composant/
    index.js
    package.json
    … fichiers additionnels utilisés par le paquet

Cet exemple, nommé mon-projet, crée un projet avec un seul paquet, nommé mon-composant, et un répertoire demo/ pour les tests et les démonstrations du composant.

La configuration se fait dans le fichier package.json à la racine du projet :

{
  "name": "mon-projet",
  "workspaces": ["demo", "paquets/*"]
}

Dans cet exemple, plusieurs paquets peuvent être développés simultanément à partir du répertoire paquets. Ces paquets peuvent également être référencés depuis demo, où vous pouvez installer une copie fonctionnelle d’Astro.

npm create astro@latest demo -- --template minimal

pnpm create astro@latest demo -- --template minimal

yarn create astro demo --template minimal

Votre paquet individuel sera constitué de deux fichiers initiaux : package.json et index.js.

`package.json`

Le fichier package.json situé dans le répertoire du paquet contient toutes les informations relatives à votre paquet, notamment sa description, ses dépendances et toutes les autres métadonnées du paquet.

{
  "name": "mon-composant",
  "description": "Description du composant",
  "version": "1.0.0",
  "homepage": "https://github.com/utilisateur/projet#readme",
  "type": "module",
  "exports": {
    ".": "./index.js",
    "./astro": "./MonComposantAstro.astro",
    "./react": "./MonComposantReact.jsx"
  },
  "files": ["index.js", "MonComposantAstro.astro", "MonComposantReact.jsx"],
  "keywords": ["astro-component", "withastro", "... etc", "... etc"]
}

`description`

Une brève description de votre composant, utilisée pour aider les autres à comprendre son fonctionnement.

{
  "description": "Un générateur d'éléments Astro"
}

`type`

Le format de module utilisé par Node.js et Astro pour interpréter vos fichiers index.js.

{
  "type": "module"
}

Utilisez "type": "module" afin que votre fichier index.js puisse être utilisé comme point d’entrée avec import et export .

`homepage`

L’URL de la page d’accueil du projet.

{
  "homepage": "https://github.com/utilisateur/projet#readme"
}

C’est un excellent moyen de diriger les utilisateurs vers une démo en ligne, la documentation ou la page d’accueil de votre projet.

`exports`

Les points d’entrée d’un paquet lorsqu’il est importé par son nom.

{
  "exports": {
    ".": "./index.js",
    "./astro": "./MonComposantAstro.astro",
    "./react": "./MonComposantReact.jsx"
  }
}

Dans cet exemple, l’importation de mon-composant utiliserait index.js, tandis que l’importation de mon-composant/astro ou mon-composant/react utiliserait respectivement MonComposantAstro.astro ou MonComposantReact.jsx.

`files`

Une optimisation facultative permettant d’exclure les fichiers inutiles du paquet distribué aux utilisateurs via npm. Veuillez noter que seuls les fichiers listés ici seront inclus dans votre paquet. Par conséquent, si vous ajoutez ou modifiez des fichiers nécessaires au fonctionnement de votre paquet, vous devez mettre à jour cette liste en conséquence.

{
  "files": ["index.js", "MonComposantAstro.astro", "MonComposantReact.jsx"]
}

`keywords`

Une liste de mots clés pertinents pour votre composant, utilisée pour aider les autres à trouver votre composant sur npm et dans tous les autres catalogues de recherche.

Ajoutez astro-component, astro-integration ou withastro comme mot-clé spécial pour maximiser sa découvrabilité dans l’écosystème d’Astro.

{
  "keywords": ["astro-component", "withastro", "... etc", "... etc"]
}

`index.js`

Le principal point d’entrée du paquet utilisé lors de l’importation de votre paquet.

export { default as MonComposantAstro } from './MonComposantAstro.astro';
export { default as MonComposantReact } from './MonComposantReact.jsx';

Cela vous permet d’empaqueter plusieurs composants ensemble dans une seule interface.

Exemple : Utilisation des importations nommées

---
import { MonComposantAstro } from 'mon-composant';
import { MonComposantReact } from 'mon-composant';
---
<MonComposantAstro />
<MonComposantReact />

Exemple : Utilisation des importations d’espaces de noms

---
import * as Exemple from 'exemple-composant-astro';
---
<Exemple.MonComposantAstro />
<Exemple.MonComposantReact />

Exemple : Utilisation d’importations individuelles

---
import MonComposantAstro from 'exemple-composant-astro/astro';
import MonComposantReact from 'exemple-composant-astro/react';
---
<MonComposantAstro />
<MonComposantReact />

Développer votre paquet

Astro ne dispose pas d’un « mode paquet » dédié au développement. Vous devriez plutôt utiliser un projet de démonstration pour développer et tester votre paquet au sein de votre projet. Il peut s’agir d’un site web privé utilisé uniquement pour le développement, ou d’un site web public de démonstration/documentation pour votre paquet.

Si vous extrayez des composants d’un projet existant, vous pouvez même continuer à utiliser ce projet pour développer les composants que vous avez maintenant extraits.

Tester votre composant

Astro ne propose actuellement aucun exécuteur de tests. (Si vous souhaitez nous aider avec ça, rejoignez-nous sur Discord !)

En attendant, notre recommandation actuelle pour les tests est la suivante :

Ajoutez un répertoire fixtures de test à votre répertoire demo/src/pages.
Ajoutez une nouvelle page pour chaque test que vous souhaitez exécuter.
Chaque page devrait inclure les différents exemples d’utilisation de composants que vous souhaitez tester.
Exécutez astro build pour compiler vos fixtures, puis comparez le résultat du répertoire dist/__fixtures__/ à ce que vous attendiez.
- Répertoiremon-projet/demo/src/pages/__fixtures__/
  - nom-test-01.astro
  - nom-test-02.astro
  - nom-test-03.astro

Publier votre composant

Une fois que votre paquet est prêt, vous pouvez le publier sur npm à l’aide de la commande npm publish. Si cela ne fonctionne pas, assurez-vous de vous être connecté via npm login et que votre fichier package.json est correct. Si la publication réussit, c’est terminé !

Notez qu’aucune étape de compilation (build) n’a été nécessaire pour les paquets Astro. Tout type de fichier pris en charge nativement par Astro, comme .astro, .ts, .jsx et .css, peut être publié directement sans étape de compilation.

Si vous avez besoin d’un autre type de fichier qui n’est pas pris en charge nativement par Astro, ajoutez une étape de compilation à votre paquet. Cet exercice avancé est laissé à votre discrétion.

Bibliothèque des intégrations

Partagez le résultat de vos efforts en ajoutant votre intégration à notre bibliothèque d’intégrations !

Données du fichier `package.json`

La bibliothèque est automatiquement mise à jour chaque semaine, récupérant tous les paquets publiés sur npm avec le mot-clé astro-component, astro-integration ou withastro.

La bibliothèque des intégrations lit les données name, description, repository et homepage de votre fichier package.json.

Les avatars sont un excellent moyen de mettre en valeur votre marque dans la bibliothèque ! Une fois votre paquet publié, vous pouvez créer un ticket GitHub avec votre avatar en pièce jointe et nous l’ajouterons à votre fiche.

Catégories

En plus du mot-clé obligatoire astro-component, astro-integration ou withastro, des mots-clés spéciaux sont également utilisés pour organiser automatiquement les paquets. Inclure l’un des mots-clés ci-dessous ajoutera votre intégration à la catégorie correspondante dans notre bibliothèque d’intégrations.

Catégorie	Mots-clés
Accessibility (Accessibilité)	`a11y`, `accessibility`
Adapters (Adaptateurs)	`astro-adapter`
Analytics (Mesure d’audience)	`analytics`
CSS + UI	`css`, `ui`, `icon`, `icons`, `renderer`
Frameworks	`renderer`
Content Loaders (Chargeurs de contenu)	`astro-loader`
Images + Media	`media`, `image`, `images`, `video`, `audio`
Performance + SEO	`performance`, `perf`, `seo`, `optimization`
Dev Toolbar (Barre d’outils de dév)	`devtools`, `dev-overlay`, `dev-toolbar`
Utilities (Utilitaires)	`tooling`, `utils`, `utility`

Les paquets ne contenant aucun mot-clé correspondant à une catégorie seront affichés comme Uncategorized (non catégorisés).

Nous vous encourageons à partager votre travail, et nous adorons vraiment voir ce que nos talentueux Astronautes créent. Venez partager vos créations avec nous sur Discord ou mentionnez @astrodotbuild dans un tweet !

Contribuer Communauté Parrainer