React useSyncExternalStore: Externe Daten abonnieren

useSyncExternalStore abonniert für eine Komponente Daten, die außerhalb von React leben, und rendert sie erneut, wann immer sich diese Daten ändern. Du gibst ihm zwei Funktionen: subscribe, die React sagt, wie es auf Änderungen hört, und getSnapshot, die den aktuellen Wert zurückgibt.

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>
    );
}

Die beiden Display-Komponenten teilen weder Props noch Context, und doch aktualisieren sich beide gemeinsam, weil beide denselben Store abonnieren. Der Button ruft eine einfache Funktion auf, keinen React-Setter. Füge ein drittes <Display name="Sidebar" /> hinzu, und es macht ohne weitere Änderung mit.

Die Syntax

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

• subscribe(callback) beginnt zuzuhören, ruft callback auf, wann immer sich die Daten geändert haben könnten, und gibt eine Funktion zum Abbestellen zurück. React ruft sie auf, nachdem die Komponente gemountet ist, und ruft die zurückgegebene Funktion beim Unmounten auf.
• getSnapshot() gibt den aktuellen Wert zurück. React ruft sie bei jedem Render und nach jeder Benachrichtigung auf und vergleicht das Ergebnis mit dem letzten per Object.is. Gleicher Wert, kein Render.
• getServerSnapshot() (optional) gibt den Wert zurück, der auf dem Server und bei der Hydration verwendet wird.

Definiere subscribe außerhalb der Komponente oder halte sie mit useCallback stabil. Wenn du bei jedem Render eine neue Funktion subscribe übergibst, bestellt React jedes Mal ab und abonniert neu.

Browser-APIs als Stores

Alles, was einen aktuellen Wert hat und ein Event feuert, wenn sich der Wert ändert, passt in diese Form. navigator.onLine mit den Events online und offline ist der klassische Fall.

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>
    );
}

Schalte dein Netzwerk ab (oder wechsle in den Entwicklerwerkzeugen deines Browsers auf Offline), und der Text ändert sich ohne Neuladen. Das dritte Argument sagt „nimm online an“, wenn auf dem Server gerendert wird, wo es kein navigator gibt. Den Aufruf des Hooks in useOnlineStatus zu packen macht daraus einen Custom Hook, den jede Komponente nutzen kann.

Die Fensterbreite funktioniert genauso:

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>
    );
}

Füge ein paar Kopien hinzu und ändere die Fenstergröße: Jede Kopie zeigt im selben Moment dieselbe Zahl. Jede Kopie hat ihren eigenen Listener, und jede liest die Breite beim Rendern, also hinkt keine je einen Frame hinterher.

getSnapshot muss einen gecachten Wert zurückgeben

React ruft getSnapshot oft auf und vergleicht Ergebnisse per Referenz. Eine Funktion, die bei jedem Aufruf ein neues Objekt oder Array baut, sieht immer wie eine Änderung aus:

// 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 rendert, ruft getSnapshot auf, bekommt einen „anderen“ Wert, rendert erneut und so weiter, bis es mit „Maximum update depth exceeded“ stoppt. In der Entwicklung loggt React vorher außerdem „The result of getSnapshot should be cached to avoid an infinite loop“. Ein Produktions-Build wie die Vorschau hier überspringt diese Warnung und meldet nur den finalen Fehler als kurzen Code (Minified React error #185).

Die Lösung ist, die Daten im Store unveränderlich zu halten: Ersetze das Objekt, wenn es sich ändert, und gib die gespeicherte Referenz unverändert zurück.

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 gibt dasselbe Objekt state zurück, bis add es ersetzt, also rendert die Komponente einmal pro Änderung. Das Filtern passiert in der Komponente, nachdem der Snapshot gelesen wurde, und das ist sicher. Um stattdessen im Store zu filtern, berechne das gefilterte Array, wenn sich die Daten ändern, und speichere es, damit getSnapshot die gespeicherte Kopie zurückgeben kann.

getServerSnapshot und Hydration

Auf dem Server gibt es kein Fenster, kein navigator und kein Abonnement. Das dritte Argument sagt React, was es dort rendern soll:

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

React nutzt getServerSnapshot außerdem für den ersten Render im Browser, wenn es Server-HTML hydratisiert, damit beide übereinstimmen. Direkt nach der Hydration liest es getSnapshot und rendert erneut, wenn der echte Wert abweicht. Ohne das dritte Argument wirft der Server-Render „Missing getServerSnapshot, which is required for server-rendered content. Will revert to client rendering.“ Wenn eine <Suspense>-Grenze über der Komponente steht, schickt der Server den Fallback dieser Grenze, und der Browser rendert stattdessen ihren Inhalt; ohne Grenze schlägt der Server-Render fehl.

useSyncExternalStore vs. useEffect und useState

Du kannst auch mit einem Effekt abonnieren:

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;
}

Das funktioniert, hat aber zwei Schwächen. Der erste Render zeigt immer die anfängliche Vermutung, und der echte Wert kommt einen Render später, nachdem der Effekt gelaufen ist. Und beim Concurrent Rendering (etwa während einer Transition) kann React einen Render mittendrin pausieren; wenn sich der Store während der Pause ändert, können Komponenten, die davor und danach gerendert wurden, verschiedene Werte zeigen. Diese Inkonsistenz heißt Tearing. useSyncExternalStore liest den Wert beim Rendern und lässt React den Render synchron wiederholen, wenn sich der Store geändert hat, also sieht jede Komponente denselben Wert.

Nutze es, wenn die Daten außerhalb von React leben: dein eigenes Store-Modul, eine Browser-API, eine Bibliothek eines Drittanbieters. Die meisten State-Bibliotheken (Redux, Zustand und andere) rufen es in ihren Hooks für dich auf. Für Daten, die deinen Komponenten gehören, bleiben useState, useReducer und Context die richtigen Werkzeuge.