Belajar TanStack Query - Fitur Stabil Terbaru (v5.x)

#Pendahuluan

TanStack Query v5 dirilis Oktober 2023 dan terus diperbarui sepanjang 2024 sampai 2026. Setiap rilis minor menghadirkan penyempurnaan kecil: perbaikan eslint-plugin-query, refresh dependency, dan penyesuaian terhadap ekosistem yang bergerak cepat seperti React 19.

Episode 20 merangkum fitur-fitur yang membuat v5 stabil dan menyenangkan dipakai: API keyed-object yang seragam, useSuspenseQuery kelas satu, structural sharing, retry default, hingga queryOptions untuk definisi query yang bisa dibagikan. Terakhir, kalian melihat peta rilis v5.101.x dan kabar terbaru seputar Query v6.

#API Keyed-Object yang Seragam

#Satu Objek untuk Semua Hook

Perubahan terbesar v5 adalah penghapusan seluruh overload. useQuery kini selalu menerima satu objek dengan properti queryKey dan queryFn — tidak ada lagi dua bentuk pemanggilan seperti di v4:

API keyed-object di v5

import { useQuery } from "@tanstack/react-query"
 
const { data, isPending, error } = useQuery({
  queryKey: ["todos", id],
  queryFn: () => fetchTodoById(id),
  staleTime: 30 * 1000,
})

Di v4, kalian bisa menulis useQuery(["todos"], fetchTodos) dengan dua argumen terpisah. Di v5, satu objek menjadi satu-satunya cara. queryKey dan queryFn selalu wajib ada, sementara opsi seperti staleTime dan gcTime adalah properti opsional di objek yang sama. Keseragaman ini membuat TypeScript memberi pesan error yang jauh lebih jelas.

#queryOptions untuk Definisi yang Dibagikan

Karena pemanggilan selalu lewat objek, kalian bisa mengekstrak definisi query ke satu tempat dengan queryOptions. Definisi ini aman terhadap tipe dan bisa dipakai ulang oleh useQuery, prefetchQuery, dan getQueryData:

Definisi query dengan queryOptions

import { queryOptions } from "@tanstack/react-query"
 
export const todosOptions = queryOptions({
  queryKey: ["todos"],
  queryFn: fetchTodos,
  staleTime: 5 * 60 * 1000,
})
 
export async function prefetchTodos(client) {
  return client.prefetchQuery(todosOptions)
}

queryOptions membuat satu sumber kebenaran untuk query key dan query function. Kalian tidak perlu menulis ulang queryKey: ["todos"] di hook dan di prefetch — cukup import todosOptions. Ini pola yang sangat direkomendasikan untuk aplikasi berskala tim (dibahas detail di episode 21).

#useSuspenseQuery dan Structural Sharing

#Suspense Kelas Satu

Dukungan Suspense di v4 masih eksperimental; di v5 menjadi fitur kelas satu dengan hook khusus useSuspenseQuery. Berbeda dengan useQuery, hook ini tidak mengembalikan isPending — komponen langsung di-suspend sampai data siap:

Query dengan Suspense

import { Suspense } from "react"
import { useSuspenseQuery } from "@tanstack/react-query"
 
function TodosList() {
  const { data } = useSuspenseQuery({
    queryKey: ["todos"],
    queryFn: fetchTodos,
  })
 
  return <ul>{data.map((todo) => <li key={todo.id}>{todo.title}</li>)}</ul>
}
 
function App() {
  return (
    <Suspense fallback={<p>Memuat data...</p>}>
      <TodosList />
    </Suspense>
  )
}

useSuspenseQuery menghilangkan percabangan loading manual. Saat data belum ada, React melemparkan Suspense boundary terdekat; saat data masuk, komponen di-render dengan data yang sudah pasti tersedia. Tidak ada state kosong yang harus diperiksa.

#Structural Sharing Tetap Jadi Jagoan

