TanStack Query vs SWR: Welche State-Library gewinnt 2026

TanStack Query und SWR laden und cachen Server-Daten. Vergleichen Sie Defaults, Mutations, SSR und Devtools und wählen Sie das passende Paket für Ihre App.

Huifer
Huifer
22. Oktober 20269 min read
Auch verfügbar auf:English · 中文

Geschrieben von Huifer, Solo-Entwickler und Maintainer von TanStack Ship. Dieser Vergleich entstand aus einer echten Entscheidung: Ich brauchte Server-State-Caching für eine React-App und wollte mich nicht nach Bauchgefühl entscheiden. Ich habe die Optionstabellen beider Bibliotheken gelesen, beide Pakete in der npm-Registry geprüft und nachvollzogen, worauf mein eigenes Repository sich stützt.

Verifizierte Quellen: TanStack Query docs · Query important defaults · SWR API reference · SWR revalidation · web.dev rendering guide · Cloudflare Workers cache API

Zuletzt aktualisiert: 22. Oktober 2026 · Changelog

Direkte Antwort: SWR ist eine Single-Hook-Bibliothek, und sie gewinnt bei einer kleinen, leselastigen App, bei der Sie einen Hook, sinnvolle Defaults und keine Zeremonie wollen. TanStack Query gewinnt bei allem, was Mutationen, Pagination oder Server-Rendering enthält, weil sein Ökosystem – Router-Integration, Devtools, Hydration-Tooling – darauf aufgebaut ist. Wenn Sie auf einem Framework shippen, das TanStack Router bereits mitbringt, ist die Entscheidung für Sie getroffen.

TL;DR: SWR ist kleiner und freundlicher: ein Hook, Revalidation bei Fokus, 2000 ms Deduplizierung. TanStack Query ist größer und rigider: explizite Query Keys, eine separate Mutation-Ebene, ein 300000-ms-GC-Timer. Die npm-Registry verzeichnete 279.215.374 Downloads für @tanstack/react-query und 75.596.681 für swr zwischen dem 19.09.2026 und dem 18.10.2026.

Definition: Eine Server-State-Bibliothek ist eine React-Hook-Schicht, die entfernte Daten lädt, sie cacht und entscheidet, wann sie erneut abgerufen werden – und damit Cache-Lebensdauer und Timing der Requests aus Ihren Komponenten heraushält.

Was sich wirklich unterscheidet – und was nicht

Dieser Guide behandelt beide Bibliotheken anhand der ausgelieferten Defaults und der dokumentierten APIs: Caching, Mutationen, Pagination, Server-Rendering und Devtools. Bundle-Größe und Render-Profiling lasse ich aus, weil ich beides nicht gemessen habe. Wenn Sie zusätzlich ein Starter-Template wählen, bewertet mein SaaS-Boilerplate-Vergleich, welche Datenebene jedes Template ausliefert.

Beginnen wir mit SWR, weil es die Kurzfassung dieses Vergleichs verdient. SWR ist seit 2021 in Produktion, seine API ist für den üblichen Fall ein Hook, und seine Defaults sind gut genug, sodass die meisten Apps die Konfiguration nie anfassen. Für ein Dashboard, das aus einer API liest und bei Tab-Fokus frische Daten will, ist SWR eine reife Wahl, und ich würde nicht dagegen argumentieren.

Die beiden konvergieren an einer Stelle: Beide deduplizieren laufende Requests, beide revalidieren standardmäßig bei Fensterfokus, beide cachen nach Key, und bei beiden schreiben Sie den Fetcher selbst.

Sie divergieren bei dem, was nach dem Fetch passiert. SWR behandelt eine Mutation als Nachgedanken, erledigt über einen mutate-Aufruf. TanStack Query behandelt sie als erstklassiges Konzept, mit Mutation-Ebene, Invalidierung, optimistischen Updates und Rollback. Genau dieser Unterschied ist der Grund, warum wachsende Teams bei TanStack Query landen und kleine Teams bei SWR bleiben.

Defaults nebeneinander

Die folgenden Werte stammen aus den Optionstabellen der jeweiligen Projekte vom 22.10.2026, nicht aus dem Gedächtnis. Installieren Sie zuerst beide Bibliotheken in einem Scratch-Branch:

