TanStack Start Error Boundaries: Vollständige Fehlerbehandlung

TL;DR: TanStack Start und TanStack Router bieten ein mehrstufiges Fehlerbehandlungssystem: Routenebenen-errorComponent, globale Fehlergrenzen und try/catch-Muster in Server-Funktionen. Dieser Leitfaden behandelt benutzerdefinierte Fehlerseiten pro Route, globale Fehlerüberwachungsintegration, elegante Serverfehler mit benutzerfreundlichen Nachrichten sowie Wiederherstellungsabläufe.

Einleitung

Fehlerbehandlung wird häufig als Nachgedanke behandelt, doch sie wirkt sich direkt auf das Vertrauen und die Bindung der Nutzer aus. Eine kryptische Meldung wie „Etwas ist schiefgelaufen" frustriert Nutzer. Eine gut gestaltete Fehlerseite mit Kontext, Wiederherstellungsoptionen und einer Kontaktmöglichkeit zum Support stärkt hingegen das Vertrauen.

TanStack Start bietet mehrere Ebenen für die Fehlerbehandlung – von React Error Boundaries bis hin zu serverseitigen Fehlerzuordnungen.

Routenebenen-Fehlerkomponenten

TanStack Router ermöglicht es Ihnen, ein errorComponent pro Route zu definieren und thereby eine granulare Kontrolle über die Fehlerpräsentation zu erlangen. Hier ist eine Dashboard-Route mit einer benutzerdefinierten Fehlerkomponente, die zwischen Authentifizierungsfehlern und allgemeinen Fehlern unterscheidet:

// src/routes/dashboard.tsx
import { createFileRoute } from '@tanstack/react-router'
import { ErrorComponent } from '@tanstack/react-router'

export const Route = createFileRoute('/dashboard')({
  component: DashboardPage,
  errorComponent: ({ error, reset }) => (
    <div className="p-8 text-center">
      <h2 className="text-xl font-bold mb-2">Dashboard Error</h2>
      <p className="text-gray-600 mb-4">
        {error instanceof AuthError
          ? 'Your session expired. Please log in again.'
          : 'Unable to load dashboard. Please try again.'}
      </p>
      <div className="flex gap-4 justify-center">
        <button onClick={reset} className="btn-primary">Retry</button>
        <a href="/login" className="btn-secondary">Log In</a>
      </div>
      <details className="mt-4 text-xs text-gray-400">
        <summary>Technical Details</summary>
        <pre>{error.message}</pre>
      </details>
    </div>
  ),
})

Das errorComponent empfängt sowohl das error-Objekt als auch eine reset-Funktion. Die Reset-Funktion löscht die Fehlergrenze und rendert die Route erneut, wodurch Nutzern ein Wiederherstellungspfad ohne Navigation geboten wird. Die Kategorisierung von Fehlern (Authentifizierung vs. allgemein) ermöglicht kontextbezogene Meldungen.

Globale Fehlergrenze

Für Fehler, die die Routenebenen-Behandlung umgehen, richten Sie eine globale Fehlergrenze in Ihrer Root-Route ein. Diese fängt alle unbehandelten Fehler über alle untergeordneten Routen hinweg ab:

// src/routes/__root.tsx
import { createRootRoute, Outlet } from '@tanstack/react-router'

export const Route = createRootRoute({
  component: () => (
    <ErrorBoundary fallback={<GlobalErrorPage />}>
      <Outlet />
    </ErrorBoundary>
  ),
})

Die globale Fehlergrenze fungiert als Sicherheitsnetz. Wenn eine routenebene errorComponent fehlschlägt oder ein unerwarteter Fehler sich ausbreitet, rendert die globale Grenze ein Fallback-UI, das die gesamte Anwendung abdeckt.

Server-Funktion-Fehlerbehandlung

Server-Funktionen sollten Fehler abfangen und klassifizieren, bevor sie den Client erreichen. Hier ist ein Muster, das Datenbankfehler von anderen Ausfällen unterscheidet, kritische Probleme protokolliert und gleichzeitig benutzerfreundliche Nachrichten zurückgibt:

export const fetchDataFn = createServerFn({ method: 'GET' })
  .handler(async () => {
    try {
      return await loadData()
    } catch (error) {
      if (error instanceof DatabaseError) {
        // Für Monitoring protokollieren
        console.error('Database error:', error)
        // Benutzerfreundliche Antwort zurückgeben
        return { error: 'Data temporarily unavailable', retryAfter: 30 }
      }
      throw error // Middleware übernimmt
    }
  })

Dieser Ansatz hält Ihren Client-seitigen Code sauber: Die Server-Funktion gibt entweder Daten oder eine strukturierte Fehlerantwort zurück, und der Client behandelt jeden Fall entsprechend, ohne Fehlermeldungen parsen zu müssen.

Tabelle zur Fehlerbehandlungsstrategie

Fazit

Die mehrstufige Fehlerbehandlung von TanStack Start gibt Ihnen die Kontrolle über jeden Fehlermodus. Routenebenen-Fehlerkomponenten bieten kontextspezifische Wiederherstellung, während globale Grenzen alles auffangen, was durchschlüpft. Für eine tiefere Integration kombinieren Sie Fehlergrenzen mit Middleware und Request Lifecycle-Mustern, verknüpfen Sie sie mit Nested Layouts und Auth Guards für geschützte Routen und binden Sie SaaS Monitoring und Observability für die Produktionsfehlerverfolgung ein.