Data fetching di React selalu jadi topik yang tricky. Kamu pakai `useEffect` untuk fetch data, handle loading state, handle error, handle refetch, cache hasilnya, sinkronisasi antar komponen. Belum lagi kalau ada mutation yang butuh update cache. Kalau kamu pernah nulis boilerplate ini berulang kali, TanStack Query (dulu React Query) adalah solusi yang tepat. TanStack Query adalah library untuk manajemen state async di React (dan framework lain seperti Vue, Svelte, Solid). Library ini menangani caching, background refetching, deduplication, dan synchronization secara otomatis sehingga kamu bisa fokus ke business logic. ## Setup Dasar ```bash npm install @tanstack/react-query # atau pnpm add @tanstack/react-query ``` Bungkus aplikasi kamu dengan `QueryClientProvider`: ```typescript // src/App.tsx import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; import { ReactQueryDevtools } from "@tanstack/react-query-devtools"; import { useState } from "react"; function App() { const [queryClient] = useState( () => new QueryClient({ defaultOptions: { queries: { staleTime: 1000 * 60 * 5, // 5 menit gcTime: 1000 * 60 * 30, // 30 menit (dulu cacheTime) retry: 2, refetchOnWindowFocus: true, }, }, }) ); return ( ); } export default App; ``` Konfigurasi default penting untuk dipahami: - **staleTime**: berapa lama data dianggap fresh. Selama fresh, query tidak bakal refetch. - **gcTime** (garbage collection): berapa lama data disimpan di cache setelah tidak ada komponen yang pakai. - **retry**: jumlah retry kalau fetch gagal. - **refetchOnWindowFocus**: otomatis refetch saat user kembali ke tab. ## useQuery: Membaca Data `useQuery` adalah hook utama untuk fetching data. Hook ini memberi kamu state loading, error, data, dan berbagai utility. ```typescript // src/api/users.ts import { QueryClient, useQuery } from "@tanstack/react-query"; interface User { id: number; name: string; email: string; avatar: string; } // Fetch function async function fetchUsers(): Promise { const res = await fetch("/api/users"); if (!res.ok) throw new Error("Gagal fetch users"); return res.json(); } // Custom hook export function useUsers() { return useQuery({ queryKey: ["users"], queryFn: fetchUsers, }); } // Custom hook dengan parameter async function fetchUser(id: number): Promise { const res = await fetch(`/api/users/${id}`); if (!res.ok) throw new Error(`Gagal fetch user ${id}`); return res.json(); } export function useUser(id: number) { return useQuery({ queryKey: ["users", id], queryFn: () => fetchUser(id), enabled: !!id, // Hanya fetch kalau id ada }); } ``` Pakai hook di komponen: ```typescript // src/components/UserList.tsx import { useUsers } from "../api/users"; export function UserList() { const { data, isLoading, error, isFetching, refetch } = useUsers(); if (isLoading) { return

Loading users...

; } if (error) { return (

Error: {error.message}

); } return (

Daftar User {isFetching && (updating...)}

{user.name} - {user.email}

); } ``` ### Loading vs Fetching Penting untuk bedakan `isLoading` dan `isFetching`: - `isFetching`: true saat ada request berjalan, baik fetch pertama atau background refetch. - `isLoading`: true hanya saat fetch pertama dan belum ada data di cache. ```typescript function SmartUserList() { const { data, isLoading, isFetching } = useUsers(); // Skeleton saat loading pertama if (isLoading) return ; // Data sudah ada tapi sedang refetch di background return (

{data?.map((user) => ( ))}

); } ``` ### Query dengan Parameter dinamis ```typescript // Search dengan debounce function useSearchUsers(query: string) { return useQuery({ queryKey: ["users", "search", query], queryFn: async () => { const res = await fetch(`/api/users?q=${encodeURIComponent(query)}`); return res.json(); }, enabled: query.length > 2, // Hanya search kalau > 2 karakter staleTime: 1000 * 60 * 2, // Cache 2 menit }); } function SearchBar() { const [query, setQuery] = useState(""); const debouncedQuery = useDebounce(query, 300); const { data, isLoading } = useSearchUsers(debouncedQuery); return (

