Server state nedir

Bu Rehber Ne Anlatıyor

TanStack Query dokümanı İngilizce ve kapsamlı. Bu rehber onu tekrar etmiyor. Her derste konuyu kısaca özetleyip kütüphanenin maintainer'larının önerilerini ve yaygın hataları topluyor. Sürüm: TanStack Query v5.104 (Ekim 2026). React 18 ve sonrasıyla çalışır.¹²

Ön koşul, React rehberindeki State ve Effect dersleri. Örnekler Vite ile kurulmuş bir React projesinde ilerler; Next.js'e özgü kısım Next.js ile prefetch dersinde.

Server State Nedir

Bir component'in ekranda gösterdiği verinin iki kaynağı olabilir. Client state yalnızca tarayıcıda yaşar: modal açık mı, hangi sekme seçili. Server state ise başka bir yerde durur ve siz onun yalnızca bir kopyasını görürsünüz. Doküman server state'i dört özellikle tanımlar:¹

• Sizin kontrol etmediğiniz bir yerde saklanır.

• Okumak ve yazmak için asenkron API gerekir.

• Başkaları da değiştirebilir; siz haberdar olmazsınız.

• Dikkat etmezseniz uygulamanızdaki kopyası eskir.

Sepetteki ürün sayısı client state'tir. Ürünün stok adedi server state'tir: siz sayfaya bakarken başka bir müşteri son ürünü satın alabilir.

useEffect ile Veri Çekmek Neden Yetmez

İlk akla gelen çözüm useEffect içinde fetch'tir:

function ProductList({ category }: { category: string }) {
  const [products, setProducts] = useState<Product[]>([]);

  useEffect(() => {
    fetch(`/api/products?category=${category}`)
      .then((response) => response.json())
      .then((data) => setProducts(data));
  }, [category]);

  return <ul>{products.map((p) => <li key={p.id}>{p.name}</li>)}</ul>;
}

TanStack Query'nin ana maintainer'ı Dominik Dorfmeister (TkDodo), bu kalıptaki on satırda beş hata sayar:³

Hepsini düzeltmek için cleanup'ta bir ignore bayrağı, ayrı isLoading ve error state'leri ve kategori değişince sıfırlama gerekir. React dokümanı da Effect içinde veri çekmeyi tarif ederken bu yüzden bir framework'ü ya da bir veri kütüphanesini önerir.⁴ TkDodo sonucu tek cümleyle özetler: "Veri çekmek kolay. Asenkron state yönetimi değil."³

TanStack Query Ne Yapar

TanStack Query bir veri çekme kütüphanesi değildir; fetch'i yine siz yazarsınız. Kütüphane, o fetch'in sonucunu bir anahtarla cache'ler ve uygulamanın her yerinde tutarlı biçimde paylaşır:¹³

import { useQuery } from "@tanstack/react-query";

function ProductList({ category }: { category: string }) {
  const { data, isPending, error } = useQuery({
    queryKey: ["products", category],
    queryFn: async () => {
      const response = await fetch(`/api/products?category=${category}`);
      if (!response.ok) throw new Error("Products could not be loaded");
      return response.json() as Promise<Product[]>;
    },
  });

  if (isPending) return <p>Yükleniyor...</p>;
  if (error) return <p>Hata: {error.message}</p>;

  return <ul>{data.map((p) => <li key={p.id}>{p.name}</li>)}</ul>;
}

Yukarıdaki beş hata burada yok. Veri anahtara (category) göre saklandığı için yarış durumu oluşmaz; yükleme ve hata durumu hazır gelir; aynı anahtara giden istekler, Strict Mode'unki dahil, tek isteğe indirilir.³ Bunlara ek olarak kütüphane şunları da üstlenir:¹

• Aynı veriyi isteyen birden fazla component'i tek isteğe indirmek.

• Eskiyen veriyi arka planda yenilemek (sekmeye dönünce, internet geri gelince).

• Kullanılmayan veriyi bir süre sonra bellekten silmek.

• Sayfalama, sonsuz liste ve iyimser güncelleme gibi kalıplar.

Client State Nerede Kalır

TanStack Query bir server state kütüphanesidir. Redux ya da Zustand gibi client state kütüphanelerinin yerini almaz, onlarla birlikte çalışır. Doküman bir örnekle gösterir: global store'daki projects, teams, tasks ve users TanStack Query'ye taşındığında geriye çoğu zaman yalnızca themeMode ve sidebarStatus kalır.⁵

TkDodo'nun kuralı: sunucudan gelen veriyi client state'e kopyalamayın. Kopyaladığınız an arka plandaki güncellemeleri kaçırırsınız ve iki gerçeği senkron tutmaya çalışırsınız.⁶ TanStack'in yaratıcısı Tanner Linsley da React Summit 2020 konuşmasında aynı noktadan başlar: global store'ların büyük kısmı aslında sunucu verisinin cache'idir.⁷

Ne Zaman Gerekmez

Next.js App Router gibi Server Component destekli bir framework'te veri çoğunlukla sunucuda okunur. TkDodo bu durumda açık konuşur: veri çekme ve mutation için olgun bir çözümü olan bir framework'le yeni başlıyorsanız muhtemelen TanStack Query'ye ihtiyacınız yok.⁸ Doküman da aynı öneriyi yapar: framework'ün sunduğuyla başlayın, ihtiyaç doğana kadar eklemeyin.⁹

Kütüphane şu durumlarda hâlâ değerlidir:⁸

• Yalnızca tarayıcıda çalışan bir SPA (panel, iç araç).

• İlk sayfası sunucuda, sonraki sayfaları istemcide yüklenen sonsuz listeler.

• Polling, odaklanınca yenileme, offline çalışma gibi sürekli güncel veri isteyen ekranlar.

• React Native ya da Server Component kullanmayan projeler.

Boyut endişesi için TkDodo'nun ölçümü: QueryClient, QueryClientProvider, useQuery ve useMutation ile 10 kB'ın altında (minify + gzip). npm sayfasında gördüğünüz boyut kaynak kodu ve source map'leri de içerir, tarayıcıya gitmez.¹⁰

Kendin Dene

• Yukarıdaki useEffect örneğinde kategoriyi hızlıca değiştirin ve DevTools'un Network sekmesinde cevapların sırasını izleyin. Ekranda hangi kategori kalıyor?

• Aynı component'i useQuery ile yazın ve aynı denemeyi tekrarlayın.

• Kendi projenizdeki global store'u açın. Hangi alanlar aslında sunucu verisinin kopyası?

Detaylı Öğrenmek İçin

• Yazı: TkDodo, "Why You Want React Query"; useEffect ile veri çekmenin beş hatası ve TanStack Query karşılığı.³

• Video: Tanner Linsley, "React Query: It's Time to Break up with your Global State!"; kütüphaneyi tanıtan React Summit 2020 konuşması.⁷

• Video: TkDodo, "React Query - The Bad Parts"; boyut, normalized cache eksikliği ve öğrenme eğrisi üzerine dürüst bir değerlendirme.¹⁰

• Yazı: TkDodo, "You Might Not Need React Query"; Server Component'lerden sonra kütüphanenin yeri.⁸