useSyncExternalStore in React: iscriversi a dati esterni

useSyncExternalStore iscrive un componente a dati che vivono al di fuori di React e lo renderizza di nuovo ogni volta che quei dati cambiano. Gli dai due funzioni: subscribe, che dice a React come ascoltare i cambiamenti, e getSnapshot, che restituisce il valore attuale.

import { useSyncExternalStore } from 'react';

// A tiny store that lives outside React
let count = 0;
const listeners = new Set();

const counterStore = {
    increment() {
        count += 1;
        listeners.forEach((listener) => listener());
    },
    subscribe(listener) {
        listeners.add(listener);
        return () => listeners.delete(listener);
    },
    getSnapshot() {
        return count;
    },
};

function Display({ name }) {
    const value = useSyncExternalStore(counterStore.subscribe, counterStore.getSnapshot);
    console.log(name, 'rendered with', value);
    return <p>{name} sees {value}</p>;
}

export default function App() {
    return (
        <div>
            <Display name="Header" />
            <Display name="Footer" />
            <button onClick={counterStore.increment}>Increment the store</button>
        </div>
    );
}

I due componenti Display non condividono props né context, eppure si aggiornano insieme, perché entrambi sono iscritti allo stesso store. Il pulsante chiama una semplice funzione, non un setter di React. Aggiungi un terzo <Display name="Sidebar" /> e si unisce agli altri senza alcuna altra modifica.

La sintassi

const value = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot?);

• subscribe(callback) inizia ad ascoltare, chiama callback ogni volta che i dati potrebbero essere cambiati e restituisce una funzione per annullare l'iscrizione. React la chiama dopo il montaggio del componente e chiama la funzione restituita allo smontaggio.
• getSnapshot() restituisce il valore attuale. React la chiama a ogni rendering e dopo ogni notifica, poi confronta il risultato con l'ultimo usando Object.is. Stesso valore, nessun rendering.
• getServerSnapshot() (facoltativa) restituisce il valore da usare sul server e durante l'hydration.

Definisci subscribe fuori dal componente, oppure mantienila stabile con useCallback. Se passi una nuova funzione subscribe a ogni rendering, React annulla l'iscrizione e si iscrive di nuovo ogni volta.

API del browser come store

Qualsiasi cosa che abbia un valore attuale e generi un evento quando il valore cambia si adatta a questa forma. navigator.onLine con gli eventi online e offline è il caso classico.

import { useSyncExternalStore } from 'react';

function subscribe(callback) {
    window.addEventListener('online', callback);
    window.addEventListener('offline', callback);
    console.log('subscribed to online/offline');
    return () => {
        window.removeEventListener('online', callback);
        window.removeEventListener('offline', callback);
    };
}

function useOnlineStatus() {
    return useSyncExternalStore(
        subscribe,
        () => navigator.onLine,
        () => true
    );
}

export default function App() {
    const online = useOnlineStatus();
    return (
        <p style={{ color: online ? '#1a7f37' : '#c0392b' }}>
            {online ? 'You are online' : 'You are offline: changes will sync later'}
        </p>
    );
}

Disattiva la rete (o passa a Offline negli strumenti per sviluppatori del browser) e il testo cambia senza ricaricare. Il terzo argomento dice "considera la connessione attiva" durante il rendering sul server, dove non c'è alcun navigator. Racchiudere la chiamata all'hook in useOnlineStatus lo rende un hook personalizzato che qualsiasi componente può usare.

La larghezza della finestra funziona allo stesso modo:

import { useSyncExternalStore, useState } from 'react';

function subscribe(callback) {
    window.addEventListener('resize', callback);
    return () => window.removeEventListener('resize', callback);
}

function useWindowWidth() {
    return useSyncExternalStore(subscribe, () => window.innerWidth, () => 1024);
}

function Layout() {
    const width = useWindowWidth();
    return <p>{width}px: {width < 600 ? 'one column' : 'two columns'}</p>;
}

export default function App() {
    const [copies, setCopies] = useState(1);
    return (
        <div>
            <button onClick={() => setCopies(copies + 1)}>Add a copy</button>
            {Array.from({ length: copies }, (_, i) => (
                <Layout key={i} />
            ))}
        </div>
    );
}

Aggiungi qualche copia e ridimensiona la finestra: ogni copia mostra lo stesso numero nello stesso momento. Ogni copia ha il proprio listener, e ognuna legge la larghezza durante il rendering, quindi nessuna è mai indietro di un frame.

getSnapshot deve restituire un valore in cache