bash
# Install both libraries so the comparison runs on the same versions
npm install @tanstack/react-query swr
VerhaltenSWR 2.5.1TanStack Query 5.104.5
Revalidation bei FokusrevalidateOnFocus: truerefetchOnWindowFocus: true
Request-DeduplizierungdedupingInterval: 2000 msStructural sharing, kein Dedupe-Timer
Throttling bei FokusfocusThrottleInterval: 5000 msKeine Entsprechung
Retry bei FehlershouldRetryOnError: true, errorRetryInterval: 5000 ms3 Retries mit exponentiellem Backoff
Cache-LebensdauerKein Ablauf; Daten bleiben, bis sie ersetzt werdengcTime: 300000 ms nach dem Unmount des letzten Observers
StalenessNicht vorhanden; gecachte Daten werden beim Mount wiederverwendetstaleTime: 0, Daten sind beim Mount also standardmäßig stale
Vorherige Daten behaltenkeepPreviousData: falseplaceholderData: keepPreviousData verfügbar
Mutation-APIuseSWRMutation, dazu mutateuseMutation, useQueryClient
PaginationuseSWRInfiniteuseInfiniteQuery mit initialPageParam
Live-UpdatesuseSWRSubscriptionuseQuery mit eigenem queryFn
TypsicherheitTypisiert über den SWRConfig ProviderGenerische Inferenz pro useQuery-Aufruf

Eine Zeile verdient Aufmerksamkeit. Der staleTime von TanStack Query ist standardmäßig 0, ein Query, das gemountet wird, refetcht also per Default – wie SWRs revalidateIfStale: true. Wenn Sie gelesen haben, TanStack Query „cacht aggressiv“, dann lautet die präzise Version: Es cacht 300000 ms nach dem Unmount des letzten Observers, und die Frische ist eine Entscheidung pro Query.

Caching, Revalidation und der Unterschied beim Deduplizieren

Das Deduplizieren bei SWR ist zeitbasiert. Innerhalb eines 2000-ms-Fensters teilen sich zwei Komponenten, die denselben Key anfordern, eine Anfrage – gut für Dashboards, schlecht für eine präzise Anfrage-Bilanz.

TanStack Query dedupliziert strukturell. Zwei useQuery-Aufrufe mit demselben Key und derselben Query-Funktion teilen sich ein Promise, solange die Query in flight ist, und der Cache-Eintrag überlebt jede Komponente. Der Preis ist, dass Sie über das Key-Design nachdenken müssen – deshalb liefert TanStack einen Query-Key-Guide.

tsx
// SWR: the key is a string, and dedupe is a 2000 ms window
import useSWR from 'swr'

const { data, error, isLoading } = useSWR('/api/invoices', fetcher)
tsx
// TanStack Query: the key is a structured array, shared by every observer
import { useQuery } from '@tanstack/react-query'

const { data, error, isPending } = useQuery({
  queryKey: ['invoices', { status: 'open' }],
  queryFn: fetchInvoices,
})

Die beiden Designs schieben unterschiedliche Arbeit auf Sie. Mit SWR schreiben Sie einen Fetcher und einen Key. Mit TanStack Query schreiben Sie einen Key, der jede Eingabe erfassen muss, von der die Anfrage abhängt, weil der Cache ihn jeder Komponente ausliefert, die danach fragt. Das ist ein Cache-Lookup gegen einen Cache-Vertrag.

Mutationen, optimistische Updates und Rollback

Hier hört SWRs Einfachheit auf, sich auszuzahlen. useSWRMutation liefert Ihnen eine Trigger-Funktion und einen Status, und Sie entscheiden, was danach passiert – genug für einen Button, der einen Endpunkt aufruft und einen Toast zeigt.

TanStack Query modelliert die Mutation als eigenes Objekt mit Lifecycle-Hooks und liefert Ihnen den Invalidierungs-Graphen: Nach einer erfolgreichen Mutation invalidieren Sie einen Query Key, und jeder Observer refetcht. Der Guide zu optimistischen Updates behandelt den Rollback-Pfad, den die meisten handgebauten Implementierungen falsch machen.

tsx
// TanStack Query: invalidate a key after a mutation, and observers refetch
import { useMutation, useQueryClient } from '@tanstack/react-query'

const client = useQueryClient()

const save = useMutation({
  mutationFn: updateInvoice,
  onSuccess: () => client.invalidateQueries({ queryKey: ['invoices'] }),
})

Die Lücke ist nicht, dass SWR das nicht könnte. Es ist, dass SWR keinen gemeinsamen Invalidierungs-Graphen hat, also schreibt ein Team die Key-Buchhaltung selbst – und diese Buchhaltung bricht um 2 Uhr morgens.

Pagination und abhängige Requests

useSWRInfinite und useInfiniteQuery beides laden seitenbasiert, und beide unterstützen Cursor-Pagination über eine getKey-Funktion auf der SWR-Seite und getNextPageParam auf der Query-Seite. Der Unterschied zeigt sich bei abhängigen Requests: TanStack Query dokumentiert dependent queries, bei denen das Ergebnis einer Query den nächsten Key speist.

SWR löst dasselbe Muster mit useSWR und einem null-Key, aber den Guard für den null-Key übernehmen Sie selbst. Beide Bibliotheken brechen laufende Requests bei Unmount oder Key-Wechsel ab.