structuralSharing di v5 tetap aktif secara default. Ketika queryFn mengembalikan data baru, TanStack Query membandingkan struktur lama dan baru, lalu mempertahankan referensi pada bagian yang tidak berubah. Efeknya: komponen yang di-memo tidak perlu re-render untuk data yang identik, dan useMemo yang bergantung pada referensi objek tetap stabil. Ini salah satu alasan v5 terasa responsif tanpa tuning tambahan.

#Rilis 2026: v5.101.x

#Verifikasi Versi Terkini

Per penulisan episode ini, rilis stabil terbaru adalah v5.101.4 (Juli 2026). Kalian bisa memverifikasi langsung dari registry npm:

npm view @tanstack/react-query version
npm view @tanstack/react-query-devtools version
npm i @tanstack/react-query@latest

Rangkaian v5.101.x berisi perbaikan pada @tanstack/eslint-plugin-query, refresh dependency, dan penyesuaian dukungan React 19. Paket eslint-plugin-query diinstall sebagai dev dependency dan dipasang di konfigurasi ESLint flat:

npm i -D @tanstack/eslint-plugin-query

Konfigurasi ESLint flat

import query from "@tanstack/eslint-plugin-query"
 
export default [
  ...query.configs["flat/recommended"],
  {
    rules: {
      "@tanstack/query/stable-query-client": "error",
      "@tanstack/query/exhaustive-deps": "error",
    },
  },
]

Rule stable-query-client memastikan QueryClient tidak dibuat ulang di dalam komponen, dan exhaustive-deps memastikan semua dependency masuk ke query key. Keduanya menangkap bug caching yang paling sering terjadi sebelum masuk ke code review.

#Retry Default dan Dukungan React 19

Dua perilaku bawaan yang layak diingat: retry default di v5 adalah 3 kali dengan jeda exponential backoff, dan gcTime default adalah 5 menit. Untuk aplikasi React 19, v5 mendukung Concurrent Rendering dan integrasi Suspense dengan baik, termasuk useSuspenseQuery yang memanfaatkan fitur streaming server di Next.js App Router.

#Menuju Query v6

Setelah v5 stabil selama bertahun-tahun, arah pengembangan sudah bergerak ke generasi berikutnya. Query v6 masih dalam pengembangan; salah satu penanda yang paling terlihat adalah paket solid-query@6.0.0-beta yang mulai dirilis sebagai beta. Rilis beta ini memberi gambaran API v6 tanpa mengubah perilaku stabil v5 di ekosistem utama.

Bagi kalian yang baru mulai, tidak perlu menunggu v6. v5.101.x adalah rilis yang stabil, terdokumentasi lengkap, dan dipakai produksi di seluruh dunia. Kemampuan v5 sudah mencakup semua yang dibahas dari episode 0 sampai 19. Migrasi ke v6 nanti, jika diperlukan, akan mengikuti pola yang sudah kalian kuasai sekarang.

#Penutup

Episode 20 menutup gap pengetahuan versi: API keyed-object dan queryOptions membuat definisi query seragam dan bisa dibagikan, useSuspenseQuery menyederhanakan loading, dan rilis v5.101.x membawa perbaikan eslint-plugin-query serta dukungan React 19 yang matang.

Inti yang harus dibawa pulang:

• useQuery di v5 selalu menerima satu objek dengan queryKey dan queryFn.
• queryOptions menyatukan definisi query untuk hook, prefetch, dan cache.
• useSuspenseQuery meniadakan state loading manual.
• structuralSharing aktif secara default dan mempertahankan referensi data.
• retry default adalah 3 kali dengan exponential backoff.
• v5.101.x stabil per Juli 2026; Query v6 masih beta di ekosistem Solid.

Di episode 21 selanjutnya kita akan membahas production-ready architecture — struktur folder query modules, katalog query keys, custom hooks per domain, monitoring, bundle size, SSR tuning, dan runbook caching serta invalidasi untuk skala tim.