React Error Boundary: Render Hatalarına Yedek Arayüz

Error boundary, içindeki bileşenler render olurken fırlatılan hataları yakalayan ve tüm uygulamayı çökertmek yerine bir yedek arayüz gösteren bir React bileşenidir. Bunun için bir hook olmadığından static getDerivedStateFromError tanımlayan bir class bileşeni olmalıdır. Onu bir kez yazar ve ağacın herhangi bir kısmının etrafına sararsın.

Çocuğun render sırasında hata fırlatması için "Break the profile"a bas.

// This throws on purpose: Profile throws during render after you press the button.
import { Component, useState } from 'react';

class ErrorBoundary extends Component {
    state = { error: null };

    static getDerivedStateFromError(error) {
        return { error };
    }

    componentDidCatch(error, info) {
        console.log('caught:', error.message);
    }

    reset = () => {
        this.props.onReset();
        this.setState({ error: null });
    };

    render() {
        if (this.state.error) {
            return (
                <div style={{ padding: 12, background: '#fdecea' }}>
                    <p>Something went wrong: {this.state.error.message}</p>
                    <button onClick={this.reset}>Try again</button>
                </div>
            );
        }
        return this.props.children;
    }
}

function Profile({ broken }) {
    if (broken) {
        throw new Error('Profile could not render');
    }
    return <p>Ada Lovelace, mathematician</p>;
}

export default function App() {
    const [broken, setBroken] = useState(false);

    return (
        <div>
            <button onClick={() => setBroken(true)}>Break the profile</button>
            <p>This line is outside the boundary and stays.</p>
            <ErrorBoundary onReset={() => setBroken(false)}>
                <Profile broken={broken} />
            </ErrorBoundary>
        </div>
    );
}

Profil yedek arayüzle değiştirilir ve sayfanın geri kalanı çalışmaya devam eder. Konsol hatayı iki kez gösterir: React yakalanan her hatayı console.error ile kaydeder ve componentDidCatch onu yeniden kaydeder. "Try again" nedeni (broken) ve boundary'nin hatasını temizler, böylece profil yeniden render olur. reset'ten this.props.onReset();'u kaldır; Try again doğrudan yedek arayüze geri fırlatır, çünkü hiçbir şey nedeni düzeltmedi.

Class nasıl çalışır

İki metot bir class'ı bir error boundary yapar:

• static getDerivedStateFromError(error), bir çocuk hata fırlattıktan hemen sonra render sırasında çalışır. Boundary'yi yedek arayüzüne geçiren state güncellemesini döndürür. Saf olmalıdır: kayıt yok, istek yok.
• componentDidCatch(error, info), yedek arayüz ekrandayken çalışır. Onu hatayı bir raporlama servisine göndermek gibi yan etkiler için kullan. info.componentStack, hata fırlatan bileşeni ve üstündeki bileşenleri listeler.

class ErrorBoundary extends Component {
    state = { error: null };

    static getDerivedStateFromError(error) {
        return { error }; // switch to the fallback
    }

    componentDidCatch(error, info) {
        reportError(error, info.componentStack); // your logging service
    }

    render() {
        if (this.state.error) return this.props.fallback;
        return this.props.children;
    }
}

Hook karşılığı yoktur, bu yüzden yalnızca fonksiyon bileşenleriyle yazılmış bir uygulamanın bile bu tek class'a ihtiyacı vardır. Class sözdizimi sana yeniyse class bileşenleri sayfası onu anlatıyor.

Bir boundary neyi yakalar, neyi yakalamaz

Bir boundary, React içindeki bileşenler üzerinde çalışırken olan hataları yakalar:

• render (bir fonksiyon bileşeninin gövdesi, bir class'ın render'ı),
• çocuk class bileşenlerinin yaşam döngüsü metotları ve constructor'ları,
• efektler (useEffect, useLayoutEffect) ve ref callback'leri,
• use ile okunan reddedilmiş bir promise ve React 19'da bir form action'ının ya da useTransition'dan gelen startTransition'a aktarılan bir fonksiyonun fırlattığı hata.

