Astro : interactivité et intégrations

Astro n’envoie aucun JavaScript par défaut. L’interactivité s’ajoute composant par composant (îlots).

Ajouter une intégration

npx astro add react
npx astro add sitemap
npx astro add mdx

astro add installe les paquets et modifie astro.config.mjs. Vérifier le diff (git diff) avant de valider.

Un composant React dans une page Astro

npx astro add react

src/components/Compteur.jsx :

import { useState } from 'react';

export default function Compteur({ depart = 0 }) {
  const [n, setN] = useState(depart);
  return <button onClick={() => setN(n + 1)}>Cliqué {n} fois</button>;
}

---
import Compteur from '../components/Compteur.jsx';
---

<Compteur client:visible depart={5} />

Sans directive client:*, le composant est rendu en HTML statique sans interactivité.

Directives client

Directive	Quand le JavaScript est chargé
`client:load`	Dès le chargement de la page
`client:idle`	Quand le navigateur est inactif
`client:visible`	Quand le composant entre dans l’écran
`client:media="(max-width: 600px)"`	Quand la requête média correspond
`client:only="react"`	Rendu uniquement côté navigateur (pas de HTML serveur)

Choisir la plus tardive possible : client:visible pour les éléments sous la ligne de flottaison, client:idle pour le secondaire, client:load pour l’essentiel (menu, formulaire principal).

Autres frameworks

Astro prend en charge React, Vue, Svelte, Solid et Preact. Plusieurs peuvent cohabiter dans un même projet. Pour de petites interactions (menu, bouton de thème), un <script> dans un composant .astro est plus léger qu’un framework (voir Composants et layouts).

Partager un état entre îlots

Les îlots sont indépendants : pas de contexte React partagé entre eux. Utiliser un stockage léger commun, par exemple Nano Stores :

npm install nanostores @nanostores/react

import { atom } from 'nanostores';
export const nombreArticles = atom(0);

import { useStore } from '@nanostores/react';
import { nombreArticles } from '../stores/panier';

export function Badge() {
  return <span>{useStore(nombreArticles)}</span>;
}

Transitions de page

---
import { ClientRouter } from 'astro:transitions';
---

<head>
  <ClientRouter />
</head>

ClientRouter remplace les rechargements de page par des transitions animées (navigation côté client). Contraintes :

Les scripts de page ne se ré-exécutent pas à chaque navigation : écouter l’événement astro:page-load pour initialiser.
Les pages hors du routeur (par exemple une documentation dans un autre outil) restent de vrais chargements : leurs liens peuvent s’ouvrir avec target="_blank" ou data-astro-reload.

document.addEventListener('astro:page-load', () => {
  // (ré)initialiser les écouteurs d'événements ici
});

Directives utiles : transition:name, transition:animate, transition:persist (conserve un élément et son état entre deux pages).

Intégrations courantes

Intégration	Commande	Usage
Sitemap	`npx astro add sitemap`	Génère `sitemap-index.xml` (nécessite `site`)
MDX	`npx astro add mdx`	Composants dans le Markdown
React, Vue, Svelte	`npx astro add react`	Composants interactifs
Tailwind	Plugin Vite `@tailwindcss/vite` (voir Tailwind : installation)	Styles utilitaires
Node (adaptateur)	`npx astro add node`	Rendu à la demande (voir Rendu et déploiement)
Starlight	`npm create astro@latest -- --template starlight`	Site de documentation

Dépannage

Symptôme	Piste
Le composant React est affiché mais inerte	Directive `client:*` manquante
`window is not defined` à la compilation	Code navigateur exécuté côté serveur : utiliser `client:only` ou un `useEffect`
Le script ne fonctionne qu’à la première page	`ClientRouter` : utiliser `astro:page-load`
L’état n’est pas partagé entre deux composants	Îlots indépendants : store partagé
Erreur d’hydratation	Le HTML serveur diffère du rendu client (date, valeur aléatoire)
`astro add` échoue	Dépendances pas à jour : `npm install`, puis relancer