setQuery(e.target.value)} placeholder="Cari user..." /> {isLoading &&

Mencari...

} {data?.map((user) => (

{user.name}

))}

); } ``` ## Query Keys: Kunci Caching Query key adalah pondasi dari sistem caching TanStack Query. Key ini menentukan identitas dan hierarchy cache. Key bisa berupa string, array, atau struktur kompleks. ```typescript // Key sederhana useQuery({ queryKey: ["users"], queryFn: fetchUsers }); // Key dengan parameter useQuery({ queryKey: ["users", userId], queryFn: () => fetchUser(userId) }); // Key dengan objek filter useQuery({ queryKey: ["users", { status: "active", role: "admin", page: 1 }], queryFn: () => fetchUsers({ status: "active", role: "admin", page: 1 }), }); // Hierarki key useQuery({ queryKey: ["projects", projectId, "tasks", taskId], ... }); ``` Aturan penting untuk query key: 1. Key harus unik untuk setiap query yang berbeda. 2. Key harus deskriptif dan menggambarkan data. 3. Gunakan array dengan struktur hierarkis. ```typescript // GOOD queryKey: ["users", userId] // ["users", 123] queryKey: ["users", "list", { page: 1, filter: "active" }] queryKey: ["projects", "task", taskId] // BAD - terlalu generik queryKey: "data" queryKey: ["q1"] ``` ### Invalidasi Berdasarkan Key Prefix Salah satu kekuatan utama query key adalah kemampuan untuk invalidate sekelompok query dengan prefix: ```typescript // Invalidate semua query yang key-nya mulai dengan ["users"] queryClient.invalidateQueries({ queryKey: ["users"] }); // Ini bakal invalidate: // ["users"] // ["users", 123] // ["users", { page: 1 }] // ["users", "search", "budi"] // Semua yang prefix-nya ["users"] ``` ## useMutation: Mengubah Data `useMutation` digunakan untuk operasi yang mengubah data: create, update, delete. Berbeda dengan `useQuery`, mutation tidak otomatis dijalankan saat komponen mount. ```typescript // src/api/mutations.ts import { useMutation, useQueryClient } from "@tanstack/react-query"; // Create user async function createUser(data: { name: string; email: string; }): Promise { const res = await fetch("/api/users", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(data), }); if (!res.ok) throw new Error("Gagal membuat user"); return res.json(); } export function useCreateUser() { const queryClient = useQueryClient(); return useMutation({ mutationFn: createUser, onSuccess: () => { // Invalidate list users agar refetch queryClient.invalidateQueries({ queryKey: ["users"] }); }, onError: (error) => { console.error("Mutation error:", error); }, }); } // Update user async function updateUser({ id, data, }: { id: number; data: Partial; }): Promise { const res = await fetch(`/api/users/${id}`, { method: "PATCH", headers: { "Content-Type": "application/json" }, body: JSON.stringify(data), }); if (!res.ok) throw new Error("Gagal update user"); return res.json(); } export function useUpdateUser() { const queryClient = useQueryClient(); return useMutation({ mutationFn: updateUser, onSuccess: (updatedUser) => { // Update cache individual queryClient.setQueryData(["users", updatedUser.id], updatedUser); // Invalidate list agar konsisten queryClient.invalidateQueries({ queryKey: ["users"] }); }, }); } // Delete user export function useDeleteUser() { const queryClient = useQueryClient(); return useMutation({ mutationFn: async (id: number) => { const res = await fetch(`/api/users/${id}`, { method: "DELETE" }); if (!res.ok) throw new Error("Gagal hapus user"); }, onSuccess: () => { queryClient.invalidateQueries({ queryKey: ["users"] }); }, }); } ``` Pakai mutation di komponen: ```typescript // src/components/CreateUserForm.tsx import { useState } from "react"; import { useCreateUser } from "../api/mutations"; export function CreateUserForm() { const [name, setName] = useState(""); const [email, setEmail] = useState(""); const createUser = useCreateUser(); const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); createUser.mutate( { name, email }, { onSuccess: () => { setName(""); setEmail(""); alert("User berhasil dibuat!"); }, onError: (error) => { alert(`Error: ${error.message}`); }, } ); }; return ( ); } ``` ## Cache Invalidation: Menjaga Data Tetap Segar Invalidation adalah cara untuk memberitahu TanStack Query bahwa data di cache sudah tidak valid dan perlu di-refetch. Ada beberapa strategi: ```typescript const queryClient = useQueryClient(); // 1. Invalidate semua query queryClient.invalidateQueries(); // 2. Invalidate berdasarkan prefix queryClient.invalidateQueries({ queryKey: ["users"] }); // 3. Invalidate query spesifik queryClient.invalidateQueries({ queryKey: ["users", "list", { page: 1 }], }); // 4. Invalidate dengan predicate function queryClient.invalidateQueries({ predicate: (query) => query.queryKey[0] === "users" && query.queryKey[1] !== "deleted", }); // 5. Refetch specific query await queryClient.refetchQueries({ queryKey: ["users"] }); // 6. Remove query dari cache queryClient.removeQueries({ queryKey: ["users", "old"] }); ``` ### Pattern Invalidation Setelah Mutation ```typescript function useCreatePost() { const queryClient = useQueryClient(); return useMutation({ mutationFn: createPost, onSuccess: (newPost) => { // Strategy 1: Invalidate list queryClient.invalidateQueries({ queryKey: ["posts", "list"] }); // Strategy 2: Update cache secara manual (lebih cepat) queryClient.setQueryData(["posts", "list"], (old) => { return [...(old ?? []), newPost]; }); }, }); } ``` ## Optimistic Updates Optimistic update adalah teknik di mana kamu update UI sebelum konfirmasi dari server. Ini membuat aplikasi terasa sangat responsif. Kalau ternyata gagal, kamu rollback perubahan. ```typescript export function useUpdateTodoOptimistic() { const queryClient = useQueryClient(); return useMutation({ mutationFn: updateTodo, // Update UI sebelum request selesai onMutate: async (updatedTodo) => { // Cancel outgoing refetches supaya tidak overwrite optimistic update await queryClient.cancelQueries({ queryKey: ["todos"] }); // Snapshot data lama untuk rollback const previousTodos = queryClient.getQueryData(["todos"]); // Optimistic update queryClient.setQueryData(["todos"], (old) => { return old?.map((todo) => todo.id === updatedTodo.id ? { ...todo, ...updatedTodo } : todo ); }); // Return context untuk rollback return { previousTodos }; }, // Kalau error, rollback onError: (err, updatedTodo, context) => { queryClient.setQueryData(["todos"], context?.previousTodos); }, // Selalu refetch setelah sukses atau gagal onSettled: () => { queryClient.invalidateQueries({ queryKey: ["todos"] }); }, }); } ``` Pakai di komponen: ```typescript function TodoItem({ todo }: { todo: Todo }) { const updateTodo = useUpdateTodoOptimistic(); const handleToggle = () => { // UI langsung update, tidak ada loading state updateTodo.mutate({ id: todo.id, completed: !todo.completed, }); }; return (