Wenn Ihre Liste Infinite Scroll, Filter und eine an die Auswahl gekoppelte Detail-Drawer braucht, liefert Ihnen die Query-Seite die Bausteine ohne Klebstoff. Dort würde ich SWR nicht wählen.

Server-Rendering, Hydration und Persistenz

Hier hat mein eigenes Repository die Entscheidung getroffen, deshalb zeige ich die Belege. Die Commit-ID af037a8 hat @tanstack/react-router-ssr-query am 2026-05-15 zur package.json dieses Projekts hinzugefügt. Dieses Paket deklariert eine Peer Dependency auf @tanstack/react-query mit der Range >=5.90.0.

Dieses Repository trägt diese Abhängigkeit seit 2026. Über 5 Monate Betrieb dieses Stacks habe ich beide Optionstabellen bei jedem Release erneut gelesen und die Abfrage in der npm-Registry mehrfach wiederholt, um zu bestätigen, dass sich die Zahlen nicht verschoben haben.

Kurz gesagt: Wenn ich die Server-Rendering-Query-Integration von TanStack Router nutze, ist TanStack Query bereits eine erforderliche Peer Dependency meiner Anwendung. SWR zu wählen hieße dort, den Hydration-Schritt selbst neu zu bauen. Dieselbe Entscheidung taucht in jedem Starter auf, den ich vergleiche – deshalb habe ich die Datenebene jedes einzelnen bewertet.

Für die Persistenz über Reloads hinweg liefert TanStack Query ein persistQueryClient-Plugin, das den Cache speichert und wieder hydriert, mit einem Standard-maxAge von 24 Stunden (86400 s). SWR hat kein Pendant aus erster Hand; üblicherweise seedet man den Cache mit fallback-Daten. Der SWR-Revalidation-Guide zeigt Teams, dass fallback ein manuelles Rehydrierungssystem ist, das sie nun pflegen.

Devtools und Debugging

TanStack Query liefert ein offizielles Devtools-Paket mit einer visuellen Timeline aller Queries, ihrer Zustände und ihrer Observer. SWR hat keine offiziellen Devtools; das Community-Paket swr-devtools existiert, dessen letzte auf npm veröffentlichte Version ist aber 1.3.2 aus dem Jahr 2023. Wenn Sie ein Cache-Problem debuggen, schlägt dieser Unterschied jeden Benchmark, den ich erfinden könnte. Die Devtools-Doku zeigt die Timeline; auf der SWR-Seite bedeutet Debugging, Logs zu lesen.

Wie ich entscheiden würde – mit Checkliste

Beantworten Sie diese Fragen ehrlich, und die Wahl wird meist von selbst klar.

  • Mutiert Ihre App Server-Daten an mehr als einer Stelle? Nehmen Sie TanStack Query.
  • Brauchen Sie Infinite Pagination, abhängige Queries oder optimistischen Rollback? Nehmen Sie TanStack Query.
  • Integriert sich Ihr Framework oder Router bereits mit einer der beiden? Nehmen Sie diese.
  • Ist Ihre App read-only, klein und bereit, bei Fokus neu zu laden? SWR passt gut.
  • Ist Ihnen die kleinstmögliche Dependency-Fläche wichtig? SWR gewinnt diesen Vergleich.

Eine Checkliste, die ich griffbereit habe:

  • Bestätigen Sie die Version, auf die Ihr Framework als Peer Dependency zeigt – nicht das neueste Release.
  • Legen Sie Ihre Staleness-Policy vor der ersten Query fest.
  • Halten Sie schriftlich fest, ob Sie den Cache persistieren und wie lange.
  • Fügen Sie die Devtools früh hinzu, nicht nach dem ersten mysteriösen Render.
  • Halten Sie den Fetcher langweilig und die Caching-Policy an einer Stelle.

Wenn Sie immer noch auf Starter-Ebene entscheiden, bewertet mein Starter-Vergleich die Templates danach, welche Datenebene sie ausliefern – diese Entscheidung muss also nicht bei null beginnen.

Grenzen, Methodik und Offenlegung

Meine Methodik war bewusst eng: Ich habe die offiziellen Optionstabellen für SWR 2.5.1 und TanStack Query 5.104.5 gelesen, Versions-Metadaten und Download-Zähler der letzten 30 Tage am 2026-10-22 aus der öffentlichen npm-Registry-API geholt und die package.json-Historie dieses Repositories auf die Peer-Dependency-Belege hin untersucht. Ich habe beide Bibliotheken nicht in einer App laufen lassen, die Bundle-Größe nicht gemessen und die Render-Anzahlen nicht profiliert. Jede Zahl oben stammt aus der Dokumentation der jeweiligen Bibliothek, und die Download-Zähler sind Registry-Produktionsdaten, nicht Ihr eigener Traffic.

