Hydration React : définition et fonctionnement dans Next.js

Hydration React : la définition en clair

L'hydration (ou hydratation) est l'opération par laquelle React attache son JavaScript à un HTML déjà rendu par le serveur, pour le rendre interactif. Le serveur envoie une page complète, lisible tout de suite. Ensuite, dans le navigateur, React parcourt ce HTML existant, le compare à ce qu'il aurait lui-même produit, puis branche les clics, les saisies et l'état des composants.

L'image de l'eau aide à retenir le mot. Le serveur livre une page « sèche » : du contenu, mais aucune réaction quand on clique. Le JavaScript arrive ensuite et « hydrate » ce squelette pour lui donner vie. Rien n'est redessiné de zéro : React réutilise chaque DOM node déjà présent à l'écran.

Ce que l'hydration n'est pas

Ce n'est pas un second rendu complet de la page. Ce n'est pas non plus le server-side rendering lui-même, mais l'étape qui le suit. Pour bien situer les deux notions, notre article SSR vs CSR détaille la différence entre rendu côté serveur et rendu côté client.

À quoi sert l'hydration dans React ?

Elle sert à cumuler deux avantages qui, sans elle, s'opposent. D'un côté, le rendu serveur affiche vite un contenu que Google peut lire sans attendre le JavaScript. De l'autre, une application React offre des menus, des filtres et des formulaires réactifs. L'hydration fait le pont entre ce que le serveur prépare et ce que le client exécute.

Les bénéfices pour un site d'entreprise

• Un premier affichage rapide, même sur un mobile moyen ou un réseau lent.
• Un contenu présent dans le HTML initial, donc plus simple à indexer pour votre référencement.
• Une interactivité complète une fois le JavaScript chargé : panier, recherche, prise de rendez-vous.
• Un seul code React pour le serveur et le navigateur, ce qui limite les doublons.

Pour un dirigeant, l'enjeu est concret. Une page qui s'affiche vite retient le visiteur, et une page qui réagit au premier clic le convertit. Ce sont deux moments distincts, et l'hydration gouverne le second.

Comment fonctionne l'hydration, étape par étape

Le processus suit toujours le même ordre, que vous utilisiez React seul ou un framework comme Next.js. Comprendre cet ordre aide à repérer d'où vient un ralentissement.

1. Le serveur génère le HTML

Le serveur exécute vos composants et produit une chaîne HTML complète. On parle de server-rendered HTML. La page part vers le navigateur avec son texte, ses images et sa structure, mais sans aucun gestionnaire d'événement.

2. Le navigateur affiche la page

Le visiteur voit le contenu presque tout de suite. À ce stade, un bouton ressemble à un bouton, mais il ne fait rien. Le fichier JavaScript de l'application est encore en cours de téléchargement.

3. React prend le relais

Une fois le JavaScript chargé, React appelle la fonction hydrateRoot sur le conteneur de la page. Il rejoue le rendu en mémoire, vérifie que chaque élément correspond au DOM existant, puis attache les événements. Il ne recrée pas les nœuds : il les adopte. C'est ce qui rend l'opération plus légère qu'un rendu côté client complet.

4. La page devient interactive

Dès que l'hydration est finie, les clics fonctionnent et les hooks comme useEffect s'exécutent. Depuis React 18, l'hydration peut aussi être sélective : les zones enveloppées dans Suspense s'hydratent à part, et React traite en priorité celle sur laquelle l'utilisateur vient de cliquer.

Et dans Next.js, comment ça se passe ?

Next.js automatise tout ce mécanisme. Vous n'écrivez pas hydrateRoot vous-même : le framework rend la page sur le serveur, l'envoie, puis l'hydrate dans le navigateur. Le développeur se concentre sur ses composants.

Avec l'App Router, une nuance change beaucoup de choses. Les Server Components s'exécutent seulement sur le serveur et n'envoient pas leur code au navigateur, donc ils ne sont pas hydratés. Seuls les composants marqués « use client » le sont. Moins il y a de composants clients, moins le navigateur a de JavaScript à télécharger et à exécuter.

Les erreurs courantes avec l'hydration React

La plupart des problèmes viennent d'un écart entre ce que rend le serveur et ce que rend le client. Si le HTML ne correspond pas, React le signale avec un message du type « Hydration failed because the server rendered HTML didn't match the client ». Il peut alors jeter le HTML du serveur et tout refaire côté client, ce qui annule le gain de vitesse.

Les causes de décalage les plus fréquentes

• Une date ou une heure calculée au rendu : le serveur et le navigateur n'ont pas la même horloge ni le même fuseau.
• Une valeur aléatoire, comme Math.random(), qui change d'un rendu à l'autre.
• Un test sur window ou localStorage dans le rendu, alors que ces objets n'existent que dans le navigateur.
• Un HTML invalide, par exemple une balise p dans une autre balise p, que le navigateur corrige à sa façon.
• Une extension de navigateur qui modifie la page avant que React ne s'hydrate.

Le remède habituel consiste à déplacer le code propre au navigateur dans un useEffect, qui ne s'exécute qu'après l'hydration. Pour un écart assumé et minime, comme un horodatage, l'attribut suppressHydrationWarning masque l'alerte sur un seul élément. Il ne faut pas s'en servir pour cacher un vrai bug.

Le piège de la page visible mais figée

Autre erreur, moins visible : envoyer trop de JavaScript. La page s'affiche, mais le bouton ne répond pas pendant plusieurs secondes, le temps que l'hydration se termine. Le visiteur clique, rien ne se passe, il repart. Ce délai pèse sur l'INP, l'un des Core Web Vitals suivis par Google. Le code splitting et la réduction des composants clients sont les premiers leviers, détaillés dans notre guide pour améliorer l'INP.

Faut-il s'en soucier pour votre site ?

Si votre site tourne sur React ou Next.js, oui, même sans toucher au code. L'hydration influe sur la vitesse ressentie, sur les conversions et sur la façon dont Google évalue vos pages. Lors d'une création de site internet, c'est un point à aborder avec votre prestataire : quelles parties ont vraiment besoin d'être interactives, et lesquelles peuvent rester du simple HTML.

Questions fréquentes