Next.js

Erreur d’hydratation Next.js : corriger les dates et localStorage

Othmane Ibn Dahou Idrissi ·

Trois étapes de l’hydratation : HTML serveur, premier rendu cohérent, puis interaction dans le navigateur.

Une page Next.js s’affiche correctement, puis la console annonce que le HTML du serveur ne correspond pas au premier rendu du navigateur. Le problème apparaît parfois uniquement chez un collègue, sur un téléphone ou après un changement de fuseau horaire. Dans ces situations, ajouter suppressHydrationWarning partout masque le diagnostic et laisse subsister une interface dont l’état initial est incohérent.

Ce guide propose une méthode pour les applications App Router de Next.js 16 avec React 19. Les exemples concernent des dates et une préférence stockée dans localStorage. Ils sont illustratifs et ne supposent aucune donnée utilisateur réelle. L’objectif est de rendre le premier affichage déterministe, puis de personnaliser l’interface lorsque le navigateur dispose des informations nécessaires.

Comprendre les deux rendus qui doivent se rejoindre

Lors d’un chargement initial, le serveur produit du HTML. Le navigateur reçoit ensuite le JavaScript nécessaire pour rendre les composants interactifs. L’hydratation associe ce comportement au document existant. Si le texte ou la structure attendue diffère dès cette étape, React signale une incompatibilité. Les causes documentées par Next.js incluent les dates, les API navigateur et les imbrications HTML invalides.

Une directive use client ne dispense pas de cette cohérence. Elle définit une frontière de modules, pas une promesse de rendu exclusivement dans le navigateur. Si cette distinction reste floue, commencez par le guide sur Server Components et Client Components.

Le bon réflexe consiste à comparer trois choses : la donnée d’entrée, le HTML reçu et le premier état React. La date dans la base peut être correcte tandis que son formatage varie. Le thème sauvegardé peut être valide mais inconnu du serveur. Ces deux problèmes appellent des décisions de produit différentes.

Diagnostiquer avant de changer le composant

Ouvrez d’abord la route directement, sans passer par une navigation interne. Reproduisez avec une fenêtre privée, puis avec une préférence déjà enregistrée. Une navigation côté client peut contourner le chemin de chargement qui révèle l’erreur ; elle n’est donc pas une vérification suffisante.

Réduisez ensuite la zone concernée. Remplacez provisoirement le texte variable par une chaîne fixe. Si l’avertissement disparaît, inspectez sa fabrication : locale implicite, heure courante, nombre aléatoire ou stockage navigateur. Si l’erreur persiste, vérifiez les balises imbriquées et les composants parents avant d’accuser les données.

Enfin, reproduisez sur un build de production et dans un navigateur sans extension. Une extension peut modifier le DOM avant React ; cette observation ne justifie pas d’ignorer une erreur présente également dans un environnement propre. Notez le scénario exact dans le ticket afin que la correction puisse être vérifiée par une autre personne.

Dates : choisir une sémantique avant un format

Une date de publication et une heure de rendez-vous n’ont pas le même sens. Pour un article, on peut afficher une date éditoriale stable. Pour une réunion, le fuseau de l’utilisateur peut être important. Le premier cas permet un format commun ; le second demande une personnalisation explicitement organisée.

Voici un formatage déterministe d’un instant connu, destiné à un affichage éditorial en UTC. Il ne faut pas remplacer l’entrée par new Date() pendant chaque rendu : le moment de génération changerait entre serveur et navigateur.

const formatter = new Intl.DateTimeFormat('fr-FR', {
  dateStyle: 'long',
  timeZone: 'UTC',
});

export function PublicationDate({ iso }: { iso: string }) {
  const date = new Date(iso);
  if (Number.isNaN(date.getTime())) return null;

  return <time dateTime={iso}>{formatter.format(date)}</time>;
}

Le fuseau UTC est ici une convention éditoriale, pas une recommandation universelle. Pour une activité au Maroc, une règle métier peut demander Africa/Casablanca. Évitez un décalage numérique fixe si la règle correspond à une zone géographique. Documentez également le format accepté à l’entrée : une chaîne sans fuseau ne décrit pas toujours le même instant selon son interprétation.

Si vous devez afficher l’heure locale du visiteur, rendez d’abord une valeur stable, par exemple l’heure de référence avec son fuseau. Après montage, remplacez-la par la version locale et indiquez clairement sa signification. Réservez une place suffisante pour éviter un déplacement brutal du contenu. Le choix est autant éditorial que technique.

localStorage : conserver la même première valeur

