React use Hook: Promises und Context beim Rendern lesen

use ist eine API aus React 19, die beim Rendern einer Komponente einen Wert aus einem Promise oder einem Context liest. use(promise) pausiert die Komponente, bis das Promise aufgelöst ist, und zeigt in der Zwischenzeit den Fallback des nächsten <Suspense>; use(context) funktioniert wie useContext, darf aber in einem if oder einer Schleife stehen.

Die Funktion fetchUser unten steht für eine echte Anfrage.

import { Suspense, use, useState } from 'react';

function fetchUser(id) {
    console.log('fetching user', id);
    return new Promise((resolve) =>
        setTimeout(() => resolve({ id, name: id === 1 ? 'Ada' : 'Linus' }), 1000),
    );
}

function Profile({ userPromise }) {
    const user = use(userPromise);
    return <p>User #{user.id}: {user.name}</p>;
}

export default function App() {
    const [userPromise, setUserPromise] = useState(() => fetchUser(1));

    return (
        <div>
            <button onClick={() => setUserPromise(fetchUser(1))}>User 1</button>
            <button onClick={() => setUserPromise(fetchUser(2))}>User 2</button>
            <Suspense fallback={<p>Loading...</p>}>
                <Profile userPromise={userPromise} />
            </Suspense>
        </div>
    );
}

Der erste Render zeigt eine Sekunde lang „Loading...“, dann das Profil. Klicke auf User 2: Der Fallback kommt zurück, solange das neue Promise aussteht. Profile hat keinen eigenen Ladezustand; es ist so geschrieben, als wären die Daten schon da.

Wie use(promise) funktioniert

Wenn Profile use(userPromise) aufruft:

• Wenn das Promise aufgelöst ist, gibt use seinen Wert zurück, und das Rendern geht weiter.
• Wenn es noch aussteht, hört React auf, Profile zu rendern, und zeigt den Fallback des nächsten <Suspense> darüber. Wenn das Promise erledigt ist, rendert React Profile erneut, und diesmal gibt use den Wert zurück.
• Wenn es abgelehnt wurde, zeigt React stattdessen die nächste Error Boundary.

React merkt sich das Ergebnis am Promise-Objekt selbst. Deshalb muss das Promise beim nächsten Render dasselbe Objekt sein.

Um das alte Profil auf dem Bildschirm zu halten, während das nächste lädt, setze das Promise in einer Transition. React wartet dann, statt den Fallback erneut zu zeigen:

<button onClick={() => startTransition(() => setUserPromise(fetchUser(2)))}>User 2</button>

Wo das Promise entsteht

Das ist der Teil, an dem Leute stolpern. Den Fetch-Aufruf in die Komponente zu schreiben, die ihn liest, sieht natürlich aus und funktioniert nicht:

// Do not do this
function Profile({ id }) {
    const user = use(fetchUser(id)); // a new promise on every render
    return <p>{user.name}</p>;
}

Jeder Render ruft fetchUser auf und bekommt ein neues, ausstehendes Promise. Profile suspendiert. Wenn dieses Promise aufgelöst ist, rendert React Profile erneut, was ein weiteres ausstehendes Promise erzeugt, das wieder suspendiert. Die Komponente zeigt die Daten nie, und der Netzwerk-Tab füllt sich mit Anfragen.

Erzeuge das Promise an einer Stelle, die nicht bei jedem Render der lesenden Komponente erneut läuft:

• In einem Elternteil, im State gehalten (wie im ersten Beispiel) oder in einem Event-Handler erzeugt.
• Auf Modulebene, wenn die Daten nicht von Props abhängen: const configPromise = fetchConfig(); über der Komponente.
• In einem Cache, nach den Argumenten geordnet, damit dieselbe ID dasselbe Promise zurückgibt.
• In einem Framework: Eine Server Component kann einer Client-Komponente ein Promise als Prop übergeben, und Route-Loader machen dasselbe. Für diesen Fall wurde use entworfen.

Hier ist die Version mit Cache, damit eine Komponente Daten per ID anfragen und trotzdem ein stabiles Promise bekommen kann:

import { Suspense, use, useState } from 'react';

const cache = new Map();
function getWeather(city) {
    if (!cache.has(city)) {
        console.log('request for', city);
        // Stands in for a real request
        cache.set(city, new Promise((resolve) => setTimeout(() => resolve(`${city.length * 3} °C`), 800)));
    }
    return cache.get(city);
}

function Weather({ city }) {
    const temperature = use(getWeather(city));
    return <p>{city}: {temperature}</p>;
}

export default function App() {
    const [city, setCity] = useState('Lisbon');

    return (
        <div>
            {['Lisbon', 'Oslo', 'Cairo'].map((c) => (
                <button key={c} onClick={() => setCity(c)}>{c}</button>
            ))}
            <Suspense fallback={<p>Loading weather...</p>}>
                <Weather city={city} />
            </Suspense>
        </div>
    );
}

Klicke dich durch die drei Städte und dann zurück zu einer, die du schon geöffnet hast. Die Konsole loggt eine Anfrage pro Stadt, und eine Stadt, die du schon gesehen hast, erscheint ohne Fallback, weil ihr Promise schon aufgelöst ist. Lösch die Prüfung if (!cache.has(city)), und die Komponente suspendiert wieder endlos.