React chiama getSnapshot spesso e confronta i risultati per riferimento. Una funzione che costruisce un nuovo oggetto o array a ogni chiamata sembra sempre un cambiamento:

// Broken: a new object on every call
function getSnapshot() {
    return { count: store.count, user: store.user };
}

// Also broken: filter returns a new array every time
function getSnapshot() {
    return store.todos.filter((t) => !t.done);
}

React esegue il rendering, chiama getSnapshot, ottiene un valore "diverso", esegue di nuovo il rendering, e così via, finché non si ferma con "Maximum update depth exceeded". In sviluppo React prima registra anche "The result of getSnapshot should be cached to avoid an infinite loop". Una build di produzione, come l'anteprima qui, salta quell'avviso e segnala solo l'errore finale come breve codice (Minified React error #185).

La soluzione è mantenere i dati immutabili nello store: sostituisci l'oggetto quando cambia, e restituisci il riferimento memorizzato così com'è.

import { useSyncExternalStore } from 'react';

let state = { todos: [{ id: 1, text: 'Write docs', done: false }] };
const listeners = new Set();

const todoStore = {
    add(text) {
        state = { ...state, todos: [...state.todos, { id: Date.now(), text, done: false }] };
        listeners.forEach((l) => l());
    },
    subscribe(listener) {
        listeners.add(listener);
        return () => listeners.delete(listener);
    },
    getSnapshot() {
        return state;
    },
};

export default function App() {
    const { todos } = useSyncExternalStore(todoStore.subscribe, todoStore.getSnapshot);
    const open = todos.filter((t) => !t.done);
    console.log('render,', todos.length, 'todos');
    return (
        <div>
            <button onClick={() => todoStore.add('Another task')}>Add task</button>
            <ul>
                {open.map((t) => (
                    <li key={t.id}>{t.text}</li>
                ))}
            </ul>
        </div>
    );
}

getSnapshot restituisce lo stesso oggetto state finché add non lo sostituisce, quindi il componente si renderizza una volta per ogni modifica. Il filtraggio avviene nel componente, dopo che lo snapshot è stato letto, il che è sicuro. Per filtrare invece dentro lo store, calcola l'array filtrato quando i dati cambiano e memorizzalo, così getSnapshot può restituire la copia memorizzata.

getServerSnapshot e hydration

Sul server non ci sono finestra, navigator né sottoscrizioni. Il terzo argomento dice a React cosa renderizzare lì:

const width = useSyncExternalStore(
    subscribe,
    () => window.innerWidth, // in the browser
    () => 1024 // on the server, and during hydration
);

React usa getServerSnapshot anche per il primo rendering nel browser quando idrata l'HTML del server, così i due coincidono. Subito dopo l'hydration legge getSnapshot e, se il valore reale è diverso, esegue un nuovo render con esso. Senza il terzo argomento, il rendering sul server genera "Missing getServerSnapshot, which is required for server-rendered content. Will revert to client rendering.". Se sopra il componente c'è un confine <Suspense>, il server invia il fallback di quel confine e il browser renderizza invece il suo contenuto; senza alcun confine, il rendering sul server fallisce.

useSyncExternalStore vs useEffect e useState

Puoi iscriverti con un effetto:

function useOnlineStatus() {
    const [online, setOnline] = useState(true);
    useEffect(() => {
        const update = () => setOnline(navigator.onLine);
        update();
        window.addEventListener('online', update);
        window.addEventListener('offline', update);
        return () => {
            window.removeEventListener('online', update);
            window.removeEventListener('offline', update);
        };
    }, []);
    return online;
}

Funziona, con due punti deboli. Il primo rendering mostra sempre la stima iniziale, e il valore reale arriva un rendering dopo, quando l'effetto viene eseguito. E con il rendering concorrente (durante una transizione, per esempio), React può mettere in pausa un rendering a metà; se lo store cambia durante la pausa, i componenti renderizzati prima e dopo possono mostrare valori diversi. Questa incoerenza si chiama tearing. useSyncExternalStore legge il valore durante il rendering e costringe React a rifare il rendering in modo sincrono se lo store è cambiato, quindi ogni componente vede lo stesso valore.

Usalo quando i dati vivono fuori da React: il tuo modulo store, un'API del browser, una libreria di terze parti. La maggior parte delle librerie di stato (Redux, Zustand e altre) lo chiama per te dentro i loro hook. Per i dati che appartengono ai tuoi componenti, useState, useReducer e il context restano gli strumenti giusti.