Yakalamadıkları:

• olay işleyicilerindeki hatalar,
• kendin başlattığın async kod: setTimeout, .then() callback'leri, bir olay işleyicisindeki bir await,
• boundary'nin kendi render'ındaki hatalar (onları bir üstteki boundary yakalar),
• sunucu tarafı render sırasındaki hatalar.

Olay işleyicileri render'ı bozmadıkları için dışarıda bırakılır. Ekran hâlâ geçerli bir durumdadır, bu yüzden işleyicideki bir try/catch yeterlidir. Boundary'nin görünmesini gerçekten istiyorsan hatayı state'te sakla ve bir sonraki render'da fırlat:

// This throws on purpose: the second button forwards an async error to the boundary.
import { Component, useState } from 'react';

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

function loadReport() {
    // Stands in for a request that fails
    return new Promise((_, reject) => setTimeout(() => reject(new Error('Report failed to load')), 150));
}

function Report() {
    const [error, setError] = useState(null);
    if (error) throw error; // thrown during render, so the boundary sees it

    async function handleUnsafe() {
        await loadReport(); // rejects: the boundary never hears about it
    }

    async function handleForwarded() {
        try {
            await loadReport();
        } catch (e) {
            setError(e);
        }
    }

    return (
        <div>
            <button onClick={handleUnsafe}>Load (error escapes)</button>
            <button onClick={handleForwarded}>Load (error forwarded)</button>
        </div>
    );
}

export default function App() {
    return (
        <ErrorBoundary>
            <Report />
        </ErrorBoundary>
    );
}

İlk düğme düğmeleri ekranda bırakır ve konsola yalnızca yakalanmamış bir hata yazdırır. İkincisi reddedilmeyi yakalar, saklar ve boundary devralır.

Boundary'ler nereye konmalı

Tüm uygulamanın etrafındaki tek bir boundary beyaz ekranı durdurur, ama o zaman herhangi bir küçük hata her şeyin yerini alır. Boundary'leri bağımsız olarak başarısız olabilen parçaların etrafına koy: bir kenar çubuğu widget'ı, bir grafik, her rota. Bir başarısızlık o zaman kullanıcıya sayfaya değil, bir panele mal olur.

// This throws on purpose: the Stocks widget fails during render.
import { Component } from 'react';

class ErrorBoundary extends Component {
    state = { error: null };
    static getDerivedStateFromError(error) {
        return { error };
    }
    render() {
        if (this.state.error) {
            return <div style={{ padding: 8, background: '#fdecea' }}>{this.props.name} is unavailable.</div>;
        }
        return this.props.children;
    }
}

function Weather() {
    return <div style={{ padding: 8, background: '#eef6ee' }}>Weather: 21 °C</div>;
}

function Stocks() {
    const prices = undefined; // imagine the data came back empty
    return <div style={{ padding: 8 }}>Stocks: {prices.length} prices</div>;
}

export default function App() {
    return (
        <div style={{ display: 'grid', gap: 8 }}>
            <ErrorBoundary name="Weather">
                <Weather />
            </ErrorBoundary>
            <ErrorBoundary name="Stocks">
                <Stocks />
            </ErrorBoundary>
        </div>
    );
}

Yalnızca Stocks paneli yedek arayüzünü gösterir. İki widget'ı tek bir <ErrorBoundary>'ye taşı; çalışan Weather paneli de onunla birlikte kaybolur.

Hiç boundary olmadan, bir render hatası yakalanmadığında React tüm ağacı ekrandan kaldırır. Boş bir sayfa, yanlış veri gösteren bozuk bir sayfadan daha güvenlidir, ama kullanıcılar onu bir çökme olarak okur.

react-error-boundary kütüphanesi

react-error-boundary paketi class'ı senin için sarar ve sıfırlama yardımcıları ekler. Bu editörde mevcut değil, bu yüzden burada statik bir blokta:

import { ErrorBoundary, useErrorBoundary } from 'react-error-boundary';