{todo.title}

); } ``` ### Optimistic Update untuk List Tambah/Hapus ```typescript // Tambah item optimistically function useAddTodoOptimistic() { const queryClient = useQueryClient(); return useMutation({ mutationFn: addTodo, onMutate: async (newTodo) => { await queryClient.cancelQueries({ queryKey: ["todos"] }); const previous = queryClient.getQueryData(["todos"]); // Tambah dengan temporary ID dan flag queryClient.setQueryData(["todos"], (old) => [ ...(old ?? []), { ...newTodo, id: `temp-${Date.now()}`, _optimistic: true }, ]); return { previous }; }, onError: (err, newTodo, context) => { queryClient.setQueryData(["todos"], context?.previous); }, onSuccess: (realTodo, newTodo, context) => { // Replace temp dengan real data queryClient.setQueryData(["todos"], (old) => { return old?.map((todo) => todo.id === `temp-${Date.now()}` ? realTodo : todo ); }); }, onSettled: () => { queryClient.invalidateQueries({ queryKey: ["todos"] }); }, }); } // Hapus item optimistically function useDeleteTodoOptimistic() { const queryClient = useQueryClient(); return useMutation({ mutationFn: deleteTodo, onMutate: async (deletedId) => { await queryClient.cancelQueries({ queryKey: ["todos"] }); const previous = queryClient.getQueryData(["todos"]); queryClient.setQueryData(["todos"], (old) => old?.filter((todo) => todo.id !== deletedId) ); return { previous }; }, onError: (err, deletedId, context) => { // Restore data kalau gagal hapus queryClient.setQueryData(["todos"], context?.previous); }, onSettled: () => { queryClient.invalidateQueries({ queryKey: ["todos"] }); }, }); } ``` ## Infinite Queries: Pagination dan Infinite Scroll `useInfiniteQuery` digunakan untuk pagination atau infinite scroll. Hook ini mengelola multiple pages secara otomatis. ```typescript import { useInfiniteQuery } from "@tanstack/react-query"; interface Article { id: number; title: string; excerpt: string; } interface ArticleResponse { data: Article[]; nextPage: number | null; hasMore: boolean; } async function fetchArticles({ pageParam = 1 }): Promise { const res = await fetch(`/api/articles?page=${pageParam}&limit=10`); if (!res.ok) throw new Error("Gagal fetch articles"); return res.json(); } export function useArticlesInfinite() { return useInfiniteQuery({ queryKey: ["articles", "infinite"], queryFn: fetchArticles, initialPageParam: 1, getNextPageParam: (lastPage) => lastPage.nextPage, getPreviousPageParam: (firstPage, allPages, firstPageParam) => { return firstPageParam > 1 ? firstPageParam - 1 : undefined; }, }); } ``` Pakai dengan infinite scroll: ```typescript // src/components/ArticleFeed.tsx import { useArticlesInfinite } from "../api/articles"; import { useEffect, useRef } from "react"; export function ArticleFeed() { const { data, error, fetchNextPage, hasNextPage, isFetchingNextPage, isLoading, } = useArticlesInfinite(); const sentinelRef = useRef(null); // Intersection Observer untuk auto-load saat scroll useEffect(() => { const sentinel = sentinelRef.current; if (!sentinel) return; const observer = new IntersectionObserver( (entries) => { if (entries[0].isIntersecting && hasNextPage) { fetchNextPage(); } }, { threshold: 1 } ); observer.observe(sentinel); return () => observer.disconnect(); }, [fetchNextPage, hasNextPage]); if (isLoading) return

