Kurs JavaScript i React · Moduł 16: Obsługa błędów i Suspense

react-error-boundary - nowoczesna biblioteka

5 min czytania ·
W tej lekcji6

Twoja klasowa grodź z poprzedniej lekcji działa ale spójrz, czego jej brakuje: nie da się jej zresetować po naprawie modułu, nie zareaguje na błąd z kliknięcia ani z fetch, a każdy projekt przepisuje ją od nowa. Tworzenie Error Boundaries od zera wymaga pisania komponentów klasowych, co w dobie hooków może wydawać się archaiczne. Na szczęście istnieje biblioteka react-error-boundary, która znacznie upraszcza pracę z obsługą błędów. Poleca ją nawet dokumentacja react.dev jako gotową alternatywę dla własnej klasy.

Instalacja i podstawowe użycie

Bibliotekę instalujesz jak każdą paczkę z npm. Poniższe polecenie dotyczy npm, w projekcie z yarn wpiszesz yarn add react-error-boundary:

npm install react-error-boundary

W chwili pisania aktualna jest wersja 6.x. Działa z React 19 (oraz 18), jest dystrybuowana jako moduł ES i jest komponentem klienckim, więc w Next.js App Router plik z nią musi mieć dyrektywę "use client".

Biblioteka udostępnia gotowy komponent ErrorBoundary z wieloma przydatnymi funkcjami. Najpierw definiujemy komponent zastępczy, potem owijamy nim stację i podpinamy dwa callbacki:

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

function ErrorFallback({ error, resetErrorBoundary }) {
  return (
    <div className="error-panel">
      <h2>Awaria modułu!</h2>
      <p>{error.message}</p>
      <button onClick={resetErrorBoundary}>
        Restart modułu
      </button>
    </div>
  );
}

function App() {
  return (
    <ErrorBoundary
      FallbackComponent={ErrorFallback}
      onError={(error, info) => {
        // Logowanie do serwisu monitoringu
        console.error('Logged error:', error);
      }}
      onReset={() => {
        // Reset stanu aplikacji po naprawie błędu
        console.log('Error boundary reset');
      }}
    >
      <SpaceStation />
    </ErrorBoundary>
  );
}

onError odpowiada metodzie componentDidCatch: dostaje błąd i obiekt z componentStack. onReset wywoła się, gdy granica zostanie wyczyszczona, na przykład po kliknięciu "Restart modułu". Wtedy React spróbuje ponownie wyrenderować SpaceStation. Jedna uwaga do wersji 6: w typach TypeScript error ma typ unknown, bo rzucić można cokolwiek, nie tylko obiekt Error. Jeśli chcesz bezpiecznie wyciągnąć komunikat, biblioteka eksportuje pomocniczą funkcję getErrorMessage(error).

FallbackComponent vs fallback vs fallbackRender

Biblioteka oferuje trzy sposoby definiowania zastępczego UI. Robią to samo, różnią się wygodą i dostępem do danych o błędzie.

1. FallbackComponent (zalecane)

Przekazujesz komponent, a biblioteka sama wyrenderuje go z propsami error i resetErrorBoundary:

function MyFallback({ error, resetErrorBoundary }) {
  return (
    <div>
      <p>Błąd: {error.message}</p>
      <button onClick={resetErrorBoundary}>Spróbuj ponownie</button>
    </div>
  );
}

<ErrorBoundary FallbackComponent={MyFallback}>
  <App />
</ErrorBoundary>

Taki komponent można przetestować osobno i użyć w wielu granicach, dlatego to mój domyślny wybór.

2. fallback (prosty JSX)

Gdy nie potrzebujesz treści błędu ani przycisku resetu, wystarczy gotowy element JSX:

<ErrorBoundary fallback={<p>Coś poszło nie tak!</p>}>
  <App />
</ErrorBoundary>

Ten wariant nie dostaje żadnych propsów, więc załoga zobaczy komunikat, ale nie zrestartuje modułu.

3. fallbackRender (render prop)

Trzecia opcja to funkcja wywoływana z tymi samymi danymi, wygodna do krótkich, jednorazowych fallbacków:

<ErrorBoundary
  fallbackRender={({ error, resetErrorBoundary }) => (
    <div>
      <p>{error.message}</p>
      <button onClick={resetErrorBoundary}>Reset</button>
    </div>
  )}
>
  <App />
</ErrorBoundary>

Funkcja otrzymuje ten sam obiekt co FallbackComponent, zmienia się tylko forma zapisu.

