API et paramètres de useSyncExternalStore

useSyncExternalStore accepte jusqu’à trois arguments : la fonction d’abonnement, getSnapshot et un getServerSnapshot facultatif. Ensemble, ils indiquent à React comment écouter les changements et comment lire la valeur actuelle.

Il est essentiel de comprendre chaque argument, car de petites erreurs dans ceux-ci constituent la source la plus fréquente de bogues lors de l’utilisation de ce crochet.

La fonction d’abonnement reçoit une fonction de rappel de React et doit l’enregistrer auprès de la source d’état afin qu’elle s’exécute chaque fois que la source d’état change. Elle doit renvoyer une fonction de désabonnement que React appelle lors du nettoyage.

React s’en sert pour savoir quand relire l’instantané. La fonction d’abonnement sert donc uniquement à mettre en place puis à retirer la notification des changements.

getSnapshot renvoie la valeur actuelle de la source d’état. React l’appelle pendant le rendu pour lire l’état, puis de nouveau après les notifications afin de détecter si la valeur a changé.

Point essentiel, il doit renvoyer un résultat stable par référence lorsque les données sous-jacentes n’ont pas changé : il doit renvoyer la même référence plutôt qu’un nouvel objet à chaque appel.

Le getServerSnapshot facultatif fournit la valeur utilisée lors du rendu côté serveur et de la première phase d’hydratation. Il est nécessaire, car getSnapshot, réservé au navigateur, peut dépendre d’API qui n’existent pas sur le serveur.

Le fournir évite les incohérences d’hydratation en donnant au serveur une valeur pertinente à afficher, correspondant à ce que le client produira initialement.

Le crochet renvoie la valeur de l’instantané actuel, que vous utilisez directement dans votre composant comme n’importe quel autre élément d’état. Lorsque la source d’état change, React effectue un nouveau rendu et le crochet renvoie l’instantané mis à jour.

Du point de vue du composant, cela ressemble à la lecture d’un état réactif, même si la source de vérité se trouve entièrement en dehors de React.

getSnapshot doit s’exécuter de manière synchrone et renvoyer une valeur dérivée uniquement de l’état actuel de la source d’état. Il ne doit effectuer aucun travail asynchrone ni produire des résultats différents pour les mêmes données sous-jacentes.

React s’appuie sur des appels répétés et sur la comparaison des résultats. Tout comportement non déterministe ou effet secondaire à l’intérieur de cette fonction peut donc entraîner un fonctionnement incorrect.

Les sources d’état qui contiennent un état immuable simplifient getSnapshot, car la référence de l’objet d’état actuel ne change que lorsque les données changent. Renvoyer cette référence fournit gratuitement des comparaisons stables.

C’est pourquoi les modèles de mise à jour immuable s’accordent si bien avec le crochet : des données identiques signifient une référence identique, et React évite les nouveaux rendus inutiles.

Une erreur fréquente consiste à renvoyer un objet ou un tableau entièrement nouveau à chaque appel de getSnapshot, par exemple en y effectuant une transformation ou un filtrage. React voit une nouvelle référence à chaque fois et pense que la valeur a changé.

Cela déclenche des rendus incessants ou des avertissements. Pour corriger le problème, mettez en cache la valeur dérivée et renvoyez la même référence jusqu’à ce que les données sources changent réellement.

Pour éviter la boucle, calculez les données dérivées en dehors de getSnapshot ou mémorisez-les afin que la fonction renvoie une référence mise en cache. Le modèle fondé sur un sélecteur, utilisé par de nombreuses bibliothèques, sert précisément à gérer cette stabilité.

La règle directrice est que deux appels à getSnapshot avec des données de la source d’état inchangées doivent renvoyer exactement la même référence.

En pratique, vous écrivez une fonction d’abonnement qui ajoute et retire un écouteur, un getSnapshot qui lit une valeur actuelle stable et, pour SSR, un getServerSnapshot qui renvoie une valeur compatible avec le serveur.

Lorsque ces trois éléments sont corrects, le crochet fournit des lectures cohérentes et sûres en contexte concurrent de votre source d’état externe, avec très peu de code superflu.

Identifiez le rôle de getSnapshot.

Le crochet accepte la fonction d’abonnement, getSnapshot et, facultativement, getServerSnapshot. La fonction d’abonnement configure un écouteur et renvoie une fonction de désabonnement ; getSnapshot lit la valeur actuelle de manière synchrone et doit être stable par référence ; getServerSnapshot fournit une valeur compatible avec SSR.

Le piège classique consiste à renvoyer un nouvel objet à chaque appel, ce qui provoque des boucles infinies. Mettez les valeurs dérivées en cache afin que des données inchangées produisent la même référence.