TanStack Query v5: Migration Guide & Best Practices (2026)

Migrieren Sie ohne Ausfallzeiten zu TanStack Query v5. Breaking Changes, neue Hooks, persistentes Query-Caching und Produktionsmuster für React-Entwickler.

Huifer
Huifer
16. September 202614 min read
Auch verfügbar auf:English · 中文

Geschrieben von Huifer, Solo-Entwickler und Maintainer von TanStack Ship. Ich habe mit TanStack Query v5 (früher React Query) Produktions-Apps über mehrere SaaS-Produkte hinweg ausgeliefert. Diese Guides spiegeln praktische Produktionserfahrung mit echtem Code, gemessenem Verhalten und ehrlichen Grenzen wider.

Geprüfte Quellen: tanstack.com, github.com/TanStack, web.dev, developers.mozilla.org. Zuletzt aktualisiert: 2026-10-23 · Changelog

TanStack Query (früher React Query) v5 bringt deutliche API-Verbesserungen und Performance-Gewinne. Nach dem Einsatz in dutzenden Produktions-Apps hier die Muster, die im großen Maßstab wirklich funktionieren.

Kurzfassung: v5 ist ein Aufräum-Release. cacheTime heißt jetzt gcTime, notifyOnChangeProps und isData wurden entfernt, und useQuery hat seine onError/onSuccess-Callbacks verloren. Migrieren Sie in dieser Reihenfolge: Paket → gcTime → notifyOnChangeProps → isData → SSR-Hydration → Test-Suite. Übernehmen Sie anschließend die v5-idiomatischen Muster: Query-Key-Factories, queryOptions(), bewusst gesetzte staleTime-Werte, feingranulare Subscriptions über select und optimistische Mutations, die immer zurückrollen.

Was sich in TanStack Query v5 geändert hat

v5 ist primär ein Aufräum- und Stabilisierungs-Release. Die v4-API hatte mehrere deprecated Pfade, die das Team bereits für zwei Major-Versionen entfernen wollte. In v5 werden diese entfernt.

ÄnderungAlt (v4)Neu (v5)Auswirkung
Zeit bis zur Garbage Collection des CachescacheTimegcTimeUmbenannt — cacheTime ist in v5 entfernt
Steuerung der Re-RendersnotifyOnChangePropsselectEntfernt; select ist der idiomatische Ersatz
Boolean-Kurzpfad für Datenquery.isDataquery.isSuccessEntfernt; explizite Status-Flags verwenden
Daten der vorherigen Seite behaltenkeepPreviousData: trueplaceholderData: keepPreviousDataIn die Option placeholderData verschoben
Erfolgs-/Fehler-CallbacksonSuccess / onError bei useQuerykeinethrowOnError + Error Boundaries verwenden
SuspenseuseQuery({ suspense: true })useSuspenseQueryIn einen eigenen Hook aufgeteilt

Quelle: der offizielle Migrationsleitfaden zu v5.

Die Umbenennung zu gcTime

cacheTime wurde in v4 weich zu gcTime umbenannt. In v5 ist die Option vollständig entfernt:

typescript
// v4 (in v4 deprecated, in v5 entfernt)
const { data } = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  cacheTime: 5 * 60 * 1000, // ❌ In v5 entfernt
});

// v5
const { data } = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  gcTime: 5 * 60 * 1000, // ✅ Richtig in v5
});

notifyOnChangeProps ist weg

Die Option, mit der Sie festlegen konnten, welche Ergebnis-Eigenschaften einen Re-Render auslösen, wurde entfernt — zugunsten feingranularer Subscriptions über select:

typescript
// v4 — notifyOnChangeProps (in v5 entfernt)
const { data } = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  notifyOnChangeProps: ['data', 'error'], // ❌ Entfernt
});

// v5 — stattdessen auf einen Ausschnitt subscriben
const { data: todoCount } = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  select: (data) => data.length, // ✅ Re-rendert nur, wenn sich die Länge ändert
});

select gab es schon in v4, aber in v5 wird es zum unterstützten Weg, unnötige Re-Renders zu vermeiden.

Migrations-Checkliste

Arbeiten Sie diese Schritte der Reihe nach ab — ein übersprungener Schritt macht aus einer sauberen Migration eine Fehlersuche zur Laufzeit.

  • Paket aktualisieren auf tanstack-query@5.x und die React-Peer-Dependency prüfen (v5 verlangt React 18+).
  • Jedes cacheTime durch gcTime ersetzen (projektweite Suche).
  • Jedes notifyOnChangeProps in select umwandeln — oder es entfernen, wenn das Standard-Re-Render-Verhalten in Ordnung ist.
  • isData durch isSuccess / isError / isLoading ersetzen.
  • onSuccess / onError von useQuery wegnehmen — sie leben jetzt in useMutation, oder Sie nutzen throwOnError mit einer Error Boundary.
  • keepPreviousData: true durch placeholderData: keepPreviousData ersetzen.
  • SSR-Hydration testen, wenn Sie dehydrate / HydrationBoundary einsetzen.
  • Test-Suite ausführen und die Konsole lesen — v5 gibt für jede entfernte API eine Migrationswarnung aus.

Migration Schritt für Schritt

Schritt 1: Paket aktualisieren

bash
npm install @tanstack/react-query@5
# oder
pnpm add @tanstack/react-query@5

Schritt 2: QueryClient-Defaults aktualisieren

typescript
// src/lib/queryClient.ts
import { QueryClient } from '@tanstack/react-query';

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      gcTime: 1000 * 60 * 5, // 5 Minuten (vorher cacheTime)
      staleTime: 1000 * 30, // 30 Sekunden — ein sinnvoller Default
      retry: 1,
      refetchOnWindowFocus: true,
    },
    mutations: {
      onError: (error) => {
        console.error('Mutation error:', error);
      },
    },
  },
});

Schritt 3: Das Query-Key-Factory-Muster übernehmen

Zentralisierte Keys sind der Grund, warum Invalidierung vorhersagbar bleibt, sobald eine Codebasis über eine Handvoll Queries hinauswächst:

ts
// src/lib/queryKeys.ts
export const queryKeys = {
  users: {
    all: ['users'] as const,
    lists: () => [...queryKeys.users.all, 'list'] as const,
    list: (filters: UserFilters) => [...queryKeys.users.lists(), filters] as const,
    details: () => [...queryKeys.users.all, 'detail'] as const,
    detail: (id: string) => [...queryKeys.users.details(), id] as const,
  },
} as const;

Dasselbe Factory-Muster, mit domänenspezifischen Key-Gruppen:

ts
// Verwendung in Komponenten
const { data: users } = useQuery({
  queryKey: queryKeys.users.list({ status: 'active' }),
  queryFn: () => fetchUsers({ status: 'active' }),
});

Schritt 4: Feingranulare Reaktivität mit select

select ist der v5-Weg, um auf einen Ausschnitt der Query-Daten zu subscriben — die Komponente re-rendert nie für Änderungen, die sie nicht betreffen:

ts
// Hier zählt nur die Anzahl
const { data: userCount } = useQuery({
  queryKey: queryKeys.users.all,
  queryFn: fetchAllUsers,
  select: (users) => users.length,
});

Schritt 5: SSR-Hydration (falls zutreffend)

dehydrate und HydrationBoundary funktionieren weiterhin genauso; v5 hat lediglich die Types verschärft:

tsx
// app/page.tsx — Next.js-App-Router-Beispiel
import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query';

async function UsersPage() {
  const queryClient = new QueryClient();
  await queryClient.prefetchQuery({
    queryKey: queryKeys.users.list({ status: 'active' }),
    queryFn: () => fetchUsers({ status: 'active' }),
  });

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <UsersList />
    </HydrationBoundary>
  );
}

Query-Key-Factories

Das wirkungsvollste Muster überhaupt: strukturierte Query-Key-Factories. Ad-hoc-String-Keys erzeugen subtile Bugs und machen das Invalidieren des Caches unvorhersagbar.

ts
// queries/userKeys.ts
export const userKeys = {
  all: ['users'] as const,
  lists: () => [...userKeys.all, 'list'] as const,
  list: (filters: UserFilters) => [...userKeys.lists(), filters] as const,
  details: () => [...userKeys.all, 'detail'] as const,
  detail: (id: string) => [...userKeys.details(), id] as const,
}

