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.
cacheTimeheißt jetztgcTime,notifyOnChangePropsundisDatawurden entfernt, unduseQueryhat seineonError/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 gesetztestaleTime-Werte, feingranulare Subscriptions überselectund 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.
| Änderung | Alt (v4) | Neu (v5) | Auswirkung |
|---|---|---|---|
| Zeit bis zur Garbage Collection des Caches | cacheTime | gcTime | Umbenannt — cacheTime ist in v5 entfernt |
| Steuerung der Re-Renders | notifyOnChangeProps | select | Entfernt; select ist der idiomatische Ersatz |
| Boolean-Kurzpfad für Daten | query.isData | query.isSuccess | Entfernt; explizite Status-Flags verwenden |
| Daten der vorherigen Seite behalten | keepPreviousData: true | placeholderData: keepPreviousData | In die Option placeholderData verschoben |
| Erfolgs-/Fehler-Callbacks | onSuccess / onError bei useQuery | keine | throwOnError + Error Boundaries verwenden |
| Suspense | useQuery({ suspense: true }) | useSuspenseQuery | In 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:
// 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:
// 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.xund die React-Peer-Dependency prüfen (v5 verlangt React 18+). - Jedes
cacheTimedurchgcTimeersetzen (projektweite Suche). - Jedes
notifyOnChangePropsinselectumwandeln — oder es entfernen, wenn das Standard-Re-Render-Verhalten in Ordnung ist. -
isDatadurchisSuccess/isError/isLoadingersetzen. -
onSuccess/onErrorvonuseQuerywegnehmen — sie leben jetzt inuseMutation, oder Sie nutzenthrowOnErrormit einer Error Boundary. -
keepPreviousData: truedurchplaceholderData: keepPreviousDataersetzen. - SSR-Hydration testen, wenn Sie
dehydrate/HydrationBoundaryeinsetzen. - 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
npm install @tanstack/react-query@5
# oder
pnpm add @tanstack/react-query@5
Schritt 2: QueryClient-Defaults aktualisieren
// 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:
// 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:
// 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:
// 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:
// 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.
// 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:
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:
// 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:
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:
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:
// 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:
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:
- Query-Key-Factories — strukturieren Sie Ihre Keys vom ersten Tag an
queryOptions()— teilen Sie die Query-Konfiguration zwischen Komponenten und Loaders- Bewusste Stale Times — passen Sie die Cache-Dauer an die Änderungsrate der Daten an
- Optimistische Updates — behandeln Sie Rollback und Refetch nach Abschluss immer
- 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.