Die React Context API typsicher nutzen

1. Warum ein untypisierter Context zu Laufzeitfehlern führt

Die React Context API überträgt Zustand über die Komponentenhierarchie hinweg, ohne dass jede Zwischenkomponente Props manuell durchreichen muss. Das Problem beginnt bereits bei der Erstellung: createContext verlangt einen Default-Wert, der immer dann zum Einsatz kommt, wenn eine Komponente useContext aufruft, ohne von einem passenden Provider umschlossen zu sein. Wählt man an dieser Stelle undefined, weil zum Zeitpunkt der Context-Erstellung noch keine sinnvollen Default-Werte existieren, entsteht ein Context vom Typ MyContextType | undefined, und jede einzelne Verwendungsstelle im gesamten Projekt muss diesen möglichen undefined-Fall behandeln.

In der Praxis führt das entweder zu einer Flut von Optional-Chaining-Operatoren und Null-Checks, die eigentlich unnötig sind, weil der Context zur Laufzeit fast immer korrekt mit einem Provider umschlossen ist, oder schlimmer, zu einer stillschweigenden Typ-Assertion mit as MyContextType, die das eigentliche Problem einfach verdeckt. Fehlt der Provider dann tatsächlich, etwa weil eine Komponente versehentlich außerhalb ihres vorgesehenen Baums gerendert wird, schlägt der Code erst zur Laufzeit fehl, oft mit einer kryptischen Fehlermeldung über einen Zugriff auf eine Property von undefined.

Die Lösung, die im weiteren Verlauf dieses Artikels im Detail vorgestellt wird, kombiniert zwei Techniken: einen bewussten undefined-Zwischenzustand im Context-Typ selbst und einen Custom Hook, der genau diesen Zustand abfängt und stattdessen sofort einen aussagekräftigen Fehler wirft. Damit wird ein fehlender Provider zu einem Fehler, der beim ersten Testlauf der Komponente auffällt, nicht erst beim Kunden in der Produktion.

2. createContext richtig typisieren: undefined als bewusster Zwischenzustand

Der erste Schritt zu einer typsicheren Context API ist, den Context-Typ als Union aus der eigentlichen Datenstruktur und undefined zu deklarieren, statt zu versuchen, einen künstlichen Platzhalter-Default-Wert zu erfinden, der ohnehin niemals verwendet werden soll. createContext<ThemeContextValue | undefined>(undefined) macht explizit sichtbar, dass der Context ohne Provider tatsächlich undefined liefert, statt diesen Zustand mit einem irreführenden Fake-Objekt zu verschleiern.

Diese Entscheidung mag zunächst kontraintuitiv wirken, weil sie den Context-Typ um einen zusätzlichen Fall erweitert, den man eigentlich vermeiden möchte. Der entscheidende Punkt folgt im nächsten Abschnitt: Dieser undefined-Fall wird niemals direkt an useContext-Aufrufstellen sichtbar, weil ein Custom Hook ihn zentral abfängt. Der Context-Typ bleibt also ehrlich gegenüber dem tatsächlichen Verhalten von React, während die Komplexität an genau einer Stelle im Code gebündelt wird.

import { createContext } from "react";

interface ThemeContextValue {
  theme: "light" | "dark";
  toggleTheme: () => void;
}

// Explicit undefined: honest about what useContext returns without a Provider
const ThemeContext = createContext<ThemeContextValue | undefined>(undefined);

export { ThemeContext };
export type { ThemeContextValue };

3. Ein Custom Hook als einziger typsicherer Zugriffspunkt

Statt ThemeContext direkt in jeder Komponente mit useContext(ThemeContext) zu konsumieren, kapselt man den Zugriff in einem eigenen Custom Hook, üblicherweise useTheme genannt. Dieser Hook ruft useContext intern auf, prüft das Ergebnis auf undefined und wirft in diesem Fall sofort einen aussagekräftigen Fehler, der auf den fehlenden Provider hinweist. Der Rückgabetyp des Hooks selbst ist dann garantiert ThemeContextValue, ohne die Union mit undefined, weil der Fehlerfall bereits vor der Rückgabe abgefangen wurde.