Der Hinweis, den ich wiederholen möchte: Downloads messen Popularität, nicht Richtigkeit. SWRs 75.596.681 monatliche Downloads sagen, dass viele Teams davon abhängen – nicht, dass es zu Ihrem nächsten Screen passt.

Offenlegung: Ich baue und verkaufe TanStack Ship, das verlinkte Produkt, es besteht also eine materielle Verbindung zwischen mir und diesen Links. Wenn TanStack Query oder SWR eine Änderung ausliefert, die eine Zeile in der Tabelle invalidiert, hält das Changelog auf dieser Seite die Korrektur fest.

FAQ

Ist SWR kleiner und schneller als TanStack Query?

SWR hat eine kleinere API-Oberfläche und in der Regel ein kleineres Bundle, weil TanStack Query mehr Maschinerie ausliefert: einen Query-Cache, eine Mutation-Ebene, Devtools und ein Persistenz-Plugin. Ich habe die Bundle-Größe hier nicht gemessen, daher nenne ich den dokumentierten Feature-Unterschied und keine Zahl, die ich nicht verteidigen kann. Der Größenunterschied entscheidet selten; der Funktionsumfang entscheidet.

Kann ich TanStack Query und SWR zusammen verwenden?

Das geht, und es ist ein bekanntes Muster, aber ich würde in den meisten Projekten davon abraten: zwei Cache-Lebensdauern, zwei Sätze Defaults, zwei Debugging-Werkzeuge. Der einzige sinnvolle Fall ist eine Migration, bei der SWR eine Legacy-Screen bedient, während TanStack Query neue Arbeit übernimmt – mit einem klaren Enddatum.

Ist TanStack Query v5 eine große Neuschreibung gegenüber v4?

Ja, und lesen Sie zuerst den offiziellen Migrations-Guide. Das v5-Release erschien am 2023-10-17, und die Breaking Changes liegen in den Query- und Mutation-Option-Objekten: cacheTime wurde zu gcTime, keepPreviousData wanderte nach placeholderData, und Infinite Queries benötigen ein initialPageParam. Die Umstellung ist mechanisch, und v5 ist die bessere API.

Funktioniert TanStack Query mit React Server Components?

Teilweise, und die Unterscheidung ist wichtig. TanStack Query ist ein Client-seitiger Cache für Server-Daten, funktioniert also in Client Components und im Browser. Es ersetzt nicht das Server-Rendering; es hydriert einen Client-Cache mit bereits serverseitig geladenen Daten. Um die Serverlast zu senken, beginnen Sie mit Caching- und Rendering-Strategie.

Welche sollte ich für eine TanStack-Start-App wählen?

TanStack Query, und die Entscheidung fällt nahezu automatisch. Die Server-Rendering-Query-Integration von TanStack Router verlangt @tanstack/react-query als Peer Dependency, Sie behalten mit TanStack Query also diese Integration, statt Hydration selbst neu zu bauen. Meine Templates folgen diesem Weg, und mein Starter-Vergleich listet, welche Datenebene jedes ausliefert.

Weiterführende Lektüre: Tanstack Query V5 Best Practices · Tanstack Query Optimistic Updates · Tanstack Query V5 Migration And Best Practices 2026

Fazit

Beide sind gut, und die ehrliche Zusammenfassung lautet: SWR ist kleiner und fertig, TanStack Query ist größer und vollständig. Wählen Sie SWR, wenn Ihre App mehr liest als schreibt und Sie die Konfiguration in Ruhe lassen wollen. Wählen Sie TanStack Query, wenn Schreibzugriffe, Pagination oder Server-Rendering auf der Roadmap stehen, denn sie nachträglich einzubauen kostet mehr als sie jetzt zu übernehmen. 2026 wird das Ökosystem rund um TanStack Query voraussichtlich weiter wachsen, was für eine Codebasis zählt, die Sie noch pflegen werden.

Der nächste Schritt ist konkret: Wenn Ihr Framework bereits eine Peer Dependency festlegt, übernehmen Sie diese Wahl und machen Sie weiter. Wenn nicht, lassen Sie die Checkliste zehn Minuten lang gegen Ihre eigene App laufen und wählen Sie dann die Bibliothek, deren Defaults zum gewünschten Datenverhalten passen. Wenn Sie ein Starter-Template wollen, das diese Entscheidung bereits mitbringt, enthalten die TanStack Ship Templates das TanStack-Query-Setup mit Cloudflare Workers, und die Preisseite listet jeden Tarif.

Auf dieser Website wird der Beitrag mit einer kanonischen URL und BlogPosting-JSON-LD ausgeliefert, sodass die Metadaten in die Suchergebnisse und KI-Antworten übernehmen.

Weiterführende Lektüre