Hook useErrorBoundary

Jedno z najpotężniejszych narzędzi biblioteki - hook useErrorBoundary pozwala programowo wywoływać błędy w Error Boundary z poziomu event handlerów i kodu asynchronicznego! Zwraca funkcję showBoundary(error), która przekazuje błąd do najbliższej granicy, oraz resetBoundary(), która ją czyści:

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

function DataFetcher() {
  const { showBoundary } = useErrorBoundary();
  const [data, setData] = useState(null);

  const fetchData = async () => {
    try {
      const response = await fetch('/api/missions');
      if (!response.ok) {
        throw new Error('Błąd pobierania danych misji');
      }
      const result = await response.json();
      setData(result);
    } catch (error) {
      // Przekaż błąd do najbliższego Error Boundary!
      showBoundary(error);
    }
  };

  return (
    <div>
      <button onClick={fetchData}>Pobierz dane misji</button>
      {data && <p>Misje: {data.length}</p>}
    </div>
  );
}

Sam try/catch nadal łapie błąd, zmienia się tylko to, co z nim robimy: zamiast lokalnego komunikatu uruchamiamy ten sam fallback, który obsługuje błędy renderowania. W React 19 istnieje też alternatywa: błąd rzucony w funkcji przekazanej do startTransition z useTransition również trafia do najbliższej granicy.

resetKeys - automatyczny reset

Możesz skonfigurować resetKeys - listę wartości, których zmiana automatycznie zresetuje Error Boundary. To przydatne, gdy awaria zależy od wybranych danych:

function App() {
  const [selectedPlanet, setSelectedPlanet] = useState('Mars');

  return (
    <ErrorBoundary
      FallbackComponent={ErrorFallback}
      resetKeys={[selectedPlanet]}
      onReset={() => {
        // Czyszczenie po resecie
        console.log('Boundary reset - nowa planeta:', selectedPlanet);
      }}
    >
      <PlanetDetails planet={selectedPlanet} />
    </ErrorBoundary>
  );
}
// Gdy użytkownik zmieni planetę, Error Boundary automatycznie się zresetuje

Warto wiedzieć, że po zmianie klucza onReset dostaje obiekt z polem reason: 'keys', a przy resecie przyciskiem reason: 'imperative-api'. Dzięki temu wiesz, co wywołało restart.

Nested Error Boundaries

Możesz zagnieżdżać wiele Error Boundaries dla różnych poziomów obsługi, tak jak w poprzedniej lekcji:

<ErrorBoundary FallbackComponent={AppCrashScreen}>
  <Header />
  <ErrorBoundary FallbackComponent={SectionError}>
    <MissionControl />
  </ErrorBoundary>
  <ErrorBoundary FallbackComponent={SectionError}>
    <CrewPanel />
  </ErrorBoundary>
</ErrorBoundary>

Jeśli błąd wystąpi w MissionControl, zostanie przechwycony przez wewnętrzny ErrorBoundary. Jeśli wewnętrzny sam rzuci błąd, przechwycony zostanie przez zewnętrzny.

Porównanie: własny Error Boundary vs react-error-boundary

Zestawmy obie grodzie obok siebie:

CechaWłasny (klasowy)react-error-boundary
ResetRęcznie implementowanyWbudowany (resetErrorBoundary)
Auto-resetBrakresetKeys
HookBrakuseErrorBoundary
LoggingRęcznieWbudowany (onError)
Async errorsNie przechwytujeshowBoundary()
BoilerplateDużoMinimum

Kluczowa zaleta biblioteki to hook useErrorBoundary - pozwala przechwytywać błędy z event handlerów i kodu asynchronicznego, czego natywne Error Boundaries nie potrafią. W praktyce, jeśli budujesz poważną aplikację produkcyjną, react-error-boundary jest standardem branżowym - tak jak ustandaryzowane systemy bezpieczeństwa na statkach kosmicznych. Pod spodem to wciąż ta sama klasa z getDerivedStateFromError, więc wszystko, czego nauczyłeś się wcześniej, nadal obowiązuje. W kolejnych lekcjach połączysz ją z formularzami, monitoringiem i Suspense.

Pamiętaj: nie buduj grodzi od zera na każdym statku, sięgnij po sprawdzony moduł i skup się na tym, co zobaczy załoga.

Kod do tej lekcji: App.jsx
import React, { useState } from 'react';
import './styles.css';

// Symulacja react-error-boundary
// (w produkcji: import { ErrorBoundary } from 'react-error-boundary')

class ErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false, error: null };
  }

  static getDerivedStateFromError(error) {
    return { hasError: true, error };
  }

  componentDidCatch(error, info) {
    if (this.props.onError) {
      this.props.onError(error, info);
    }
  }

  resetErrorBoundary = () => {
    if (this.props.onReset) {
      this.props.onReset();
    }
    this.setState({ hasError: false, error: null });
  };

  render() {
    if (this.state.hasError) {
      const { FallbackComponent, fallback, fallbackRender } = this.props;
      if (FallbackComponent) {
        return (
          <FallbackComponent
            error={this.state.error}
            resetErrorBoundary={this.resetErrorBoundary}
          />
        );
      }
      if (fallbackRender) {
        return fallbackRender({
          error: this.state.error,
          resetErrorBoundary: this.resetErrorBoundary,
        });
      }
      if (fallback) return fallback;
      return <p>Cos poszlo nie tak</p>;
    }
    return this.props.children;
  }
}

// FallbackComponent
function ModuleError({ error, resetErrorBoundary }) {
  return (
    <div className="error-card">
      <h3>Awaria modulu</h3>
      <p className="error-msg">{error.message}</p>
      <button onClick={resetErrorBoundary} className="retry-btn">
        Restart modulu
      </button>
    </div>
  );
}

// Niestabilny komponent
function UnstablePanel({ name }) {
  if (Math.random() < 0.5) {
    throw new Error(name + ': krytyczny blad systemu!');
  }
  return (
    <div className="panel-ok">
      <span className="dot green" />
      {name} - Online
    </div>
  );
}

function StablePanel({ name }) {
  return (
    <div className="panel-ok">
      <span className="dot green" />
      {name} - Online
    </div>
  );
}

export default function App() {
  const [key, setKey] = useState(0);

  return (
    <div className="app">
      <h1>react-error-boundary</h1>
      <p className="subtitle">
        Trzy sposoby definiowania fallback UI
      </p>
      <button onClick={() => setKey(k => k + 1)} className="reset-all">
        Zresetuj wszystko
      </button>

      <div className="panels" key={key}>
        <div className="panel-section">
          <h2>FallbackComponent</h2>
          <ErrorBoundary
            FallbackComponent={ModuleError}
            onError={(err) => console.log('Logged:', err.message)}
            onReset={() => console.log('Reset!')}
          >
            <UnstablePanel name="Nawigacja" />
          </ErrorBoundary>
        </div>

        <div className="panel-section">
          <h2>fallbackRender</h2>
          <ErrorBoundary
            fallbackRender={({ error, resetErrorBoundary }) => (
              <div className="error-card">
                <p>{error.message}</p>
                <button onClick={resetErrorBoundary} className="retry-btn">
                  Napraw
                </button>
              </div>
            )}
          >
            <UnstablePanel name="Komunikacja" />
          </ErrorBoundary>
        </div>

        <div className="panel-section">
          <h2>fallback (prosty JSX)</h2>
          <ErrorBoundary fallback={<p className="simple-err">Modul offline</p>}>
            <UnstablePanel name="Sensory" />
          </ErrorBoundary>
        </div>

        <div className="panel-section">
          <h2>Stabilny modul</h2>
          <ErrorBoundary FallbackComponent={ModuleError}>
            <StablePanel name="Podtrzymywanie zycia" />
          </ErrorBoundary>
        </div>
      </div>
    </div>
  );
}

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Jakie propsy otrzymuje FallbackComponent w react-error-boundary?

  2. 2. Do czego służy hook useErrorBoundary z biblioteki react-error-boundary?

Zadania praktyczne w grze

  • Układanie w poziomie

    Ułóż poprawną składnię użycia ErrorBoundary z FallbackComponent:

  • Edytor kodu

    Zaimplementuj async error handling

  • Klikanie w kolejności

    Kliknij elementy w kolejności składni ErrorBoundary z resetowaniem:

  • Klikanie w kolejności

    Kliknij elementy w kolejności użycia useErrorBoundary z fetch:

  1. PytanieFallbackComponent w react-error-boundary
  2. Ułóż w kolejnościSkładnia ErrorBoundary z FallbackComponent
  3. Zadanie z kodemPraktyka: Obsługa błędów asynchronicznych
  4. PytanieHook useErrorBoundary
  5. Kliknij w kolejnościErrorBoundary z onReset i resetKeys
  6. Kliknij w kolejnościUżycie useErrorBoundary w kodzie async

Przydatne artykuły