Kurulum ve devtools

Kurulum

React rehberindeki gibi bir Vite projesi açın ve paketi ekleyin:¹

$ pnpm add @tanstack/react-query

Paket React 18 ve sonrasıyla çalışır. TypeScript tarafında son iki yılda çıkan sürümleri destekler; şu an TypeScript 5.7 ve sonrası.¹²

QueryClient ve Provider

Cache, bir QueryClient örneğinin içinde yaşar. Bu örneği uygulamanın tepesinde QueryClientProvider ile verirsiniz; altındaki her component aynı cache'e erişir:¹

// src/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import App from "./App.tsx";

const queryClient = new QueryClient();

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  </StrictMode>,
);

QueryClient'ı component'in dışında oluşturun. Component içinde new QueryClient() yazarsanız her render'da cache sıfırlanır. Component içinde oluşturmanız gerekiyorsa (ör. testler, sunucu) useState(() => new QueryClient()) kullanın.³

Şaşırtan Varsayılanlar

TanStack Query hiçbir ayar yapmadan çalışır ama varsayılanları veriyi güncel tutmaya göre seçilmiştir, istek sayısını azaltmaya göre değil.⁴⁵ İlk kullanımda şaşırtan davranışların çoğu bunlardan gelir:⁴

TkDodo'nun hatırlattığı ilk nokta: staleTime: 0 olsa bile queryFn her render'da çalışmaz. Beklemediğiniz bir istek gördüyseniz büyük ihtimalle sekmeye geri döndünüz.⁵ Geliştirirken DevTools ile uygulama arasında gidip gelmek de sekme değişikliği sayılır. v5'ten beri yalnızca visibilitychange olayı dinlendiği için bu eskisinden daha seyrektir.⁵

İkinci nokta: hata ekranı üç tekrar bitene kadar gelmez. Geliştirirken "hata neden geç görünüyor" sorusunun cevabı budur.⁴ Testlerde retry: false ayarı için Provider ve hook testi dersine bakın.

Varsayılanları tüm uygulama için defaultOptions ile değiştirirsiniz. En sık değiştirilen staleTime'dır:⁴⁶

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 60 * 1000, // 1 dakika boyunca istek atma
    },
  },
});

staleTime ve gcTime farkı Cache ve stale time dersinin konusu.

Devtools

Devtools ayrı bir pakettir. Cache'teki her sorguyu, anahtarını, durumunu ve verisini gösterir; mutation'ları da izler:⁷

$ pnpm add @tanstack/react-query-devtools

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

<QueryClientProvider client={queryClient}>
  <App />
  <ReactQueryDevtools initialIsOpen={false} />
</QueryClientProvider>;

Ekranın köşesine bir TanStack logosu gelir; tıklayınca panel açılır. Panel yalnızca NODE_ENV === "development" olduğunda bundle'a girer; production build'den kendiliğinden çıkar.⁷ Chrome, Firefox ve Edge için aynı paneli tarayıcının DevTools'una ekleyen eklentiler de var.⁷

TkDodo Devtools'u öğrenmenin en hızlı yolu olarak önerir: bir sorgunun ne zaman fresh, ne zaman stale, ne zaman inactive olduğunu canlı görürsünüz.⁶ Panelden bir sorguyu elle yenileyebilir, geçersiz kılabilir ya da hata durumuna sokabilirsiniz.

ESLint Eklentisi

Doküman kurulumla birlikte resmi lint eklentisini de önerir. Gözden kaçan hataların çoğunu yazarken yakalar:¹⁸

$ pnpm add -D @tanstack/eslint-plugin-query

// eslint.config.js
import pluginQuery from "@tanstack/eslint-plugin-query";

export default [
  ...pluginQuery.configs["flat/recommended"],
  // diğer ayarlar
];

recommended setindeki kurallar:⁸⁹

flat/recommended-strict buna prefer-query-options kuralını ekler; sorgu ayarlarını queryOptions ile yazmaya zorlar.⁸

Vite şablonu ESLint yerine Oxlint ve bir .oxlintrc.json ile gelir. Eklenti Oxlint'in JS plugin desteğiyle de çalışır; bu destek şu an alfa aşamasında. JSON dosyası eklentinin hazır setini içe aktaramaz, kuralları tek tek yazarsınız:⁸

// .oxlintrc.json
{
  "plugins": ["react", "typescript", "oxc"],
  "jsPlugins": ["@tanstack/eslint-plugin-query"],
  "rules": {
    "react/rules-of-hooks": "error",
    "@tanstack/query/exhaustive-deps": "error",
    "@tanstack/query/stable-query-client": "error",
    "@tanstack/query/no-rest-destructuring": "warn",
    "@tanstack/query/no-unstable-deps": "error",
    "@tanstack/query/infinite-query-property-order": "error",
    "@tanstack/query/mutation-property-order": "error"
  }
}

no-void-query-fn tip bilgisine ihtiyaç duyar; Oxlint bunu JS eklentilerine henüz vermediği için listede yok.⁸

Sürümü Sabitlemek

Tip düzeltmeleri patch sürümlerinde çıkar; doküman bunları kırıcı değişiklik saymaz. Bu yüzden paketi belirli bir patch sürümüne sabitlemeyi ve güncellerken tiplerin değişebileceğini beklemeyi önerir.² Lock dosyası (package-lock.json, pnpm-lock.yaml) commit'lenmişse bu zaten sağlanır.

Kendin Dene

• QueryClient'ı App component'inin içine taşıyın. ESLint ya da Oxlint hangi kuralla uyarıyor?

• Bir sorgu yazın ve Devtools'u açın. Başka bir sekmeye geçip dönün; sorgunun durumu nasıl değişiyor?

• queryFn'i her zaman hata fırlatan bir fonksiyona çevirin. Hata ekranı kaç saniye sonra geliyor? retry: false ile tekrar deneyin.

Detaylı Öğrenmek İçin

• Resmi doküman: "Important Defaults"; her varsayılanın nasıl değiştirileceği ve staleTime: 'static' ile Infinity farkı.⁴

• Yazı: TkDodo, "Practical React Query"; varsayılanların açıklaması, Devtools ve custom hook önerisi.⁶

• Resmi doküman: "ESLint Plugin Query"; her kuralın doğru ve yanlış örnekleri.⁸