Loading articles...

; if (error) return

Error: {error.message}

; // Flatten pages jadi satu array const articles = data.pages.flatMap((page) => page.data); return (

{articles.map((article) => (

{article.title}

{article.excerpt}

))} {/* Sentinel element */}

{isFetchingNextPage &&

Loading more...

} {!hasNextPage &&

Tidak ada artikel lagi.

}

); } ``` ### Pagination dengan Load More Button ```typescript function PaginatedList() { const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useArticlesInfinite(); const articles = data.pages.flatMap((page) => page.data); return (

{articles.map((article) => ( ))} {hasNextPage && ( )}

); } ``` ## Prefetching: Load Data Sebelum Dibutuhkan Prefetching membuat aplikasi terasa instan. Kamu bisa prefetch data saat user hover link atau sebelum navigasi. ```typescript // Prefetch saat hover function ArticleLink({ articleId }: { articleId: number }) { const queryClient = useQueryClient(); const handleMouseEnter = () => { queryClient.prefetchQuery({ queryKey: ["articles", articleId], queryFn: () => fetchArticle(articleId), staleTime: 1000 * 60, // 1 menit }); }; return ( Baca artikel ); } ``` ### Prefetch di Server Component (Next.js) ```typescript // app/articles/page.tsx (Server Component) import { QueryClient, HydrationBoundary, dehydrate } from "@tanstack/react-query"; export default async function ArticlesPage() { const queryClient = new QueryClient(); await queryClient.prefetchQuery({ queryKey: ["articles"], queryFn: fetchArticles, }); return ( ); } ``` ## Suspense Integration TanStack Query mendukung React Suspense: ```typescript import { useSuspenseQuery } from "@tanstack/react-query"; // Component yang pakai suspense function UserDetail({ userId }: { userId: number }) { const { data } = useSuspenseQuery({ queryKey: ["users", userId], queryFn: () => fetchUser(userId), }); // data selalu ada di sini (suspense handle loading) return

