Client-side Cache trong React với TanStack Query
TanStack Query như một client-side server-state cache: cache API, deduplicate request, tự refetch, quản lý loading/error.
Tập trung vào cách hiểu đơn giản và ứng dụng thực tế của TanStack Query trong React, đặc biệt là client-side cache.
TL;DR: @tanstack/react-query không chỉ là thư viện gọi API. Nó có thể đóng vai trò như một client-side server-state cache, giúp cache dữ liệu API, tránh request lặp lại, tự refetch khi cần và quản lý trạng thái loading/error rất tiện lợi.
Vấn đề: Request API trùng lặp#
Khi xây dựng một ứng dụng React, chúng ta thường gặp một vấn đề khá phổ biến:
API trả về dữ liệu rồi, vậy lần sau có cần gọi API lại không?
Ví dụ một trang có API:
GET /api/users/123textNếu component A gọi API này, sau đó component B cũng cần thông tin user 123, cách làm truyền thống có thể khiến cả hai component đều gọi API.
Điều này tạo ra request dư thừa.
Một giải pháp là tự xây dựng cache:
const cache = new Map()tsNhưng khi ứng dụng lớn lên, việc tự quản lý cache sẽ nhanh chóng trở nên phức tạp.
Đây là lúc TanStack Query trở nên hữu ích.
TanStack Query là gì?#
TanStack Query, trước đây thường được biết đến với tên React Query, là thư viện chuyên quản lý server state trong frontend.
Package dành cho React là:
npm install @tanstack/react-querybashĐiểm quan trọng là:
TanStack Query không đơn thuần là một thư viện
fetch()API.
Nó cung cấp một hệ thống để:
- fetch data
- cache data
- deduplicate request
- refetch data
- retry request
- quản lý loading/error
- invalidate cache
- optimistic update
- pagination
- infinite query
- background refetch
Server State và Client State khác nhau thế nào?#
Đây là khái niệm quan trọng nhất để hiểu TanStack Query.
Client State#
Là state thuộc về UI/application.
Ví dụ:
const [isOpen, setIsOpen] = useState(false)tsxHoặc:
const [theme, setTheme] = useState("dark")tsxDữ liệu này thuộc về frontend.
Server State#
Là dữ liệu đến từ backend.
Ví dụ:
{
"id": 123,
"name": "John",
"email": "john@example.com"
}jsonFrontend không thực sự sở hữu dữ liệu này.
Backend mới là nguồn dữ liệu chính.
TanStack Query được thiết kế chủ yếu để giải quyết loại state này.
[!NOTE] ELI5: Client State giống như công tắc đèn trong nhà bạn — bạn toàn quyền bật/tắt. Server State giống như thời tiết ngoài trời — bạn chỉ có thể “xem” qua cửa sổ (API), không sở hữu nó, và nó có thể thay đổi bất cứ lúc nào.
Không nên nhầm TanStack Query với Redux#
Một cách hiểu đơn giản:
Redux/Zustand
↓
Client State
TanStack Query
↓
Server StatetextVí dụ:
{
sidebarOpen: true,
theme: "dark"
}tsphù hợp với Zustand/Redux.
Trong khi:
{
users: [...],
posts: [...],
products: [...],
profile: {...}
}tsnếu dữ liệu đến từ API thì TanStack Query thường phù hợp hơn.
Tất nhiên hai loại state có thể cùng tồn tại trong một ứng dụng.
Cache hoạt động như thế nào?#
Ví dụ:
const { data } = useQuery({
queryKey: ["user", userId],
queryFn: () => fetchUser(userId),
})tsxTanStack Query sử dụng:
queryKeytsđể xác định dữ liệu nào đang được cache.
Ví dụ:
["user", 123]textvà:
["user", 456]textlà hai cache entry khác nhau.
Có thể hình dung:
Query Cache
"user", 123
↓
{ id: 123, name: "John" }
"user", 456
↓
{ id: 456, name: "Alice" }
"posts", 123
↓
[ ... ]text[!TIP] Hãy nghĩ
queryKeynhư mã số tủ đồ ở siêu thị: mỗi key mở đúng một ngăn chứa dữ liệu. Key khác nhau → ngăn khác nhau, không bao giờ lẫn lộn.
Ví dụ cơ bản#
Đầu tiên tạo QueryClient.
import {
QueryClient,
QueryClientProvider,
} from "@tanstack/react-query"
const queryClient = new QueryClient()
export function App() {
return (
<QueryClientProvider client={queryClient}>
<MyApp />
</QueryClientProvider>
)
}tsxSau đó sử dụng query:
import { useQuery } from "@tanstack/react-query"
function UserProfile({ userId }: { userId: number }) {
const { data, isPending, error } = useQuery({
queryKey: ["user", userId],
queryFn: () => fetch(`/api/users/${userId}`).then(res => res.json()),
})
if (isPending) {
return <div>Loading...</div>
}
if (error) {
return <div>Error</div>
}
return <div>{data.name}</div>
}tsxĐiểm đáng chú ý là:
queryKey: ["user", userId]tschính là identity của cache.
[!NOTE] Từ TanStack Query v5, trạng thái loading ban đầu là
isPending(thay choisLoadingở v4), vàcacheTimeđược đổi tên thànhgcTime. Các ví dụ trong bài dùng API v5.
Khi component thứ hai gọi cùng API#
Giả sử có:
<UserProfile userId={123} />tsxở component A.
Sau đó component B cũng sử dụng:
<UserProfile userId={123} />tsxTanStack Query biết rằng:
["user", 123]textđã tồn tại trong Query Cache.
Vì vậy component B thấy dữ liệu có sẵn ngay lập tức thay vì hiện màn hình loading trắng.
Đây là một trong những điểm mạnh lớn của TanStack Query.
[!NOTE] Mặc định
staleTimelà0, nghĩa là dữ liệu cache được coi là stale ngay lập tức. Component B vẫn thấy dữ liệu cũ ngay tức thì (không loading), đồng thời TanStack Query refetch ngầm dưới nền để cập nhật — pattern này gọi là stale-while-revalidate.
Request Deduplication#
Một tình huống rất thường gặp:
Component A ─┐
│
Component B ─┼──→ GET /api/user/123
│
Component C ─┘textNếu cả ba component cùng mount gần như đồng thời, bạn không muốn gửi:
GET /api/user/123
GET /api/user/123
GET /api/user/123textTanStack Query có cơ chế chia sẻ/deduplicate request dựa trên query key.
Về mặt concept:
staleTime – dữ liệu được xem là cũ sau bao lâu?#
Đây là một option rất quan trọng.
Ví dụ:
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
staleTime: 60_000,
})tsxCó nghĩa là dữ liệu được coi là fresh trong 60 giây.
Trong khoảng thời gian đó, nếu component khác sử dụng:
["users"]tsTanStack Query có thể sử dụng cache hiện tại thay vì refetch ngay lập tức.
Ví dụ:
00s API request
↓
cache
10s component B
↓
dùng cache
30s component C
↓
dùng cache
60s cache trở thành staletextstaleTime không phải thời gian xóa cache#
Đây là một nhầm lẫn rất phổ biến.
Ví dụ:
staleTime: 60_000tskhông có nghĩa:
Sau 60 giây cache bị xóa.
Nó chỉ có nghĩa:
Sau 60 giây, dữ liệu được coi là stale.
Dữ liệu vẫn có thể nằm trong cache.
[!WARNING] Nhầm lẫn phổ biến nhất khi học TanStack Query:
staleTimelà “dữ liệu còn tươi bao lâu”, KHÔNG phải “cache tồn tại bao lâu”. HếtstaleTimethì dữ liệu chỉ bị đánh dấu cũ — lần dùng tiếp theo sẽ refetch ngầm, chứ cache không bị xóa.
gcTime#
TanStack Query còn có:
gcTimetstrước đây thường được gọi là:
cacheTimetextNó liên quan đến thời gian dữ liệu không còn được sử dụng trước khi được garbage collect.
Ví dụ:
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
staleTime: 60_000,
gcTime: 5 * 60_000,
})tsxCó thể hiểu đơn giản:
staleTime
↓
Bao lâu dữ liệu được xem là fresh?
gcTime
↓
Bao lâu cache inactive được giữ lại?textHai khái niệm này khác nhau.
[!NOTE] Mặc định:
staleTimelà0(stale ngay),gcTimelà 5 phút (giữ cache inactive 5 phút sau khi component cuối cùng unmount). Hai con số này giải thích hầu hết hành vi “lạ” mà người mới gặp phải.
Một cấu hình thực tế#
Ví dụ API sản phẩm:
const productsQuery = useQuery({
queryKey: ["products"],
queryFn: fetchProducts,
staleTime: 5 * 60 * 1000,
gcTime: 30 * 60 * 1000,
})tsxCó thể hiểu:
5 phút
↓
data được xem là fresh
30 phút
↓
inactive cache có thể được garbage collecttextĐiều này đặc biệt hữu ích với những dữ liệu ít thay đổi.
Ví dụ:
- danh sách quốc gia
- category
- school list
- configuration
- product catalog
- master data
[!TIP] Quy tắc ngón tay cái: dữ liệu càng ít thay đổi thì
staleTimecàng dài. Danh sách quốc gia có thể đểstaleTime: Infinity; bảng giá realtime thì để vài giây hoặc dùng refetch interval.
Cache không có nghĩa là dữ liệu luôn mới#
Đây là điểm rất quan trọng.
Giả sử:
Backend
↓
User name = "John"textFrontend cache:
User name = "John"textSau đó server thay đổi:
Backend
↓
User name = "Mike"textCache phía frontend vẫn có thể đang chứa:
JohntextVì vậy client-side cache luôn có trade-off:
Performance
↕
FreshnesstextMuốn giảm API request:
staleTime ↑textMuốn dữ liệu cập nhật thường xuyên:
staleTime ↓textRefetch dữ liệu#
TanStack Query có thể refetch trong nhiều tình huống.
Ví dụ khi user quay lại browser tab:
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
refetchOnWindowFocus: true,
})tsxConcept:
Điều này giúp ứng dụng có cảm giác dữ liệu luôn được cập nhật mà developer không cần tự viết event listener.
[!NOTE]
refetchOnWindowFocusmặc định đã làtrue— đây là một trong những “important defaults” gây bất ngờ: chuyển tab qua lại là app tự gọi API. Nếu thấy request “tự nhiên xuất hiện” trong DevTools, thì đây chính là thủ phạm.
Invalidate Cache#
Đây là một tính năng cực kỳ hữu ích khi làm CRUD.
Ví dụ:
GET /users
POST /userstextSau khi tạo user:
await createUser(data)tscó thể invalidate:
queryClient.invalidateQueries({
queryKey: ["users"],
})tsTanStack Query sẽ biết query:
["users"]textđã trở nên stale và có thể refetch.
Flow:
Mutation#
TanStack Query cũng có useMutation().
const mutation = useMutation({
mutationFn: createUser,
})tsxSử dụng:
mutation.mutate({
name: "John",
})tsxVí dụ hoàn chỉnh:
const queryClient = useQueryClient()
const mutation = useMutation({
mutationFn: createUser,
onSuccess: () => {
queryClient.invalidateQueries({
queryKey: ["users"],
})
},
})tsxĐây là pattern rất phổ biến:
Optimistic Update#
Một tính năng nâng cao hơn là Optimistic Update.
Ví dụ user click:
❤️ LiketextThay vì:
Click
↓
API request
↓
Server response
↓
Update UItextcó thể làm:
Click
↓
Update UI ngay
↓
API request
↓
Success → giữ nguyên
Failure → rollbacktextNgười dùng sẽ cảm thấy ứng dụng nhanh hơn.
Ví dụ:
Đây là một trong những use case mà việc tự xây cache/state management trở nên phức tạp khá nhanh.
TanStack Query có lưu cache vào LocalStorage không?#
Mặc định:
Không.
Query cache chủ yếu nằm trong memory.
Ví dụ:
Browser
└─JavaScript Memory
└─TanStack Query CachetextReload trang:
F5
↓
JavaScript memory mất
↓
Query cache mấttextNếu muốn persist cache, TanStack Query có thể kết hợp với persistence mechanism như:
localStorage
IndexedDBtextđể tạo persistent cache.
Điều này phù hợp với các ứng dụng muốn giữ một số server state sau khi reload/offline.
TanStack Query có phải HTTP Cache không?#
Không nên đánh đồng hai thứ này.
Có ít nhất hai lớp cache khác nhau:
Browser / HTTP Cache
↓
HTTP response caching
TanStack Query
↓
Application-level server-state cachetextVí dụ:
TanStack Query hiểu được:
queryKey
staleTime
invalidation
mutation
query statetsTrong khi HTTP cache dựa trên các cơ chế HTTP như:
Cache-Control
ETag
Last-Modified
AgetextHai hệ thống có thể hoạt động cùng nhau.
So sánh với tự viết cache#
Không dùng TanStack Query:
const cache = new Map()
async function getUser(id: number) {
if (cache.has(id)) {
return cache.get(id)
}
const data = await fetch(`/api/users/${id}`)
.then(res => res.json())
cache.set(id, data)
return data
}tsBan đầu nhìn khá đơn giản.
Nhưng sau đó bạn sẽ phải giải quyết:
❓ Cache bao lâu?
❓ Cache stale khi nào?
❓ Khi nào refetch?
❓ Retry?
❓ Loading?
❓ Error?
❓ Deduplicate?
❓ Mutation?
❓ Invalidate?
❓ Pagination?
❓ Infinite scroll?
❓ Optimistic update?
❓ Garbage collection?
❓ Concurrent request?
❓ Offline?textLúc này Map() đơn giản ban đầu đã biến thành một hệ thống cache hoàn chỉnh.
TanStack Query giải quyết phần lớn những vấn đề đó.
TanStack Query vs Zustand#
Một kiến trúc React thường có thể sử dụng cả hai:
Ví dụ Zustand:
{
sidebarOpen: true,
selectedTheme: "dark"
}tsTanStack Query:
{
users: [...],
posts: [...],
profile: {...}
}tsKhông nhất thiết phải chọn một trong hai.
TanStack Query vs SWR#
Một lựa chọn phổ biến khác trong React/Next.js là SWR.
Concept của cả hai khá giống nhau:
React
├─TanStack Query
└─SWRtextCả hai đều giải quyết:
- fetching
- caching
- revalidation
- server state
TanStack Query thường cung cấp hệ thống query/mutation và các khả năng quản lý server state rộng hơn, trong khi SWR có API khá tối giản.
Vì vậy nếu application có nhiều:
CRUD
Mutation
Pagination
Infinite Query
Optimistic Update
Cache Invalidation
Complex Server Statetextthì TanStack Query là một lựa chọn đáng cân nhắc.
Khi nào nên dùng TanStack Query?#
TanStack Query đặc biệt phù hợp với:
Dashboard
Admin panel
E-commerce
CRM
SaaS
Social network
Healthcare application
Education platformtextđặc biệt khi application có rất nhiều API.
Ví dụ:
/users
/users/:id
/courses
/courses/:id
/students
/students/:id
/reports
/notificationstextThay vì mỗi component tự quản lý:
fetch
loading
error
cache
refetchtextcó thể để TanStack Query quản lý server state.
Khi nào không nhất thiết cần TanStack Query?#
Nếu application cực kỳ đơn giản:
const [data, setData] = useState()
useEffect(() => {
fetch("/api/data")
.then(...)
}, [])tsxvà chỉ có vài API request thì thêm một thư viện có thể không mang lại nhiều lợi ích.
Tương tự, nếu framework đã cung cấp một cơ chế server-data fetching/cache rất mạnh và application chủ yếu dùng server components, cần cân nhắc kiến trúc tổng thể trước khi thêm client-side query library.
Một kiến trúc thực tế#
Với một React SPA lớn, có thể tổ chức:
src/
├─api/
│ ├─users.ts
│ ├─courses.ts
│ └─reports.ts
├─queries/
│ ├─users.ts
│ ├─courses.ts
│ └─reports.ts
├─components/
│ ├─UserList.tsx
│ └─CourseList.tsx
└─query-client.tstextVí dụ:
// queries/users.ts
export const usersQuery = () => ({
queryKey: ["users"],
queryFn: fetchUsers,
})tsComponent:
const { data, isPending } = useQuery(
usersQuery()
)tsxĐiều này giúp API logic không bị trộn lẫn quá nhiều với UI.
Một pattern quan trọng: Query Key#
Khi sử dụng TanStack Query, nên thiết kế query key có cấu trúc.
Ví dụ:
["users"]ts["users", userId]ts["users", { page: 1, search: "john" }]tsCó thể hình dung:
users
├─users/123
├─users/456
└─users?page=1&search=johntextQuery key càng được thiết kế nhất quán thì việc:
invalidateQueries()tsvà quản lý cache càng dễ.
[!TIP] Thiết kế query key theo hierarchy từ tổng quát đến chi tiết:
["users"]→["users", id]→["users", { page, search }]. Nhờ đóinvalidateQueries({ queryKey: ["users"] })sẽ invalidate cả cây con — đúng như cách bạn xóa cả thư mục thay vì từng file.
Một ví dụ đầy đủ#
function UserList() {
const queryClient = useQueryClient()
const usersQuery = useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
staleTime: 60_000,
})
const createMutation = useMutation({
mutationFn: createUser,
onSuccess: () => {
queryClient.invalidateQueries({
queryKey: ["users"],
})
},
})
if (usersQuery.isPending) {
return <div>Loading...</div>
}
if (usersQuery.isError) {
return <div>Something went wrong</div>
}
return (
<>
{usersQuery.data.map(user => (
<div key={user.id}>
{user.name}
</div>
))}
<button
onClick={() =>
createMutation.mutate({
name: "John",
})
}
>
Add user
</button>
</>
)
}tsxFlow lúc này rất rõ:
Kết luận#
Nếu mục tiêu của bạn là client-side cache cho dữ liệu API trong React, thì @tanstack/react-query là một lựa chọn rất đáng cân nhắc.
Điểm quan trọng nhất cần nhớ không phải là:
“TanStack Query là thư viện fetch API.”
Mà là:
TanStack Query là một hệ thống quản lý server state và cache ở phía client.
Nó đặc biệt hữu ích khi application bắt đầu có nhiều API và các vấn đề như:
API request duplication
+
Caching
+
Stale data
+
Refetch
+
Mutation
+
Cache invalidation
+
Optimistic updatetextthay vì tự xây dựng tất cả bằng useEffect + useState + Map, bạn có thể để TanStack Query đảm nhiệm phần server-state này.
Một kiến trúc React hiện đại có thể đơn giản hóa thành:
Đó cũng là cách nhìn giúp tránh việc dùng Redux/Zustand để lưu toàn bộ dữ liệu API một cách không cần thiết.