Ein echter Cache braucht außerdem einen Weg, Einträge ablaufen zu lassen. Datenbibliotheken und Frameworks erledigen das, deshalb bekommen die meisten Apps ihre Promises von dort.

use(context), sogar in einem if

use(SomeContext) gibt denselben Wert zurück wie useContext(SomeContext). Der Unterschied ist, wo du es aufrufen kannst. Jeder andere Hook muss auf oberster Ebene laufen, bei jedem Render in derselben Reihenfolge (die Regeln der Hooks). use darf nach einem frühen return, in einer Bedingung oder in einer Schleife aufgerufen werden.

import { createContext, use, useState } from 'react';

const UserContext = createContext(null);

function Greeting({ showName }) {
    if (!showName) {
        return <p>Hello!</p>;
    }
    const user = use(UserContext);
    return <p>Hello, {user.name}!</p>;
}

export default function App() {
    const [showName, setShowName] = useState(false);

    return (
        <UserContext value={{ name: 'Grace' }}>
            <button onClick={() => setShowName(!showName)}>
                {showName ? 'Hide' : 'Show'} the name
            </button>
            <Greeting showName={showName} />
        </UserContext>
    );
}

Klicke auf den Button, um zwischen den beiden Zweigen zu wechseln. Tausche use(UserContext) gegen useContext(UserContext), und der Code bricht die Regeln der Hooks, weil der Hook bei manchen Renders liefe und bei anderen nicht.

use hat trotzdem Grenzen: Ruf es nur beim Rendern einer Komponente oder in einem Custom Hook auf. In einem Event-Handler oder einem Effekt liest du den Context über einen Wert, den du schon beim Rendern bekommen hast.

Fehler: Error Boundaries, nicht try/catch

Wenn das Promise abgelehnt wird, geht der Fehler an die nächste Error Boundary, genau wie ein Fehler beim Rendern.

// This throws on purpose: the second request rejects and the boundary shows it.
import { Component, Suspense, use, useState } from 'react';

function fetchPost(id) {
    // Stands in for a real request. Post 2 does not exist.
    return new Promise((resolve, reject) =>
        setTimeout(() => (id === 2 ? reject(new Error('Post 2 not found')) : resolve(`Post ${id} body`)), 600),
    );
}

class ErrorBoundary extends Component {
    state = { error: null };
    static getDerivedStateFromError(error) {
        return { error };
    }
    render() {
        if (this.state.error) return <p style={{ color: 'crimson' }}>{this.state.error.message}</p>;
        return this.props.children;
    }
}

function Post({ postPromise }) {
    return <p>{use(postPromise)}</p>;
}

export default function App() {
    const [id, setId] = useState(1);
    const [postPromise, setPostPromise] = useState(() => fetchPost(1));

    function open(next) {
        setId(next);
        setPostPromise(fetchPost(next));
    }

    return (
        <div>
            <button onClick={() => open(1)}>Post 1</button>
            <button onClick={() => open(2)}>Post 2</button>
            <ErrorBoundary key={id}>
                <Suspense fallback={<p>Loading...</p>}>
                    <Post postPromise={postPromise} />
                </Suspense>
            </ErrorBoundary>
        </div>
    );
}

Öffne Post 2, und die Boundary zeigt die Fehlermeldung. Öffne wieder Post 1, und es funktioniert: key={id} gibt der Boundary für jeden Post einen frischen State, damit sie nicht weiter den alten Fehler zeigt.

Ein ausstehendes oder abgelehntes use kannst du nicht mit try/catch abfangen. Solange das Promise aussteht, unterbricht use den Render, indem es einen besonderen Wert wirft, und ein catch darum würde ihn verschlucken. Der abgefangene Wert ist ein Fehler, dessen Meldung mit „Suspense Exception: This is not a real error!“ beginnt, und in der Entwicklung loggt React außerdem „use was called from inside a try/catch block“. Um statt eines Fehlerbildschirms einen Ersatzwert zu zeigen, behandle die Ablehnung am Promise, bevor du es weiterreichst:

const postPromise = fetchPost(id).catch(() => 'This post could not be loaded.');

use im Vergleich mit Laden per useEffect

Das klassische Muster auf dem Client lädt in einem Effekt und hält drei State-Werte:

function Profile({ id }) {
    const [user, setUser] = useState(null);
    const [error, setError] = useState(null);

    useEffect(() => {
        let ignore = false;
        fetchUser(id).then(
            (u) => !ignore && setUser(u),
            (e) => !ignore && setError(e),
        );
        return () => {
            ignore = true;
        };
    }, [id]);

    if (error) return <p>Error</p>;
    if (!user) return <p>Loading...</p>;
    return <p>{user.name}</p>;
}

Die Version mit Effekt ist in sich geschlossen, deshalb ist sie in Apps ohne Framework weiterhin der häufigste Ansatz; die Seite zum Laden von Daten behandelt sie vollständig. use glänzt, wenn etwas über der Komponente die Anfrage früh startet und das Promise nach unten reicht.