Le serveur ne lit pas le stockage du navigateur. Initialiser un état avec localStorage.getItem() dans le rendu provoque donc soit une erreur d’accès, soit une divergence si l’on ajoute une branche typeof window. Le test d’existence de window ne rend pas les deux résultats identiques.

Pour une petite préférence d’affichage, une valeur initiale neutre puis une lecture dans un effet est une solution explicite. L’exemple suivant affiche la préférence et permet de la changer. Il supporte également un stockage indisponible ; il ne synchronise volontairement pas plusieurs onglets.

'use client';

import { useEffect, useState } from 'react';

export default function DisplayPreference() {
  const [compact, setCompact] = useState(false);
  const [ready, setReady] = useState(false);

  useEffect(() => {
    try {
      setCompact(localStorage.getItem('compact-view') === 'yes');
    } catch {
      // La préférence par défaut reste utilisable.
    }
    setReady(true);
  }, []);

  function toggle() {
    const next = !compact;
    setCompact(next);
    try {
      localStorage.setItem('compact-view', next ? 'yes' : 'no');
    } catch {
      // Le changement reste actif pour cette visite.
    }
  }

  return (
    <button disabled={!ready} aria-pressed={compact} onClick={toggle}>
      Affichage compact
    </button>
  );
}

Le bouton désactivé a le même état initial des deux côtés. Une fois la préférence connue, il devient utilisable. Cette transition implique un rendu supplémentaire ; pour un thème global, on peut préférer une préférence conservée dans un cookie lisible par le serveur. Cela demande alors de définir sa durée, ses valeurs autorisées et son effet sur le cache.

Pour un stockage partagé plus complexe, useSyncExternalStore fournit un contrat de souscription avec un instantané serveur. Cet instantané doit rester identique pendant l’hydratation. Ce hook ne résout pas magiquement une différence entre deux données initiales ; il aide à formaliser leur synchronisation.

Les corrections qui déplacent le problème

Supprimer le rendu serveur de toute une page peut éliminer l’avertissement tout en retardant son contenu. Cette approche se justifie parfois pour un widget entièrement dépendant du navigateur, mais elle doit rester proportionnée. Un titre d’article ou une fiche produit ne devrait pas disparaître du HTML initial pour contourner une date mal formatée.

De même, attendre le montage pour afficher toute l’application introduit un écran vide inutile. Localisez la personnalisation. Une préférence secondaire peut évoluer après l’hydratation sans empêcher les titres, les liens et le contenu principal d’être immédiatement disponibles.

Enfin, suppressHydrationWarning est une échappatoire limitée, pas un mécanisme de synchronisation. Si vous l’utilisez sur une différence intentionnelle, expliquez-la dans le code et vérifiez le comportement réel. Ne l’ajoutez pas sur un conteneur global en espérant réparer les interactions de ses descendants.

Un protocole de vérification reproductible

Préparez une matrice simple : stockage vide ou existant, navigation directe ou interne, deux fuseaux horaires, JavaScript disponible ou retardé. Utilisez la même donnée ISO dans chaque scénario. Comparez l’affichage initial et l’affichage stabilisé, sans vous limiter à l’absence d’avertissement.

Testez également une valeur stockée invalide et un refus d’accès au stockage. La page doit conserver une valeur par défaut acceptable. Si votre préférence influence une requête serveur, vérifiez qu’elle ne provoque pas une réponse privée partagée avec d’autres visiteurs ; ce point rejoint la gestion du cache d’un CMS Next.js.

Pour terminer, contrôlez le clavier et les technologies d’assistance. Une modification de texte ou de contrôle après montage peut être techniquement cohérente mais déroutante. Le guide sur les formulaires React accessibles montre comment rendre ces états compréhensibles.

Questions fréquentes

Pourquoi l’erreur apparaît-elle uniquement sur certains appareils ?

Une locale, un fuseau, une extension ou une préférence enregistrée peut varier. Reproduisez ces paramètres au lieu de supposer que le serveur renvoie des données différentes. Conservez un exemple d’entrée identique pour isoler le formatage.

Faut-il toujours utiliser un effet ?

Non. Si le serveur connaît la valeur correcte, transmettez-la et rendez-la directement. Un effet convient lorsque l’information dépend réellement du navigateur. Une donnée métier devrait avoir une source définie, pas être recalculée différemment à chaque extrémité.

Une erreur d’hydratation bloque-t-elle forcément Google ?

Pas systématiquement. Il faut examiner le contenu accessible, les erreurs de rendu et les règles d’indexation. Le diagnostic doit partir du document livré, sans transformer un avertissement React en conclusion SEO automatique. Pour situer ces sujets dans mon travail, consultez mon parcours professionnel.

Next.jsReactHydratationDébogage