Belajar TanStack Query - Setup & QueryClient

#Pendahuluan

Di episode 2 kalian sudah punya model mental arsitektur. Sekarang saatnya menulis kode sungguhan. Langkah pertama yang benar menentukan kenyamanan semua episode berikutnya: menyiapkan QueryClient sebagai pusat cache, membungkus aplikasi dengan QueryClientProvider, dan mengatur konfigurasi global agar perilaku semua query konsisten sejak awal.

Episode 3 membahas ketiganya secara praktis. Di akhir episode, aplikasi kalian sudah siap menerima hooks useQuery di episode 4.

#Membuat QueryClient

#Instance Pertama

QueryClient adalah wadah cache dan konfigurasi. Biasanya dibuat sekali di level aplikasi dan disimpan di variabel module:

Membuat QueryClient

import { QueryClient } from "@tanstack/react-query"
 
export const queryClient = new QueryClient()

Membuat instance di luar komponen berarti cache dibagikan ke seluruh aplikasi dan tidak dibuat ulang saat render. new QueryClient() di atas menghasilkan instance dengan konfigurasi default bawaan library.

#Default Options

Kalian bisa langsung memberikan default options saat pembuatan. Ini pola yang umum dipakai di aplikasi nyata:

QueryClient dengan default options

import { QueryClient } from "@tanstack/react-query"
 
export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000,
      retry: 2,
      refetchOnWindowFocus: true,
      gcTime: 10 * 60 * 1000,
    },
  },
})

Konfigurasi defaultOptions.queries.staleTime diterapkan ke semua query yang tidak mengatur staleTime-nya sendiri. staleTime: 5 * 60 * 1000 berarti data dianggap segar selama 5 menit.

#Membungkus Aplikasi dengan Provider

#QueryClientProvider

Agar semua hooks bisa mengakses QueryClient, bungkus aplikasi dengan QueryClientProvider. Di project Vite, ini dilakukan di src/main.tsx:

Memasang provider di entry point

import { QueryClientProvider } from "@tanstack/react-query"
import { queryClient } from "./query-client"
import { App } from "./App"
 
function Main() {
  return (
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  )
}

Provider menerima prop client yang berisi instance QueryClient. QueryClientProvider client={queryClient} membuat cache dapat diakses dari komponen mana pun di dalam pohon.

#Satu Provider untuk Satu Root

Aturan sederhana: buat satu QueryClient dan satu QueryClientProvider di root aplikasi. Membuat instance di dalam komponen akan membuat cache baru setiap render — itu bug yang umum dan sering sulit ditemukan.

#Konfigurasi Global yang Sering Dipakai

#staleTime

Mengatur berapa lama data dianggap segar. Nilai 0 (default) membuat data langsung basi setiap kali komponen mount. Untuk aplikasi yang datanya jarang berubah, naikkan ke 30 detik, 5 menit, atau lebih lama. Trade-off-nya: staleTime besar mengurangi jumlah request tapi data bisa ketinggalan dari server.

#retry

Berapa kali query gagal dicoba ulang. Default TanStack Query adalah 3 kali dengan jeda yang meningkat. Untuk operasi read yang penting, pertahankan nilai default; untuk query yang memang sering gagal karena input user, bisa diturunkan ke 1.

#refetchOnWindowFocus

Saat user kembali ke tab browser, TanStack Query secara default me-refetch query yang basi. Ini fitur yang sangat berguna — data selalu segar saat user kembali. Atur ke false jika aplikasi kalian butuh kontrol penuh.

#gcTime

Berapa lama cache bertahan di memori setelah tidak ada observer. Default v5 adalah 5 menit (5 * 60 * 1000). Nilai yang lebih besar membuat data bertahan lebih lama saat berpindah-pindah halaman, dengan harga penggunaan memori.

staleTime           → 0 detik
retry               → 3 kali
refetchOnWindowFocus → true
gcTime              → 5 menit
structuralSharing   → true

Ringkasan staleTime → 0 detik menunjukkan default bawaan v5. Ingat-ingat angka ini karena akan sering kita sebut sebagai baseline di episode-episode berikutnya.

#Menggabungkan Semua

Dengan provider terpasang dan konfigurasi global diatur, struktur akhir aplikasi kalian menjadi:

Struktur setup lengkap

// src/query-client.ts
import { QueryClient } from "@tanstack/react-query"
 
export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000,
      retry: 2,
      refetchOnWindowFocus: true,
      gcTime: 10 * 60 * 1000,
    },
  },
})

Satu file untuk instance dan konfigurasi, satu provider di root, dan seluruh aplikasi siap memakai cache yang konsisten. Pola pemisahan file seperti ini juga menjadi cikal bakal arsitektur folder yang akan kita bahas di episode 21.

#Penutup

Episode 3 menyelesaikan fondasi instalasi: membuat QueryClient dengan default options di module scope, membungkus aplikasi dengan QueryClientProvider, dan memahami konfigurasi global seperti staleTime, retry, refetchOnWindowFocus, serta gcTime.

Inti yang harus dibawa pulang:

• Buat QueryClient sekali di module scope, bukan di dalam komponen.
• Bungkus root aplikasi dengan QueryClientProvider.
• defaultOptions.queries menjadi konfigurasi baseline semua query.
• Default v5: staleTime 0, retry 3, gcTime 5 menit.
• staleTime dan gcTime adalah dua hal yang berbeda dan harus disetel sadar.
• Satu root, satu QueryClient, satu provider.

Di episode 4 selanjutnya kita akan membahas useQuery dasar — membuat query pertama dengan queryKey dan queryFn, membaca status data, isLoading, isError, dan isFetching, serta pola query function yang benar. Di sinilah kalian benar-benar merasakan perbedaan dengan pola useEffect manual.