@astrojs/ react

Cette intégration Astro permet le rendu côté serveur et l’hydratation côté client pour vos composants React.

Installation

Astro inclut une commande astro add pour automatiser l’installation des intégrations officielles. Si vous préférez, vous pouvez installer les intégrations manuellement à la place.

Pour installer @astrojs/react, exécutez ce qui suit depuis le répertoire de votre projet et suivez les instructions :

npx astro add react

pnpm astro add react

yarn astro add react

Si vous rencontrez des problèmes, n’hésitez pas à nous les signaler sur GitHub et essayez les étapes d’installation manuelle ci-dessous.

Installation manuelle

Tout d’abord, installez le paquet @astrojs/react :

npm install @astrojs/react

pnpm add @astrojs/react

yarn add @astrojs/react

La plupart des gestionnaires de paquets installent également les dépendances associées. Si vous voyez un avertissement “Cannot find package ‘react’” (ou similaire) lorsque vous démarrez Astro, vous devrez installer react et react-dom :

npm install react react-dom

pnpm add react react-dom

yarn add react react-dom

Ensuite, appliquez l’intégration à votre fichier astro.config.* en utilisant la propriété integrations :

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

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

Démarrage

Pour utiliser votre premier composant React dans Astro, dirigez-vous vers notre documentation sur les frameworks UI. Vous y découvrirez :

📦 comment les composants du cadre sont chargés,
💧 les options d’hydratation côté client, et
🤝 les possibilités de mélanger et d’imbriquer les cadres.

Options

Combinaison de plusieurs frameworks JSX

Lorsque vous utilisez plusieurs frameworks JSX (React, Preact, Solid) dans le même projet, Astro doit déterminer quelles transformations spécifiques au framework JSX doivent être utilisées pour chacun de vos composants. Si vous n’avez ajouté qu’une seule intégration de framework JSX à votre projet, aucune configuration supplémentaire n’est nécessaire.

Utilisez les options de configuration include (obligatoire) et exclude (optionnelle) pour spécifier quels fichiers appartiennent à quel framework. Fournissez un tableau de fichiers et/ou de dossiers à inclure pour chaque framework que vous utilisez. Des caractères joker peuvent être utilisés pour inclure plusieurs chemins de fichiers.

Nous recommandons de placer les composants communs du framework dans le même dossier (par exemple /composants/react/ et /composants/solid/) pour faciliter la spécification de vos inclusions, mais ce n’est pas obligatoire :

import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';
import react from '@astrojs/react';
import svelte from '@astrojs/svelte';
import vue from '@astrojs/vue';
import solid from '@astrojs/solid-js';

export default defineConfig({
  // Permettre à de nombreux frameworks de prendre en charge tous les différents types de composants.
  // Aucun `include` n'est nécessaire si vous n'utilisez qu'un seul framework JSX !
  integrations: [
    preact({
      include: ['**/preact/*'],
    }),
    react({
      include: ['**/react/*'],
    }),
    solid({
      include: ['**/solid/*'],
    }),
  ],
});

Traitement des éléments enfants (Children parsing)

Les enfants passés dans un composant React depuis un composant Astro sont analysés comme des chaînes simples, et non comme des nœuds React.

Par exemple, le <ReactComponent /> ci-dessous ne recevra qu’un seul élément enfant :

---
import ReactComponent from './ReactComponent';
---

<ReactComponent>
  <div>un</div>
  <div>deux</div>
</ReactComponent>

Si vous utilisez une bibliothèque qui attend que plus d’un élément enfant soit passé, par exemple pour qu’elle puisse placer certains éléments à différents endroits, vous pourriez trouver cela bloquant.

Vous pouvez définir le drapeau expérimental experimentalReactChildren pour dire à Astro de toujours passer les enfants à React en tant que nœuds DOM virtuels React. Il y a un coût d’exécution à cela, mais cela peut aider à la compatibilité.

Vous pouvez activer cette option dans la configuration de l’intégration de React :

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

export default defineConfig({
  // ...
  integrations: [
    react({
      experimentalReactChildren: true,
    }),
  ],
});