Configurer Astro et les îlots React

Pour initialiser un projet Astro, utilisez npx create astro@latest, qui lance un assistant interactif permettant de choisir un modèle, les paramètres TypeScript et un gestionnaire de paquets. Astro prend en charge plusieurs modèles de départ, notamment un modèle vierge, un modèle de blog et des modèles de documentation.

Les intégrations Astro ajoutent la prise en charge d’un framework à un projet. L’exécution de npx astro add react installe automatiquement @astrojs/react, react et react-dom, puis met à jour astro.config.mjs pour inclure l’intégration React. Toute la configuration s’effectue avec une seule commande.

Un fichier .astro est le format de composant d’Astro. Il se compose d’une section de préambule (du JavaScript située entre des délimiteurs ---) et d’une section de modèle. Par défaut, un fichier Astro produit du HTML statique : aucun JavaScript n’est envoyé au navigateur, sauf si vous ajoutez explicitement une directive client.

L’importation d’un composant React dans un fichier Astro utilise la syntaxe standard des modules ES : import Counter from './Counter.jsx'. Sans directive client, Astro effectue le rendu côté serveur du composant React sous forme de HTML statique et envoie ce HTML au navigateur : aucun JavaScript n’est envoyé pour ce composant.

Ajouter client:visible à la balise du composant dans le modèle Astro le transforme en îlot : <Counter client:visible />. Astro envoie alors le JavaScript de Counter, l’hydrate lorsqu’il entre dans la zone visible et le rend interactif. Sans cette directive, il s’agit de HTML statique.

Les composants React utilisés comme îlots Astro sont écrits en React standard : ils utilisent des crochets, un état, des effets et n’importe quelle bibliothèque React. L’intérieur du composant React lui-même ne contient aucune API propre à Astro. La frontière de l’îlot est définie dans le modèle Astro, et non dans le code du composant.

Chaque instance d’îlot constitue une arborescence React indépendante. Deux îlots Counter présents sur la même page ne partagent pas leur état. Si vous avez besoin d’un état partagé, trois options s’offrent à vous : les regrouper dans un seul îlot, utiliser les paramètres de recherche de l’URL pour un état sérialisable ou utiliser une bibliothèque d’état partagé comme nanostores.

La bibliothèque @nanostores/react fournit des atomes légers auxquels n’importe quel îlot peut s’abonner. Un îlot écrit dans un atome de nano-magasin et un autre îlot le lit. Comme les nano-magasins sont indépendants du framework, ce modèle fonctionne également entre des îlots React et Vue présents sur la même page.

Les collections de contenu Astro offrent une manière sûre du point de vue des types de gérer des fichiers Markdown et MDX. Définissez le schéma d’une collection avec Zod, placez les fichiers Markdown dans src/content/, et Astro génère des fonctions de requête entièrement typées. Il s’agit du modèle standard pour les articles de blog, la documentation et les pages de produit.

L’exécution de astro build génère un dossier dist/ contenant des fichiers HTML statiques. Pour chaque page, Astro produit un fichier HTML avec le contenu rendu côté serveur et uniquement les paquets JavaScript nécessaires aux îlots de cette page. Les pages qui ne contiennent aucun îlot ne produisent aucun JavaScript.

La sortie statique peut être déployée sur n’importe quel CDN (Netlify, Vercel, Cloudflare Pages), sans serveur. Pour les besoins de rendu côté serveur (routes dynamiques, points d’accès d’API), Astro prend en charge des adaptateurs SSR pour Node.js, Vercel Edge, Cloudflare Workers et Deno. Les îlots fonctionnent de la même manière dans les deux modes.

Quelle modification minimale faut-il apporter à un composant React importé dans un modèle Astro pour le rendre interactif côté client ?

Configurez Astro avec React à l’aide de npx astro add react. Les fichiers Astro sont statiques par défaut ; l’ajout d’une directive client: à la balise d’un composant React le transforme en îlot hydraté. Les composants React sont du React standard, sans API propre à Astro. L’état est isolé par îlot ; nanostores permet la communication entre les îlots. La construction produit du HTML statique avec uniquement le JavaScript nécessaire aux îlots.