{data.name}

; } // Parent component function App() { return ( }> ); } ``` ## Custom Hooks Pattern Bikin custom hooks yang reusable dan type-safe: ```typescript // src/hooks/queries.ts import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"; // ==================== PRODUCTS ==================== export const productKeys = { all: ["products"] as const, lists: () => [...productKeys.all, "list"] as const, list: (filters: { category?: string; sort?: string }) => [...productKeys.lists(), filters] as const, details: () => [...productKeys.all, "detail"] as const, detail: (id: number) => [...productKeys.details(), id] as const, }; export function useProducts(filters: { category?: string; sort?: string }) { return useQuery({ queryKey: productKeys.list(filters), queryFn: () => fetchProducts(filters), }); } export function useProduct(id: number) { return useQuery({ queryKey: productKeys.detail(id), queryFn: () => fetchProduct(id), enabled: !!id, }); } export function useCreateProduct() { const qc = useQueryClient(); return useMutation({ mutationFn: createProduct, onSuccess: () => { qc.invalidateQueries({ queryKey: productKeys.lists() }); }, }); } export function useUpdateProduct() { const qc = useQueryClient(); return useMutation({ mutationFn: updateProduct, onMutate: async (updated) => { await qc.cancelQueries({ queryKey: productKeys.detail(updated.id) }); const previous = qc.getQueryData(productKeys.detail(updated.id)); qc.setQueryData(productKeys.detail(updated.id), updated); return { previous }; }, onError: (err, updated, context) => { qc.setQueryData(productKeys.detail(updated.id), context?.previous); }, onSettled: (data) => { qc.invalidateQueries({ queryKey: productKeys.detail(data.id) }); qc.invalidateQueries({ queryKey: productKeys.lists() }); }, }); } ``` Pola `queryKeys` factory ini membuat key management jadi rapi dan terhindar dari typo. ## DevTools TanStack Query Devtools adalah alat yang sangat membantu untuk debugging. Tampilkan panel yang menunjukkan semua queries, status-nya, data, dan timing. ```typescript import { ReactQueryDevtools } from "@tanstack/react-query-devtools"; function App() { return ( {/* Auto-excluded di production build */} ); } ``` Di DevTools kamu bisa melihat: - Semua query keys dan datanya - Status setiap query (fresh, stale, fetching, inactive) - Timeline kapan query di-fetch - Ability untuk invalidate atau refetch manual ## Best Practices 1. **Pakai staleTime yang tepat**. Default 0 berarti selalu refetch, yang mungkin berlebihan. Set ke beberapa menit untuk data yang jarang berubah. 2. **Struktur query key dengan baik**. Pakai factory pattern agar konsisten dan mudah invalidate. 3. **Handle error di tempat yang tepat**. `onError` di `useMutation` global, atau di callback `mutate` untuk per-komponen. 4. **Prefetch untuk UX yang cepat**. Hover link, pre-load next page, prefetch saat idle. 5. **Jangan pakai query untuk data yang tidak async**. Local state pakai `useState` atau `useReducer`. 6. **Gunakan `select` untuk transform data**. Jangan transform di render. ```typescript const { data } = useQuery({ queryKey: ["users"], queryFn: fetchUsers, select: (users) => users .filter((u) => u.active) .sort((a, b) => a.name.localeCompare(b.name)) .map((u) => ({ ...u, displayName: `${u.name} (${u.role})` })), }); ``` ## Kesimpulan TanStack Query mengubah cara kita menangani data async di React. Dengan caching otomatis, background refetching, deduplication, dan API yang ergonomis, kamu tidak perlu lagi nulis boilerplate `useEffect` + `useState` untuk setiap data fetch. Kombinasi `useQuery` untuk baca, `useMutation` untuk tulis, query key hierarchy untuk caching, invalidation untuk sinkronisasi, dan optimistic update untuk UX yang instan membuat aplikasi React kamu terasa cepat dan reliable. Mulai dari install, setup provider, dan ganti satu `useEffect` fetch dengan `useQuery`. Rasakan sendiri bedanya. ```bash npm install @tanstack/react-query ``` Selamat coding!