function Fallback({ error, resetErrorBoundary }) {
    return (
        <div role="alert">
            <p>Something went wrong: {error.message}</p>
            <button onClick={resetErrorBoundary}>Try again</button>
        </div>
    );
}

<ErrorBoundary FallbackComponent={Fallback} onReset={() => refetch()} resetKeys={[userId]}>
    <Profile userId={userId} />
</ErrorBoundary>;

// Inside a child: hand an async error to the boundary
const { showBoundary } = useErrorBoundary();
fetchData().catch(showBoundary);

resetKeys, listelenen herhangi bir değer değiştiğinde boundary'yi sıfırlar ve showBoundary, önceki örnekteki "sakla ve fırlat" numarasını yapar.

React 19'da hataları raporlamak

React 19 hataları yeni bir şekilde raporlar. Bir boundary tarafından yakalanan hatalar bir kez console.error ile kaydedilir, yakalanmamış hatalar ise window.reportError'a gider. Onları kendi servisine göndermek için createRoot'a seçenekler aktar. Her seçenek eşleşen varsayılan kaydın yerini alır:

import { createRoot } from 'react-dom/client';

const root = createRoot(document.getElementById('root'), {
    onCaughtError(error, errorInfo) {
        // an error boundary caught it
        logToService('caught', error, errorInfo.componentStack);
    },
    onUncaughtError(error, errorInfo) {
        // no boundary caught it, and React removed the tree
        logToService('uncaught', error, errorInfo.componentStack);
    },
    onRecoverableError(error, errorInfo) {
        // React recovered by itself, for example after a hydration mismatch
        logToService('recovered', error, errorInfo.componentStack);
    },
});
root.render(<App />);

onRecoverableError, React'in senin yardımın olmadan düzelttiği hatalar içindir; örneğin bir hydration uyuşmazlığı ya da React yeniden denediğinde kaybolan bir render hatası. hydrateRoot aynı üç seçeneği alır.

Yaygın hatalar

Boundary'yi hata fırlatan bileşenin içine koymak. Bir boundary yalnızca çocuklarından gelen hataları yakalar. Profile kendi JSX'inin etrafında <ErrorBoundary> render edip sonra kendi gövdesinde hata fırlatırsa, hata onu geçip bir üstteki boundary'ye gider. Bileşeni ebeveyninden sar.

getDerivedStateFromError içinde yan etkiler. Render sırasında çalışır ve birden fazla kez çalışabilir, bu yüzden onu state döndürmekle sınırla. Kayıt tutmak componentDidCatch'e ya da kökün onCaughtError'ına aittir.

Hiçbir şeyi düzeltmeyen bir sıfırlama. Boundary'nin hatasını temizlemek aynı çocukları aynı props ile render eder. Yeniden hata fırlatırlarsa kullanıcı yedek arayüze geri döner. Önce hataya neyin neden olduğunu değiştir (yeniden veri çek, hatalı girdiyi temizle, key'i değiştir), sonra hatayı temizle; ilk örnek bunu onReset ile yapıyor.

Tüm uygulama için tek bir boundary ve başka hiçbir şey. Boş sayfayı önler ama her küçük başarısızlığı tam sayfalık bir hataya dönüştürür. Özelliklerin etrafına boundary'ler ekle ve en üst düzeydekini son çare olarak tut.

Hatayı senden gizleyen yedek arayüzler. Dostça bir mesaj kullanıcılar için doğrudur, ama hatanın yine de kayıtlarına ulaştığından emin ol. React 19 yakalanan hataları varsayılan olarak konsola kaydeder; production'da o konsol kullanıcının konsoludur, bu yüzden hataları componentDidCatch'ten ya da onCaughtError'dan bir servise gönder.

Error boundary'ler <Suspense> ile doğal olarak eşleşir: Suspense "henüz hazır değil"i, boundary ise "başarısız oldu"yu ele alır. use örneklerindeki gibi boundary'yi Suspense'in dışına koy, böylece tek bir bileşen yüklemeyi, başarıyı ve başarısızlığı kapsar.