TanStack Query 완벽 가이드 | React Query·캐싱·Optimistic Updates·Infinite Scroll
이 글의 핵심
TanStack Query(React Query)로 서버 상태를 효율적으로 관리하는 완벽 가이드입니다. 캐싱, Mutation, Optimistic Updates, Infinite Scroll, Prefetch까지 실전 예제로 정리했습니다.
실무 경험 공유: 대규모 대시보드 애플리케이션에 TanStack Query를 도입하면서, 보일러플레이트 코드를 70% 줄이고 사용자 경험을 크게 향상시킨 경험을 공유합니다.
들어가며: “API 상태 관리가 복잡해요”
실무 문제 시나리오
시나리오 1: 로딩/에러 상태 관리가 번거로워요
useState, useEffect로 매번 로딩/에러 상태를 관리해야 합니다. TanStack Query는 자동 처리합니다.
시나리오 2: 캐싱이 없어요
같은 데이터를 여러 번 요청합니다. TanStack Query는 자동 캐싱합니다.
시나리오 3: 리페칭이 복잡해요
데이터 갱신 로직이 복잡합니다. TanStack Query는 자동 리페칭합니다.
1. TanStack Query란?
핵심 특징
TanStack Query는 서버 상태 관리 라이브러리입니다.
주요 장점:
- 자동 캐싱: 중복 요청 방지
- 자동 리페칭: 백그라운드 갱신
- Optimistic Updates: 낙관적 업데이트
- Infinite Scroll: 무한 스크롤 지원
- Devtools: 강력한 개발자 도구
2. 설치 및 설정
설치
npm install @tanstack/react-query
npm install -D @tanstack/react-query-devtools기본 설정
// app/providers.tsx
'use client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import { useState } from 'react';
export function Providers({ children }: { children: React.ReactNode }) {
const [queryClient] = useState(
() =>
new QueryClient({
defaultOptions: {
queries: {
staleTime: 60 * 1000, // 1분
refetchOnWindowFocus: false,
},
},
})
);
return (
<QueryClientProvider client={queryClient}>
{children}
<ReactQueryDevtools initialIsOpen={false} />
</QueryClientProvider>
);
}3. useQuery (데이터 조회)
기본 사용
import { useQuery } from '@tanstack/react-query';
interface User {
id: number;
name: string;
email: string;
}
async function fetchUser(id: number): Promise<User> {
const response = await fetch(`/api/users/${id}`);
if (!response.ok) throw new Error('Failed to fetch user');
return response.json();
}
export function UserProfile({ userId }: { userId: number }) {
const { data, isLoading, error } = useQuery({
queryKey: ['user', userId],
queryFn: () => fetchUser(userId),
});
if (isLoading) return <div>Loading...</div>;
if (error) return <div>Error: {error.message}</div>;
return (
<div>
<h1>{data.name}</h1>
<p>{data.email}</p>
</div>
);
}의존성 쿼리
function UserPosts({ userId }: { userId: number }) {
// 사용자 정보 먼저 가져오기
const { data: user } = useQuery({
queryKey: ['user', userId],
queryFn: () => fetchUser(userId),
});
// 사용자 정보가 있을 때만 포스트 가져오기
const { data: posts } = useQuery({
queryKey: ['posts', userId],
queryFn: () => fetchPosts(userId),
enabled: !!user, // user가 있을 때만 실행
});
return <div>{/* ... */}</div>;
}4. useMutation (데이터 변경)
기본 사용
import { useMutation, useQueryClient } from '@tanstack/react-query';
async function createUser(user: { name: string; email: string }) {
const response = await fetch('/api/users', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(user),
});
return response.json();
}
export function CreateUserForm() {
const queryClient = useQueryClient();
const mutation = useMutation({
mutationFn: createUser,
onSuccess: () => {
// 사용자 목록 다시 가져오기
queryClient.invalidateQueries({ queryKey: ['users'] });
},
});
const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
e.preventDefault();
const formData = new FormData(e.currentTarget);
mutation.mutate({
name: formData.get('name') as string,
email: formData.get('email') as string,
});
};
return (
<form onSubmit={handleSubmit}>
<input name="name" placeholder="Name" required />
<input name="email" type="email" placeholder="Email" required />
<button type="submit" disabled={mutation.isPending}>
{mutation.isPending ? 'Creating...' : 'Create User'}
</button>
{mutation.isError && <p>Error: {mutation.error.message}</p>}
</form>
);
}5. Optimistic Updates
function TodoList() {
const queryClient = useQueryClient();
const { data: todos } = useQuery({
queryKey: ['todos'],
queryFn: fetchTodos,
});
const toggleMutation = useMutation({
mutationFn: (id: number) => toggleTodo(id),
// Optimistic Update
onMutate: async (id) => {
// 진행 중인 리페칭 취소
await queryClient.cancelQueries({ queryKey: ['todos'] });
// 이전 데이터 저장
const previousTodos = queryClient.getQueryData(['todos']);
// 낙관적 업데이트
queryClient.setQueryData(['todos'], (old: Todo[]) =>
old.map((todo) =>
todo.id === id ? { ...todo, done: !todo.done } : todo
)
);
return { previousTodos };
},
// 에러 시 롤백
onError: (err, id, context) => {
queryClient.setQueryData(['todos'], context?.previousTodos);
},
// 성공/실패 후 리페칭
onSettled: () => {
queryClient.invalidateQueries({ queryKey: ['todos'] });
},
});
return (
<ul>
{todos?.map((todo) => (
<li key={todo.id}>
<input
type="checkbox"
checked={todo.done}
onChange={() => toggleMutation.mutate(todo.id)}
/>
<span>{todo.text}</span>
</li>
))}
</ul>
);
}6. Infinite Scroll
import { useInfiniteQuery } from '@tanstack/react-query';
interface PostsResponse {
posts: Post[];
nextCursor: number | null;
}
async function fetchPosts({ pageParam = 0 }): Promise<PostsResponse> {
const response = await fetch(`/api/posts?cursor=${pageParam}&limit=10`);
return response.json();
}
export function InfinitePostList() {
const {
data,
fetchNextPage,
hasNextPage,
isFetchingNextPage,
} = useInfiniteQuery({
queryKey: ['posts'],
queryFn: fetchPosts,
getNextPageParam: (lastPage) => lastPage.nextCursor,
initialPageParam: 0,
});
return (
<div>
{data?.pages.map((page, i) => (
<div key={i}>
{page.posts.map((post) => (
<article key={post.id}>
<h2>{post.title}</h2>
<p>{post.content}</p>
</article>
))}
</div>
))}
<button
onClick={() => fetchNextPage()}
disabled={!hasNextPage || isFetchingNextPage}
>
{isFetchingNextPage
? 'Loading more...'
: hasNextPage
? 'Load More'
: 'No more posts'}
</button>
</div>
);
}7. Prefetch
import { useQueryClient } from '@tanstack/react-query';
export function PostList() {
const queryClient = useQueryClient();
const { data: posts } = useQuery({
queryKey: ['posts'],
queryFn: fetchPosts,
});
// 마우스 호버 시 미리 가져오기
const handleMouseEnter = (postId: number) => {
queryClient.prefetchQuery({
queryKey: ['post', postId],
queryFn: () => fetchPost(postId),
});
};
return (
<ul>
{posts?.map((post) => (
<li key={post.id} onMouseEnter={() => handleMouseEnter(post.id)}>
<Link href={`/posts/${post.id}`}>{post.title}</Link>
</li>
))}
</ul>
);
}8. 실전 예제: 댓글 시스템
// hooks/useComments.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
interface Comment {
id: number;
postId: number;
author: string;
content: string;
createdAt: string;
}
export function useComments(postId: number) {
return useQuery({
queryKey: ['comments', postId],
queryFn: async () => {
const response = await fetch(`/api/posts/${postId}/comments`);
return response.json() as Promise<Comment[]>;
},
});
}
export function useCreateComment(postId: number) {
const queryClient = useQueryClient();
return useMutation({
mutationFn: async (comment: { author: string; content: string }) => {
const response = await fetch(`/api/posts/${postId}/comments`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(comment),
});
return response.json();
},
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: ['comments', postId] });
},
});
}
export function useDeleteComment(postId: number) {
const queryClient = useQueryClient();
return useMutation({
mutationFn: async (commentId: number) => {
await fetch(`/api/comments/${commentId}`, { method: 'DELETE' });
},
onMutate: async (commentId) => {
await queryClient.cancelQueries({ queryKey: ['comments', postId] });
const previousComments = queryClient.getQueryData(['comments', postId]);
queryClient.setQueryData(['comments', postId], (old: Comment[]) =>
old.filter((comment) => comment.id !== commentId)
);
return { previousComments };
},
onError: (err, commentId, context) => {
queryClient.setQueryData(['comments', postId], context?.previousComments);
},
onSettled: () => {
queryClient.invalidateQueries({ queryKey: ['comments', postId] });
},
});
}// components/CommentSection.tsx
export function CommentSection({ postId }: { postId: number }) {
const { data: comments, isLoading } = useComments(postId);
const createComment = useCreateComment(postId);
const deleteComment = useDeleteComment(postId);
const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
e.preventDefault();
const formData = new FormData(e.currentTarget);
createComment.mutate({
author: formData.get('author') as string,
content: formData.get('content') as string,
});
e.currentTarget.reset();
};
if (isLoading) return <div>Loading comments...</div>;
return (
<div>
<h2>Comments ({comments?.length})</h2>
<form onSubmit={handleSubmit}>
<input name="author" placeholder="Your name" required />
<textarea name="content" placeholder="Your comment" required />
<button type="submit" disabled={createComment.isPending}>
{createComment.isPending ? 'Posting...' : 'Post Comment'}
</button>
</form>
<ul>
{comments?.map((comment) => (
<li key={comment.id}>
<strong>{comment.author}</strong>
<p>{comment.content}</p>
<small>{new Date(comment.createdAt).toLocaleString()}</small>
<button onClick={() => deleteComment.mutate(comment.id)}>
Delete
</button>
</li>
))}
</ul>
</div>
);
}9. 성능 최적화
선택적 리렌더링
const { data } = useQuery({
queryKey: ['user', userId],
queryFn: () => fetchUser(userId),
select: (data) => data.name, // name만 선택
});캐시 시간 설정
const { data } = useQuery({
queryKey: ['user', userId],
queryFn: () => fetchUser(userId),
staleTime: 5 * 60 * 1000, // 5분
gcTime: 10 * 60 * 1000, // 10분 (구 cacheTime)
});정리 및 체크리스트
핵심 요약
- TanStack Query: 서버 상태 관리 라이브러리
- 자동 캐싱: 중복 요청 방지
- Optimistic Updates: 낙관적 업데이트로 UX 향상
- Infinite Scroll: 무한 스크롤 지원
- Devtools: 강력한 디버깅 도구
구현 체크리스트
- TanStack Query 설치 및 설정
- useQuery로 데이터 조회
- useMutation으로 데이터 변경
- Optimistic Updates 구현
- Infinite Scroll 구현
- Prefetch 활용
같이 보면 좋은 글
- React 18 심화 가이드
- Next.js 15 완벽 가이드
- Zod 완벽 가이드
이 글에서 다루는 키워드
TanStack Query, React Query, React, State Management, Caching, API, Frontend
자주 묻는 질문 (FAQ)
Q. TanStack Query vs Redux, 어떤 게 나은가요?
A. TanStack Query는 서버 상태, Redux는 클라이언트 상태 관리에 적합합니다. 대부분의 경우 TanStack Query만으로 충분합니다.
Q. 성능은 어떤가요?
A. 매우 빠릅니다. 자동 캐싱과 최적화로 불필요한 요청을 줄입니다.
Q. Next.js App Router에서 사용할 수 있나요?
A. 네, Server Components와 함께 사용 가능합니다. Prefetch를 활용하여 SSR과 통합할 수 있습니다.
Q. 학습 곡선이 가파른가요?
A. 기본 사용법은 간단합니다. useQuery와 useMutation만 알면 80%는 해결됩니다.