// Verwendung
const { data } = useQuery({
  queryKey: userKeys.detail(userId),
  queryFn: () => fetchUser(userId),
})

// Alle User-Queries invalidieren
queryClient.invalidateQueries({ queryKey: userKeys.all })

// Nur die Liste invalidieren
queryClient.invalidateQueries({ queryKey: userKeys.lists() })

Typisierte Query-Options

v5 hat queryOptions() eingeführt — für wiederverwendbare, typsichere Query-Konfigurationen:

ts
import { queryOptions } from '@tanstack/react-query'

export const userQueryOptions = (userId: string) =>
  queryOptions({
    queryKey: userKeys.detail(userId),
    queryFn: () => fetchUser(userId),
    staleTime: 5 * 60 * 1000, // 5 Minuten
  })

// In einer Komponente
const { data: user } = useQuery(userQueryOptions(userId))

// In einem Route-Loader (TanStack-Router-Integration)
export const Route = createFileRoute('/users/$userId')({
  loader: ({ context, params }) =>
    context.queryClient.ensureQueryData(userQueryOptions(params.userId)),
})

Smarte Stale Times

Verwenden Sie nicht für alles den Default staleTime: 0. Überlegen Sie, wie sich Daten tatsächlich ändern:

ts
// Nutzereinstellungen ändern sich selten — 1 Stunde cachen
const { data: preferences } = useQuery({
  queryKey: ['preferences'],
  queryFn: fetchPreferences,
  staleTime: 60 * 60 * 1000,
})

// Feed-Daten ändern sich ständig — kein Cache
const { data: feed } = useQuery({
  queryKey: ['feed'],
  queryFn: fetchFeed,
  staleTime: 0,
  refetchInterval: 30_000,
})

// Produktkatalog — mittlerer Cache
const { data: products } = useQuery({
  queryKey: ['products', filters],
  queryFn: () => fetchProducts(filters),
  staleTime: 5 * 60 * 1000,
})

staleTime: Infinity funktioniert in v5 weiterhin — es bedeutet lediglich „niemals als stale betrachten“. Nutzen Sie das für Referenzdaten, die sich im Deploy-Takt ändern, und deaktivieren Sie die automatischen Refetch-Trigger explizit, wenn Sie diese Garantie brauchen.

Optimistische Mutations

Optimistische Updates lassen die UI sofortig reagieren. v5 macht das deutlich sauberer:

ts
function useUpdateTodo() {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: updateTodo,
    onMutate: async (updatedTodo) => {
      // Laufende Queries abbrechen, damit das optimistische Update nicht überschrieben wird
      await queryClient.cancelQueries({ queryKey: todoKeys.detail(updatedTodo.id) })

      // Vorherigen Wert für den Rollback sichern
      const previous = queryClient.getQueryData(todoKeys.detail(updatedTodo.id))

      // Optimistisch aktualisieren
      queryClient.setQueryData(todoKeys.detail(updatedTodo.id), (old) => ({
        ...old,
        ...updatedTodo,
      }))

      return { previous }
    },
    onError: (err, updatedTodo, context) => {
      // Bei Fehler zurückrollen
      queryClient.setQueryData(todoKeys.detail(updatedTodo.id), context?.previous)
    },
    onSettled: (data, error, updatedTodo) => {
      // Nach der Mutation immer erneut abfragen
      queryClient.invalidateQueries({ queryKey: todoKeys.detail(updatedTodo.id) })
    },
  })
}

Das Trio onMutate → onError → onSettled ist der gesamte Vertrag: onMutate erzeugt den optimistischen Zustand und liefert den Rollback-Kontext zurück, onError stellt diesen Kontext wieder her, onSettled invalidiert immer, damit der nächste Render den Server-Stand abbildet.

Infinite Queries mit Cursor-Pagination

Cursor-basierte Pagination ist bei Live-Daten verlässlicher als Offset-Pagination:

ts
const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfiniteQuery({
  queryKey: ['posts', filters],
  queryFn: ({ pageParam }) => fetchPosts({ cursor: pageParam, ...filters }),
  initialPageParam: undefined as string | undefined,
  getNextPageParam: (lastPage) => lastPage.nextCursor,
})

// Seiten für das Rendering flach ausrollen
const posts = data?.pages.flatMap((page) => page.items) ?? []

Integration mit Error Boundaries

Da v5 onError aus useQuery entfernt hat, werden Fehler, die die Route abbrechen sollen, mit throwOnError ausgelöst und von einer Boundary abgefangen:

tsx
// Fehler an die nächste Error Boundary werfen
const { data } = useQuery({
  queryKey: ['critical-data'],
  queryFn: fetchCriticalData,
  throwOnError: true,
})

// In Ihrem Route- oder Komponenten-Baum
function RouteErrorBoundary({ error }: { error: Error }) {
  return (
    <div className="error-state">
      <h2>Something went wrong</h2>
      <p>{error.message}</p>
      <button onClick={() => window.location.reload()}>Retry</button>
    </div>
  )
}

Prefetching für bessere UX

Daten beim Hover vorab laden, um Loading States komplett zu eliminieren:

tsx
function PostCard({ post }: { post: Post }) {
  const queryClient = useQueryClient()

  return (
    <Link
      to="/posts/$postId"
      params={{ postId: post.id }}
      onMouseEnter={() => {
        queryClient.prefetchQuery(postQueryOptions(post.id))
      }}
    >
      {post.title}
    </Link>
  )
}

FAQ

Was sind die größten Breaking Changes in TanStack Query v5? cacheTime → gcTime (der alte Name ist entfernt), notifyOnChangeProps entfernt zugunsten von select, isData entfernt zugunsten expliziter Status-Flags, und useQuery akzeptiert kein onSuccess / onError mehr.

Wie migriere ich von React Query v4 zu v5? Paket aktualisieren, alle cacheTime durch gcTime ersetzen, die Verwendung von notifyOnChangeProps in select umwandeln, isData-Prüfungen ersetzen und nach jedem Schritt die Test-Suite ausführen. Der offizielle Migrationsleitfaden listet jede entfernte API auf.

Funktioniert TanStack Query v5 mit dem Next.js App Router? Ja. Der QueryClient muss clientseitig erstellt werden, um Hydration-Mismatches zu vermeiden, und HydrationBoundary + dehydrate funktionieren genauso wie in v4.

Wird staleTime: Infinity weiterhin unterstützt? Ja — in v5 ist die Option nicht deprecated. Sie bedeutet, dass die Daten nie als stale gelten; kombinieren Sie sie daher mit explizitem refetchOnMount / refetchOnWindowFocus: false, wenn Sie eine harte Garantie brauchen.

Wie verbessert v5 die Performance gegenüber v4? Durch feingranulare Subscriptions auf Basis von select (weniger Re-Renders in Listenansichten), einen klareren gcTime / staleTime-Lifecycle und ein verfeinertes Verhalten beim Abbrechen von Queries.

Weiterführende Lektüre: Tanstack Router Best Practices 2026 · Tanstack Query Booking Holds · TanStack Query vs SWR

Fazit

Die wichtigsten Takeaways:

  1. Query-Key-Factories — strukturieren Sie Ihre Keys vom ersten Tag an
  2. queryOptions() — teilen Sie die Query-Konfiguration zwischen Komponenten und Loaders
  3. Bewusste Stale Times — passen Sie die Cache-Dauer an die Änderungsrate der Daten an
  4. Optimistische Updates — behandeln Sie Rollback und Refetch nach Abschluss immer
  5. Prefetch on Hover — der günstigste Performance-Gewinn, den Sie je finden werden

Diese Muster haben in der Produktion unzählige Stunden beim Debuggen von stale Daten und Cache-Invalidierungs-Bugs gespart. Starten Sie mit den Key-Factories und arbeiten Sie sich von dort aus vor.

Mehr zu diesem Thema

Dieser Beitrag beleuchtet einen Aspekt. Beginne mit dem vollständigen Leitfaden oder sieh dir die anderen Aspekte an.