Kurs Next.js · Moduł 6: Formularze i Server Actions
Komponenty error.tsx dla obsługi błędów
W tej lekcji9
Podczas tworzenia aplikacji w Next.js, jednym z ważnych aspektów jest odpowiednie obsługiwanie sytuacji awaryjnych. Framework Next.js oferuje prosty, a zarazem potężny mechanizm umożliwiający łatwe izolowanie i obsługę błędów w aplikacji - komponenty error.tsx. W tym module przyjrzymy się, jak efektywnie wykorzystać te komponenty do poprawy odporności i doświadczenia użytkownika naszej aplikacji.
Czym jest komponent error.tsx?
Komponent error.tsx to specjalny plik w strukturze aplikacji Next.js, który służy jako "granica błędu" (error boundary) dla danego segmentu aplikacji. Gdy w danym segmencie lub jego dzieciach wystąpi błąd:
- Next.js automatycznie przechwytuje ten błąd
- Renderuje komponent error.tsx zamiast komponentu, który wygenerował błąd
- Izoluje błąd do konkretnego segmentu, pozwalając reszcie aplikacji działać normalnie
Jak działa error.tsx w Next.js App Router?
W architekturze App Router, komponenty error.tsx możemy umieszczać na dowolnym poziomie struktury katalogów, co pozwala na bardzo precyzyjne określanie granic błędów.
Podstawowa implementacja
Oto jak wygląda prosty komponent error.tsx:
'use client'; // Musi być komponentem klienckim
import { useEffect } from 'react';
interface ErrorComponentProps {
error: Error & { digest?: string };
reset: () => void;
}
export default function Error({ error, reset }: ErrorComponentProps) {
useEffect(() => {
// Opcjonalnie raportowanie błędu do serwisu monitorowania
console.error('Wystąpił nieoczekiwany błąd:', error);
}, [error]);
return (
<div className="p-6 max-w-sm mx-auto bg-white rounded-xl shadow-md">
<h2 className="text-xl font-bold text-red-600 mb-4">Coś poszło nie tak!</h2>
<p className="text-gray-700 mb-4">
Przepraszamy, wystąpił nieoczekiwany błąd. Nasz zespół został powiadomiony.
</p>
<button
onClick={reset}
className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
>
Spróbuj ponownie
</button>
</div>
);
}Kluczowe elementy:
Oznaczenie 'use client' - komponent error.tsx musi być oznaczony jako komponent kliencki, nawet jeśli reszta aplikacji używa renderowania po stronie serwera.
Props:
error: Obiekt błędu zawierający informacje o tym, co poszło nie takreset: Funkcja, która pozwala na ponowną próbę renderowania komponentu, który wygenerował błąd
Funkcja reset(): Pozwala użytkownikom spróbować ponownie wykonać operację bez przeładowywania całej strony.
Strategie obsługi błędów z użyciem error.tsx
1. Hierarchiczna obsługa błędów
Next.js pozwala na tworzenie komponentów error.tsx na różnych poziomach struktury katalogów, co umożliwia precyzyjną kontrolę nad tym, jak obsługiwane są błędy w różnych częściach aplikacji.
app/
├── error.tsx # Globalny fallback dla błędów całej aplikacji
├── layout.tsx
├── page.tsx
├── dashboard/
│ ├── error.tsx # Obsługa błędów dla całego dashboardu
│ ├── layout.tsx
│ ├── page.tsx
│ └── settings/
│ ├── error.tsx # Specyficzny dla sekcji ustawień
│ └── page.tsx
└── profile/
├── error.tsx # Specyficzny dla profilu użytkownika
└── page.tsx2. Szczegółowe komunikaty błędów w środowisku deweloperskim
Możemy dostosować komponent error.tsx tak, aby wyświetlał bardziej szczegółowe informacje o błędzie w środowisku deweloperskim:
'use client';
export default function Error({ error, reset }) {
const isDevelopment = process.env.NODE_ENV === 'development';
return (
<div>
<h2>Coś poszło nie tak!</h2>
{isDevelopment && (
<div className="bg-gray-100 p-4 rounded my-4">
<h3 className="font-bold">Szczegóły błędu (tylko w trybie dev):</h3>
<p className="font-mono">{error.message}</p>
<pre className="overflow-auto text-sm mt-2">{error.stack}</pre>
</div>
)}
<button onClick={reset}>Spróbuj ponownie</button>
</div>
);
}3. Różne typy błędów, różne komunikaty
Możemy dostosować wygląd i komunikaty w zależności od typu błędu:
'use client';
import { useEffect } from 'react';
export default function Error({ error, reset }) {
// Logowanie błędu do systemu monitoringu
useEffect(() => {
console.error(error);
// logErrorToService(error);
}, [error]);
// Określenie typu błędu na podstawie wiadomości lub innych właściwości
const is404 = error.message?.includes('not found') || error.statusCode === 404;
const isAuthentication = error.message?.includes('unauthorized') || error.statusCode === 401;
return (
<div className="p-6 mx-auto max-w-md">
{is404 ? (
<>
<h2 className="text-xl font-bold">Zasób nie znaleziony</h2>
<p>Przepraszamy, ale żądany zasób nie istnieje.</p>
</>
) : isAuthentication ? (
<>
<h2 className="text-xl font-bold">Wymagane uwierzytelnienie</h2>
<p>Musisz się zalogować, aby uzyskać dostęp do tego zasobu.</p>
<button className="mt-4 px-4 py-2 bg-blue-500 text-white rounded">
Zaloguj się
</button>
</>
) : (
<>
<h2 className="text-xl font-bold text-red-600">Nieoczekiwany błąd</h2>
<p>Przepraszamy, wystąpił nieoczekiwany problem.</p>
</>
)}
<button
onClick={reset}
className="mt-4 px-4 py-2 bg-gray-200 rounded hover:bg-gray-300"
>
Spróbuj ponownie
</button>
</div>
);
}Integracjaz systemami monitoringu błędów
W produkcyjnych aplikacjach niezbędne jest gromadzenie informacji o błędach. Komponenty error.tsx mogą być zintegrowane z zewnętrznymi systemami monitoringu błędów, takimi jak Sentry, LogRocket czy New Relic:
'use client';
import { useEffect } from 'react';
import * as Sentry from '@sentry/nextjs';
export default function Error({ error, reset }) {
useEffect(() => {
// Wysłanie informacji o błędzie do Sentry
Sentry.captureException(error);
}, [error]);
return (
<div>
<h2>Coś poszło nie tak!</h2>
<p>Nasz zespół został powiadomiony o problemie.</p>
<button onClick={reset}>Spróbuj ponownie</button>
</div>
);
}Obsługa błędów API i fetch
Błędy podczas pobierania danych w komponentach Next.js można obsługiwać za pomocą error.tsx, ale warto pamiętać o kilku niuansach:
W komponentach serwerowych
// app/products/page.tsx
async function getProducts() {
const res = await fetch('https://api.example.com/products');
if (!res.ok) {
// Ten błąd zostanie przechwycony przez najbliższy error.tsx
throw new Error('Nie udało się pobrać produktów');
}
return res.json();
}
export default async function ProductsPage() {
const products = await getProducts();
return (
<div>
<h1>Nasze produkty</h1>
<ul>
{products.map(product => (
<li key={product.id}>{product.name}</li>
))}
</ul>
</div>
);
}W komponentach klienckich
'use client';
import { useState, useEffect } from 'react';
import { useRouter } from 'next/navigation';
export default function ClientProductsPage() {
const [products, setProducts] = useState([]);
const [error, setError] = useState(null);
const router = useRouter();
useEffect(() => {
async function fetchProducts() {
try {
const res = await fetch('/api/products');
if (!res.ok) {
throw new Error('Błąd pobierania danych');
}
const data = await res.json();
setProducts(data);
} catch (err) {
setError(err.message);
// Opcjonalnie - możemy ręcznie wywołać najbliższy error.tsx
// throw err; // To spowoduje, że Next.js użyje najbliższego error.tsx
}
}
fetchProducts();
}, []);
if (error) {
return (
<div className="p-4 bg-red-50 border border-red-200 rounded">
<h2 className="text-red-600 font-bold">Wystąpił błąd</h2>
<p>{error}</p>
<button onClick={() => router.refresh()}>Odśwież stronę</button>
</div>
);
}
return (
<div>
<h1>Produkty (Klient)</h1>
{/* ... */}
</div>
);
}Dobre praktyki przy pracy z error.tsx
Odpowiednia granularność - używaj error.tsx na poziomach, które dają sensowną izolację błędów, ale nie twórz zbyt wielu komponentów.
Użyteczne komunikaty - dostarczaj przyjazne dla użytkownika wiadomości i jasne instrukcje co do dalszych kroków.
Opcje naprawy - oferuj możliwości naprawy sytuacji, takie jak przycisk "Spróbuj ponownie" (używając funkcji
reset).Śledzenie i monitorowanie - zawsze loguj błędy do systemów monitorowania, aby móc śledzić i rozwiązywać problemy.
Testowanie - testuj różne scenariusze błędów, aby upewnić się, że Twoje granice błędów reagują prawidłowo.
Dostępność - zapewnij, że komunikaty błędów są dostępne również dla użytkowników korzystających z technologii wspomagających.
Łapanie błędów z layout.tsx
Granice błędów z error.tsx nie przechwytują błędów z komponentów layout.tsx w tym samym segmencie. Aby obsłużyć błędy w layoutach, musisz utworzyć komponent error.tsx w segmencie nadrzędnym.
app/
├── dashboard/
│ ├── layout.tsx // Błędy tu nie są łapane przez error.tsx na tym samym poziomie
│ ├── error.tsx // Ten nie złapie błędów z layout.tsx
│ └── page.tsxPrawidłowa struktura do łapania błędów z layout.tsx:
app/
├── error.tsx // Ten złapie błędy z dashboard/layout.tsx
├── dashboard/
│ ├── layout.tsx
│ └── page.tsxPrzykład kompletnej implementacji
Poniżej znajduje się przykład bardziej zaawansowanego komponentu error.tsx z obsługą różnych typów błędów, opcjami naprawy i integracją z zewnętrznym systemem monitorowania:
'use client';
import { useEffect, useState } from 'react';
import Link from 'next/link';
import { useRouter } from 'next/navigation';
// Typy błędów, które możemy obsługiwać specjalnie
enum ErrorType {
NOT_FOUND = 'NOT_FOUND',
UNAUTHORIZED = 'UNAUTHORIZED',
FORBIDDEN = 'FORBIDDEN',
TIMEOUT = 'TIMEOUT',
SERVER_ERROR = 'SERVER_ERROR',
UNKNOWN = 'UNKNOWN'
}
interface ErrorComponentProps {
error: Error & {
digest?: string;
statusCode?: number;
};
reset: () => void;
}
export default function Error({ error, reset }: ErrorComponentProps) {
const router = useRouter();
const [errorType, setErrorType] = useState<ErrorType>(ErrorType.UNKNOWN);
const [isReporting, setIsReporting] = useState(false);
// Określenie typu błędu
useEffect(() => {
if (error.message?.toLowerCase().includes('not found') || error.statusCode === 404) {
setErrorType(ErrorType.NOT_FOUND);
} else if (error.message?.toLowerCase().includes('unauthorized') || error.statusCode === 401) {
setErrorType(ErrorType.UNAUTHORIZED);
} else if (error.message?.toLowerCase().includes('forbidden') || error.statusCode === 403) {
setErrorType(ErrorType.FORBIDDEN);
} else if (error.message?.toLowerCase().includes('timeout') || error.message?.includes('timed out')) {
setErrorType(ErrorType.TIMEOUT);
} else if (error.statusCode >= 500 && error.statusCode < 600) {
setErrorType(ErrorType.SERVER_ERROR);
}
}, [error]);
// Raportowanie błędu
useEffect(() => {
// Logowanie do konsoli w dev
console.error('Application error:', error);
// W prawdziwej aplikacji wysłalibyśmy to do zewnętrznego serwisu
async function reportError() {
try {
setIsReporting(true);
// Przykładowa implementacja
// await fetch('/api/error-reporting', {
// method: 'POST',
// headers: { 'Content-Type': 'application/json' },
// body: JSON.stringify({
// message: error.message,
// stack: process.env.NODE_ENV === 'development' ? error.stack : undefined,
// url: window.location.href,
// type: errorType,
// timestamp: new Date().toISOString()
// })
// });
await new Promise(resolve => setTimeout(resolve, 1000)); // Symulacja
} catch (e) {
console.error('Failed to report error:', e);
} finally {
setIsReporting(false);
}
}
reportError();
}, [error, errorType]);
// Renderowanie różnych komunikatów w zależności od typu błędu
function renderErrorContent() {
switch (errorType) {
case ErrorType.NOT_FOUND:
return (
<>
<h2 className="text-2xl font-bold text-gray-800 mb-3">Nie znaleziono zasobu</h2>
<p className="text-gray-600 mb-4">
Strona, której szukasz, nie istnieje lub została przeniesiona.
</p>
<div className="flex space-x-4">
<button
onClick={() => router.back()}
className="px-4 py-2 bg-gray-200 rounded hover:bg-gray-300"
>
Powrót
</button>
<Link href="/" className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600">
Strona główna
</Link>
</div>
</>
);
case ErrorType.UNAUTHORIZED:
return (
<>
<h2 className="text-2xl font-bold text-gray-800 mb-3">Wymagane logowanie</h2>
<p className="text-gray-600 mb-4">
Musisz się zalogować, aby uzyskać dostęp do tej strony.
</p>
<Link
href="/login"
className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
>
Zaloguj się
</Link>
</>
);
case ErrorType.FORBIDDEN:
return (
<>
<h2 className="text-2xl font-bold text-gray-800 mb-3">Brak dostępu</h2>
<p className="text-gray-600 mb-4">
Nie masz uprawnień do tej strony lub zasobu.
</p>
<button
onClick={() => router.back()}
className="px-4 py-2 bg-gray-200 rounded hover:bg-gray-300"
>
Powrót
</button>
</>
);
case ErrorType.TIMEOUT:
return (
<>
<h2 className="text-2xl font-bold text-gray-800 mb-3">Upłynął limit czasu</h2>
<p className="text-gray-600 mb-4">
Operacja trwała zbyt długo. Sprawdź swoje połączenie internetowe i spróbuj ponownie.
</p>
<button
onClick={reset}
className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
>
Spróbuj ponownie
</button>
</>
);
case ErrorType.SERVER_ERROR:
return (
<>
<h2 className="text-2xl font-bold text-gray-800 mb-3">Błąd serwera</h2>
<p className="text-gray-600 mb-4">
Przepraszamy, wystąpił błąd po stronie serwera. Nasz zespół został powiadomiony.
</p>
<button
onClick={reset}
className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
>
Spróbuj ponownie
</button>
</>
);
default:
return (
<>
<h2 className="text-2xl font-bold text-gray-800 mb-3">Coś poszło nie tak</h2>
<p className="text-gray-600 mb-4">
Przepraszamy, wystąpił nieoczekiwany błąd. {isReporting ? 'Zgłaszamy problem...' : 'Nasz zespół został powiadomiony.'}
</p>
<div className="flex space-x-4">
<button
onClick={reset}
className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
>
Spróbuj ponownie
</button>
<button
onClick={() => router.refresh()}
className="px-4 py-2 bg-gray-200 rounded hover:bg-gray-300"
>
Odśwież stronę
</button>
</div>
</>
);
}
}
// Rendering dla trybu deweloperskiego - dodatkowe informacje o błędzie
function renderDevModeInfo() {
if (process.env.NODE_ENV !== 'development') return null;
return (
<div className="mt-8 p-4 bg-gray-100 rounded-lg border border-gray-300">
<h3 className="text-sm font-bold uppercase text-gray-500 mb-2">
Informacje o błędzie (tylko tryb dev)
</h3>
<p className="font-mono text-sm mb-2">{error.message}</p>
{error.digest && (
<p className="font-mono text-xs text-gray-500 mb-2">Digest: {error.digest}</p>
)}
{error.stack && (
<pre className="mt-2 p-2 bg-gray-800 text-gray-200 rounded overflow-x-auto text-xs">
{error.stack}
</pre>
)}
</div>
);
}
return (
<div className="min-h-[400px] flex flex-col items-center justify-center p-6">
<div className="w-full max-w-md bg-white rounded-lg shadow-lg p-8 text-center">
{renderErrorContent()}
{renderDevModeInfo()}
</div>
</div>
);
}Podsumowanie
Komponenty error.tsx w Next.js to potężne narzędzie do obsługi błędów, które:
- Izolują błędy do konkretnych segmentów aplikacji
- Pozwalają na prezentowanie przyjaznych komunikatów użytkownikom
- Umożliwiają próbę naprawy sytuacji bez przeładowywania strony
- Mogą być dostosowane dla różnych typów błędów
- Pozwalają na integrację z systemami monitoringu błędów
Dzięki nim możesz tworzyć bardziej odporne aplikacje, które elegancko obsługują sytuacje awaryjne, poprawiając ogólne doświadczenie użytkownika i zmniejszając frustrację związaną z nieoczekiwanymi problemami.
Kod do tej lekcji: App.tsx
import React, { useState, Component, ReactNode } from 'react';
// Symulacja error.tsx w Next.js App Router
// Kazdy segment moze miec wlasny error boundary
// Symulowany error boundary (jak error.tsx w Next.js)
class ErrorBoundary extends Component<
{ children: ReactNode; fallback: (error: Error, reset: () => void) => ReactNode },
{ error: Error | null }
> {
state: { error: Error | null } = { error: null };
static getDerivedStateFromError(error: Error) { return { error }; }
reset = () => this.setState({ error: null });
render() {
if (this.state.error) return this.props.fallback(this.state.error, this.reset);
return this.props.children;
}
}
// Komponent error.tsx - wyswietlany przy bledzie
function ErrorComponent({ error, reset }: { error: Error; reset: () => void }) {
return (
<div style={{
background: '#3e1010', border: '1px solid #f44336', borderRadius: 8,
padding: 16, margin: '8px 0'
}}>
<h3 style={{ color: '#f44336', margin: '0 0 8px' }}>error.tsx</h3>
<p style={{ color: '#ffcdd2', fontSize: 13 }}>{error.message}</p>
<button onClick={reset} style={{
background: '#f44336', color: '#fff', border: 'none', borderRadius: 4,
padding: '6px 12px', cursor: 'pointer', fontFamily: 'monospace', marginTop: 8
}}>
Sprobuj ponownie (reset)
</button>
</div>
);
}
// Komponent, ktory moze rzucic blad
function DangerousWidget({ label }: { label: string }) {
const [shouldError, setShouldError] = useState(false);
if (shouldError) throw new Error(`Blad w komponencie "${label}"!`);
return (
<div style={{ background: '#1a2744', borderRadius: 8, padding: 16, border: '1px solid #64ffda' }}>
<h4 style={{ color: '#64ffda', margin: '0 0 8px' }}>{label}</h4>
<p style={{ color: '#aaa', fontSize: 12 }}>Ten komponent dziala poprawnie.</p>
<button onClick={() => setShouldError(true)} style={{
background: '#ff5722', color: '#fff', border: 'none', borderRadius: 4,
padding: '4px 10px', cursor: 'pointer', fontFamily: 'monospace', fontSize: 11
}}>
Wywolaj blad
</button>
</div>
);
}
export default function ErrorTsxDemo() {
return (
<div style={{ background: '#0f0f23', minHeight: '100vh', padding: 20, color: '#e0e0e0', fontFamily: 'monospace' }}>
<h1 style={{ color: '#64ffda' }}>error.tsx w Next.js</h1>
<p style={{ color: '#888', fontSize: 13, marginBottom: 16 }}>
Kazdy segment moze miec wlasny error.tsx. Blad izolowany - reszta aplikacji dziala.
</p>
<div style={{ display: 'grid', gap: 12 }}>
<div style={{ background: '#0d1117', borderRadius: 8, padding: 12 }}>
<div style={{ color: '#888', fontSize: 11, marginBottom: 8 }}>app/dashboard/error.tsx</div>
<ErrorBoundary fallback={(error, reset) => <ErrorComponent error={error} reset={reset} />}>
<DangerousWidget label="Dashboard Widget" />
</ErrorBoundary>
</div>
<div style={{ background: '#0d1117', borderRadius: 8, padding: 12 }}>
<div style={{ color: '#888', fontSize: 11, marginBottom: 8 }}>app/profile/error.tsx</div>
<ErrorBoundary fallback={(error, reset) => <ErrorComponent error={error} reset={reset} />}>
<DangerousWidget label="Profile Widget" />
</ErrorBoundary>
</div>
<div style={{ background: '#0d1117', borderRadius: 8, padding: 12 }}>
<div style={{ color: '#888', fontSize: 11, marginBottom: 8 }}>app/settings/error.tsx (niezalezny)</div>
<ErrorBoundary fallback={(error, reset) => <ErrorComponent error={error} reset={reset} />}>
<DangerousWidget label="Settings Widget" />
</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. ARIA labels w formularzach pomagają w: