React İle Tanstack Query Kullanarak Veri Önbellekleme Nasıl Yapılır?

Gereksinimler ve Proje Kurulumu

Tanstack Query ile çalışmaya başlamadan önce Node.js yüklü bir React ortamınızın olması gerekir. 2026 yılı standartlarına uygun olarak Vite kullanmanızı öneririz. Projenize gerekli paketleri eklemek için terminalinizde aşağıdaki komutları çalıştırın.

npm install @tanstack/react-query

Kurulum tamamlandıktan sonra, uygulamanızın en üst seviyesinde QueryClientProvider bileşenini kullanarak istemciyi (client) tüm ağaca yaymanız gerekir. Bu, önbelleğin uygulamanın her yerinden erişilebilir olmasını sağlar.

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

function App() {
  return (
    
      
    
  );
}

Tanstack Query ile Temel Veri Çekme ve Önbellekleme

Veri önbelleklemenin temelinde useQuery hook'u yatar. Bu hook, belirttiğiniz bir anahtar (query key) üzerinden veriyi çeker ve otomatik olarak önbelleğe alır. Aynı anahtarla tekrar istek atıldığında, kütüphane önce önbellekteki veriyi sunar, ardından arka planda güncellik kontrolü yapar.

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

function UserProfile() {
  const { data, isLoading, error } = useQuery({
    queryKey: ['user', 1],
    queryFn: () => fetch('/api/user/1').then(res => res.json()),
    staleTime: 5000, // Verinin 5 saniye boyunca "taze" kabul edilmesini sağlar
  });

  if (isLoading) return 
Yükleniyor...
;
  return 
{data.name}
;
}

Buradaki staleTime parametresi, önbellekleme stratejinizin kalbidir. Eğer staleTime değerini 0 yaparsanız, her bileşen tekrar render edildiğinde ağ isteği tetiklenir. Değer artırıldığında ise, belirtilen süre boyunca ağ isteği yapılmadan doğrudan önbellekten veri okunur.

Önbellekleme Stratejileri ve Karşılaştırma

Uygulamanızın ihtiyaçlarına göre farklı önbellekleme stratejileri belirleyebilirsiniz. Aşağıdaki tablo, yaygın kullanım senaryolarını ve Tanstack Query karşılıklarını özetlemektedir.

Veri Güncelleme ve Önbelleği Geçersiz Kılma

Veriyi önbelleğe aldınız, peki veri değiştiğinde ne olacak? Tanstack Query'de queryClient.invalidateQueries fonksiyonu ile belirli bir anahtara sahip önbelleği "geçersiz" kılabilir ve verinin otomatik olarak tekrar çekilmesini sağlayabilirsiniz. Bu, özellikle form gönderimlerinden sonra verinin güncellenmesi için kritiktir.

import { useMutation, useQueryClient } from '@tanstack/react-query';

function UpdateUser() {
  const queryClient = useQueryClient();

  const mutation = useMutation({
    mutationFn: (newData) => fetch('/api/user/1', { method: 'POST', body: JSON.stringify(newData) }),
    onSuccess: () => {
      // Başarılı işlem sonrası kullanıcı verisini yeniden çek
      queryClient.invalidateQueries({ queryKey: ['user', 1] });
    },
  });

  return  mutation.mutate({ name: 'Yeni İsim' })}>Güncelle;
}

Güvenlik Uyarısı: API isteklerinde her zaman yetkilendirme (token) başlıklarını kontrol edin. invalidateQueries kullanırken hassas verilerin sunucu tarafında doğrulanmış olduğundan emin olun; sadece önbelleği temizlemek güvenlik sağlamaz.

Gelişmiş Önbellekleme: Prefetching (Önceden Yükleme)

Kullanıcı bir sayfaya gitmeden önce veriyi önbelleğe almak, uygulamanın "anında" tepki vermesini sağlar. prefetchQuery metodu, kullanıcı etkileşimi gerçekleşmeden veriyi arka planda hazırlamak için kullanılır.

const prefetchUser = async () => {
  await queryClient.prefetchQuery({
    queryKey: ['user', 1],
    queryFn: fetchUser,
  });
};

// Örneğin bir linkin üzerine gelindiğinde (onMouseEnter) çağrılabilir.

Sıkça Sorulan Sorular

Önbellek süresi (staleTime) ne kadar olmalı?

Bu, verinizin ne kadar sık değiştiğine bağlıdır. Eğer veriniz saatte bir güncelleniyorsa 3600000ms (1 saat) verebilirsiniz. Çok dinamik veriler için 0 veya birkaç saniye idealdir.

Önbellek boyutu sınırlı mı?

Tanstack Query, varsayılan olarak verileri bellekte tutar. Çok büyük veri setleri için gcTime (garbage collection time) ayarını kullanarak kullanılmayan verilerin bellekten ne zaman temizleneceğini kontrol edebilirsiniz.

Aynı anda birden fazla bileşen aynı veriyi isterse ne olur?

Tanstack Query, aynı queryKey için yapılan tüm istekleri birleştirir (deduplication). Yani, 5 bileşen aynı anda aynı veriyi isterse, ağa sadece tek bir istek gider.

SSR (Sunucu Taraflı İşleme) ile uyumlu mu?

Evet, Next.js gibi framework'lerle tam uyumludur. Veriyi sunucuda çekip önbelleğe (dehydration) aktarabilir, istemci tarafında kaldığı yerden devam edebilirsiniz.

Hata yönetimi nasıl yapılır?

useQuery içinden dönen error nesnesini kullanarak veya QueryCache üzerinde global hata yakalayıcılar tanımlayarak hataları yönetebilirsiniz.

Sorumluluk Reddi: Bu makaledeki kod örnekleri eğitim amaçlıdır. Üretim ortamında (production) kullanırken API uç noktalarınızın güvenliğini (CORS, XSS koruması, Input Validation) sağladığınızdan emin olun. Yazılım güvenliği sorumluluğu geliştiriciye aittir.

Tanstack Query ile İyimser Güncellemeler (Optimistic Updates)

Kullanıcı deneyimini en üst düzeye çıkarmanın yollarından biri, sunucudan yanıt gelmesini beklemeden arayüzü güncellemektir. Tanstack Query, useMutation kancası ile "İyimser Güncelleme" yapmanıza olanak tanır. Bu yöntem, veri henüz veritabanına ulaşmadan kullanıcıya sanki işlem başarılı olmuş gibi geri bildirim verir.

İyimser güncelleme yaparken izlemeniz gereken temel adımlar şunlardır: Mevcut veriyi yedeklemek, önbelleği manuel olarak güncellemek ve hata durumunda veriyi eski haline (rollback) döndürmek.

const queryClient = useQueryClient();

const mutation = useMutation({
  mutationFn: updateTodo,
  onMutate: async (newTodo) => {
    // Mevcut sorguları iptal et (güncelleme ile çakışmaması için)
    await queryClient.cancelQueries({ queryKey: ['todos'] });

    // Önceki veriyi al
    const previousTodos = queryClient.getQueryData(['todos']);

    // Önbelleği iyimser bir şekilde güncelle
    queryClient.setQueryData(['todos'], (old) => [...old, newTodo]);

    // Hata durumunda geri dönmek için context döndür
    return { previousTodos };
  },
  onError: (err, newTodo, context) => {
    // Hata olursa eski veriye dön
    queryClient.setQueryData(['todos'], context.previousTodos);
  },
  onSettled: () => {
    // İşlem bittiğinde veriyi sunucudan tekrar çek
    queryClient.invalidateQueries({ queryKey: ['todos'] });
  },
});

Tanstack Query DevTools ile Hata Ayıklama

Önbellekleme stratejileri karmaşıklaştıkça, hangi verinin "stale" (bayat), hangisinin "fetching" (yükleniyor) durumunda olduğunu takip etmek zorlaşabilir. Tanstack Query'nin sağladığı ReactQueryDevtools, geliştirme sürecinde hayat kurtarıcıdır.

Bu araç, uygulamanızın sağ alt köşesinde bir panel oluşturarak tüm sorguların durumunu canlı olarak izlemenizi sağlar. Hangi sorgunun ne zaman tetiklendiğini, önbellekteki verinin yapısını ve hata detaylarını anlık olarak görebilirsiniz.

DevTools Kurulumu ve Kullanımı

DevTools'u projenize eklemek için şu adımları izleyin:

1. Paketi yükleyin: npm install @tanstack/react-query-devtools
2. Uygulamanızın kök dizininde QueryClientProvider içerisine yerleştirin.

import { ReactQueryDevtools } from '@tanstack/react-query-devtools';

function App() {
  return (
    
      
      {/* DevTools sadece geliştirme ortamında görünür */}
      
    
  );
}

İpucu: DevTools üzerinden belirli bir sorguyu manuel olarak "Invalidate" edebilir veya "Refetch" tetikleyerek verinin nasıl güncellendiğini test edebilirsiniz. Bu, özellikle karmaşık bağımlılıklara sahip sorguların hata ayıklamasında büyük kolaylık sağlar.

Sonuç

React ile Tanstack Query kullanarak veri önbellekleme yapmak, uygulamanızın performansını ve kullanıcı deneyimini bir üst seviyeye taşır. useQuery ile veriyi çekmek, invalidateQueries ile veriyi güncel tutmak ve prefetchQuery ile kullanıcıyı bekletmemek, profesyonel bir React geliştiricisinin temel yetkinliklerindendir. Bir sonraki adım olarak, "Optimistic Updates" (iyimser güncellemeler) konusunu araştırarak kullanıcıya veri sunucuya ulaşmadan önce güncellenmiş gibi göstermeyi öğrenebilirsiniz.