Dieses Muster verschiebt die Fehlerbehandlung von jeder einzelnen Verwendungsstelle an eine einzige, zentrale Stelle. Jede Komponente, die useTheme() aufruft, erhält garantiert ein vollständiges ThemeContextValue-Objekt und muss keinen Optional-Chaining-Operator mehr verwenden. Vergisst ein Entwickler versehentlich, eine Komponente mit ThemeProvider zu umschließen, erscheint sofort eine klare Fehlermeldung im Konsolen-Log oder in der Testausgabe, statt eines kryptischen Laufzeitfehlers tief in der Komponente selbst.

import { createContext, useContext, useState, type ReactNode } from "react";

interface ThemeContextValue {
  theme: "light" | "dark";
  toggleTheme: () => void;
}

const ThemeContext = createContext<ThemeContextValue | undefined>(undefined);

export function ThemeProvider({ children }: { children: ReactNode }) {
  const [theme, setTheme] = useState<"light" | "dark">("light");
  const toggleTheme = () => setTheme((t) => (t === "light" ? "dark" : "light"));

  return (
    <ThemeContext.Provider value={{ theme, toggleTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

// Single, central access point: return type is always ThemeContextValue, never undefined
export function useTheme(): ThemeContextValue {
  const context = useContext(ThemeContext);
  if (context === undefined) {
    throw new Error("useTheme must be used within a ThemeProvider");
  }
  return context;
}

// Consuming components never see the undefined case
function ThemeToggleButton() {
  const { theme, toggleTheme } = useTheme();
  return <button onClick={toggleTheme}>Aktuell: {theme}</button>;
}

4. Discriminated-Union-Zustand im Context modellieren

Ein Context, der einen Authentifizierungsstatus transportiert, steht vor einem ähnlichen Problem wie ein Zustand in useState: Ohne bewusste Modellierung entstehen leicht unabhängige Felder wie isLoggedIn, user und isLoading, die in ungültigen Kombinationen auftreten können, etwa isLoggedIn: true mit user: null. Für einen Context API-Wert mit mehreren sich ausschließenden Zuständen ist eine Discriminated Union die robustere Modellierung, exakt wie bei lokalem Komponentenzustand.

Der Zugriff über den Custom Hook bleibt dabei unverändert: useAuth() liefert weiterhin garantiert einen Wert statt undefined, aber dieser Wert selbst ist jetzt eine Union aus loading, authenticated und anonymous. Jede Komponente muss vor dem Zugriff auf user explizit den status prüfen, wodurch ein Zugriff auf einen nicht existierenden Nutzer bereits beim Kompilieren verhindert wird, nicht erst durch einen Laufzeit-Check.

interface User { id: number; email: string; }

// Discriminated union instead of independent isLoggedIn/user/isLoading fields
type AuthState =
  | { status: "loading" }
  | { status: "authenticated"; user: User }
  | { status: "anonymous" };

const AuthContext = createContext<AuthState | undefined>(undefined);

export function useAuth(): AuthState {
  const context = useContext(AuthContext);
  if (context === undefined) {
    throw new Error("useAuth must be used within an AuthProvider");
  }
  return context;
}

// Usage: status must be checked before "user" becomes accessible
function AccountBadge() {
  const auth = useAuth();

  if (auth.status === "loading") return <span>Lädt...</span>;
  if (auth.status === "anonymous") return <span>Nicht angemeldet</span>;

  return <span>{auth.user.email}</span>; // fully typed, no optional chaining
}

5. State und Dispatch in getrennten Contexts typisieren

Ein einziger Context, der sowohl den aktuellen Zustand als auch die Funktionen zum Ändern dieses Zustands enthält, hat einen praktischen Nachteil: Jede Komponente, die nur eine Änderungsfunktion braucht, etwa einen Button, der lediglich toggleTheme aufruft, rendert trotzdem bei jeder Zustandsänderung neu, weil sich der komplette Context-Wert samt Zustand ändert. Die Lösung ist, State und Dispatch-Funktionen in zwei getrennte Contexts aufzuteilen, jeden mit einem eigenen, klar abgegrenzten Typ.

Diese Trennung bringt einen Nebeneffekt, der bei der Typisierung besonders zum Tragen kommt: Der Dispatch-Context ändert sich in der Regel nie, weil die referenzierten Funktionen über useCallback stabil bleiben, während der State-Context sich bei jeder Änderung neu erstellt. Komponenten, die den Dispatch-Context konsumieren, werden dadurch typsicher von unnötigen Re-Renders entkoppelt, ohne dass an der Typisierung selbst etwas Kompliziertes hinzukommt, jeder Context bleibt für sich genommen genauso einfach wie im vorherigen Abschnitt.

interface CartItem { productId: number; quantity: number; }

// Separate state and dispatch contexts, each with its own precise type
const CartStateContext = createContext<CartItem[] | undefined>(undefined);
const CartDispatchContext = createContext<
  { addItem: (item: CartItem) => void; removeItem: (productId: number) => void } | undefined
>(undefined);

export function useCartState(): CartItem[] {
  const context = useContext(CartStateContext);
  if (context === undefined) throw new Error("useCartState must be used within CartProvider");
  return context;
}

export function useCartDispatch() {
  const context = useContext(CartDispatchContext);
  if (context === undefined) throw new Error("useCartDispatch must be used within CartProvider");
  return context;
}

// Components that only dispatch actions never re-render on state changes
function AddToCartButton({ item }: { item: CartItem }) {
  const { addItem } = useCartDispatch();
  return <button onClick={() => addItem(item)}>Hinzufügen</button>;
}

6. Generische Context-Factories für wiederverwendbare Provider

Wer in einem größeren Projekt mehrere ähnlich strukturierte Contexts anlegt, jeden mit demselben Muster aus createContext, Custom Hook und Fehlerprüfung, dupliziert dabei dieselbe Boilerplate-Logik immer wieder. Eine generische Factory-Funktion, die diesen kompletten Aufbau einmal implementiert und dann für beliebige Datentypen wiederverwendet werden kann, reduziert diese Duplizierung erheblich, ohne die Typsicherheit an irgendeiner Stelle zu verlieren.

Die Factory selbst ist generisch über den Typ T des Context-Werts und gibt sowohl den Provider als auch den passenden Custom Hook als Paar zurück. Für jeden neuen Context reicht dann ein einziger Aufruf dieser Factory, statt die vollständige Struktur aus Context, Provider und Hook erneut von Hand zu schreiben. Der Typparameter sorgt dafür, dass jede Instanz der Factory ihren eigenen, spezifischen Typ behält, ohne dass die Contexts sich gegenseitig beeinflussen.

import { createContext, useContext, type ReactNode } from "react";

// Generic factory: builds a typed context, provider, and hook in one call
function createTypedContext<T>(hookName: string) {
  const Context = createContext<T | undefined>(undefined);

  function useTypedContext(): T {
    const context = useContext(Context);
    if (context === undefined) {
      throw new Error(`${hookName} must be used within its matching Provider`);
    }
    return context;
  }

  function Provider({ value, children }: { value: T; children: ReactNode }) {
    return <Context.Provider value={value}>{children}</Context.Provider>;
  }

  return [Provider, useTypedContext] as const;
}

interface LocaleContextValue { locale: "de" | "en"; setLocale: (locale: "de" | "en") => void; }

// One line instead of repeating createContext + hook + null-check boilerplate
const [LocaleProvider, useLocale] = createTypedContext<LocaleContextValue>("useLocale");

7. Context mit useReducer kombinieren

Sobald der im Context verwaltete Zustand mehrere zusammenhängende Felder hat, die durch verschiedene Ereignisse aktualisiert werden, lohnt sich die Kombination der Context API mit useReducer anstelle mehrerer einzelner useState-Aufrufe im Provider. Die Typisierung folgt dabei denselben Prinzipien wie bei einem eigenständigen Reducer: eine Discriminated Union für die Actions, eine Interface-Definition für den Zustand, und eine reine Reducer-Funktion, die beide zusammenführt.

Der Context selbst überträgt in diesem Fall meist ein Tupel aus aktuellem Zustand und der dispatch-Funktion, die useReducer zurückgibt. Weil dispatch bereits durch React vollständig typisiert ist, sobald die Actions als Union deklariert sind, muss an dieser Stelle keine zusätzliche manuelle Typarbeit geleistet werden, der Reducer-Typ propagiert automatisch bis zur Aufrufstelle im Context-Consumer.

import { createContext, useContext, useReducer, type ReactNode, type Dispatch } from "react";

interface NotificationState { messages: string[]; }

type NotificationAction =
  | { type: "ADD"; payload: string }
  | { type: "CLEAR" };

function notificationReducer(state: NotificationState, action: NotificationAction): NotificationState {
  switch (action.type) {
    case "ADD":
      return { messages: [...state.messages, action.payload] };
    case "CLEAR":
      return { messages: [] };
  }
}

// Context carries both the current state and the fully typed dispatch function
const NotificationContext = createContext<
  [NotificationState, Dispatch<NotificationAction>] | undefined
>(undefined);

export function NotificationProvider({ children }: { children: ReactNode }) {
  const value = useReducer(notificationReducer, { messages: [] });
  return <NotificationContext.Provider value={value}>{children}</NotificationContext.Provider>;
}

export function useNotifications() {
  const context = useContext(NotificationContext);
  if (context === undefined) throw new Error("useNotifications must be used within NotificationProvider");
  return context;
}

8. Context in Tests typsicher mit Mock-Providern versorgen

Ein typsicherer Custom Hook mit Fehlerprüfung hat einen unmittelbaren Nutzen für Tests: Vergisst ein Test, die zu testende Komponente mit dem passenden Provider zu umschließen, schlägt der Test sofort mit einer klaren Fehlermeldung fehl, statt ein still falsches Ergebnis zu produzieren. Für Tests selbst lohnt sich ein Test-Wrapper, der den echten Provider mit konfigurierbaren, typisierten Werten kombiniert, sodass jeder Test genau den Context-Zustand erzeugen kann, den das jeweilige Testszenario benötigt.

Wichtig ist, dass dieser Test-Wrapper dieselben Typen verwendet wie die Produktionslogik, statt eigene, lose Mock-Typen zu erfinden. Ändert sich das Context-Interface, meldet der Compiler sofort jede Stelle im Testcode, die mit der neuen Struktur nicht mehr kompatibel ist, genau wie bei jedem anderen typisierten Produktionscode auch.

import { render, screen } from "@testing-library/react";
import { ThemeContext, type ThemeContextValue } from "./ThemeContext";

// Test wrapper reuses the production type, no loose mock shape
function renderWithTheme(ui: React.ReactElement, value: ThemeContextValue) {
  return render(
    <ThemeContext.Provider value={value}>{ui}</ThemeContext.Provider>
  );
}

test("shows the current theme", () => {
  renderWithTheme(<ThemeToggleButton />, { theme: "dark", toggleTheme: () => {} });
  expect(screen.getByText(/dark/i)).toBeInTheDocument();
});

9. Context-Patterns im Vergleich

Die folgende Übersicht zeigt, welches Context-Pattern für welches Szenario geeignet ist und wovon jeweils abzuraten ist.

Kein Pattern aus dieser Übersicht ist in jedem Fall zwingend, aber jedes löst ein konkretes Problem, das ohne bewusste Typisierung in der Praxis regelmäßig auftritt. Ein Projekt mit nur einem einzigen, einfachen Context braucht keine generische Factory, ein Context mit hoher Render-Frequenz profitiert dagegen deutlich von der Aufteilung in State und Dispatch.

10. Zusammenfassung

Die React Context API typsicher nutzen bedeutet zuerst, den Context-Typ ehrlich als Union mit undefined zu deklarieren, statt einen künstlichen Fake-Default zu erfinden, und diesen Zwischenzustand dann in einem einzigen Custom Hook mit klarer Fehlermeldung abzufangen. Jede Komponente, die diesen Hook aufruft, erhält danach garantiert einen vollständigen, nicht-optionalen Wert. Zustände mit mehreren sich ausschließenden Phasen gehören als Discriminated Union in den Context, exakt wie bei lokalem Komponentenzustand, und State sollte von Dispatch-Funktionen getrennt werden, sobald unnötige Re-Renders zum Problem werden.

Für Projekte mit vielen strukturell ähnlichen Contexts reduziert eine generische Factory-Funktion die Boilerplate erheblich, ohne die Typsicherheit zu verlieren. In Tests zahlt sich die konsequente Typisierung sofort aus: Ein vergessener Provider oder eine geänderte Context-Struktur fällt durch den Compiler oder den Custom Hook auf, lange bevor ein Nutzer in Produktion einen kryptischen Laufzeitfehler zu sehen bekommt.

11. FAQ: Die React Context API typsicher nutzen