정정지용
기술스택 목록
프론트엔드

React Query

프로젝트 3개에서 사용했습니다. 각 프로젝트에서 어떤 역할로 썼는지 아래에 정리했습니다.

이 기술은 무엇인가요?

React 애플리케이션에서 서버 상태를 선언적으로 관리하는 데이터 패칭 라이브러리

React Query는 서버에서 가져온 데이터를 캐싱하고 동기화하는 라이브러리입니다. 기존에는 Redux나 useState로 API 응답을 직접 관리했지만, 서버 상태는 클라이언트가 소유하지 않고 항상 최신 상태를 유지해야 하는 특성이 있습니다. React Query는 이런 서버 상태를 자동으로 캐싱하고, 백그라운드에서 다시 가져오며, 로딩·에러 상태를 선언적으로 다룰 수 있게 설계되었습니다.

이럴 때 사용합니다

  • 서버 API를 호출하고 응답을 여러 컴포넌트에서 공유해야 할 때
  • 실시간성이 중요해 주기적으로 데이터를 갱신해야 하는 대시보드나 모니터링 화면
  • 페이지네이션, 무한 스크롤 등 복잡한 데이터 패칭 로직을 간결하게 구현하고 싶을 때
  • 낙관적 업데이트나 mutation 후 자동 리페칭이 필요한 폼 중심 애플리케이션

핵심 개념

useQuery
서버에서 데이터를 조회(GET)할 때 사용하는 훅입니다. 쿼리 키와 패칭 함수를 받아 데이터를 가져오고, 자동으로 캐싱 및 리페칭을 처리합니다.
useMutation
서버 상태를 변경(POST, PUT, DELETE)할 때 사용하는 훅입니다. 성공 후 관련 쿼리를 무효화하거나 낙관적 업데이트를 수행할 수 있습니다.
Query Key
쿼리를 식별하고 캐시를 관리하는 고유 키입니다. 배열 형태로 작성하며, 같은 키를 가진 쿼리는 같은 캐시를 공유합니다.
Stale Time
데이터가 신선한 상태로 유지되는 시간입니다. 이 시간이 지나면 데이터는 stale 상태가 되어 다음 렌더링 시 백그라운드에서 다시 가져옵니다.
Cache Time
사용되지 않는 쿼리 데이터가 메모리에 남아있는 시간입니다. 이 시간이 지나면 가비지 컬렉션됩니다.
Refetch
캐시된 데이터를 백그라운드에서 다시 가져오는 동작입니다. 윈도우 포커스, 네트워크 재연결, 일정 간격 등 다양한 시점에 자동으로 실행할 수 있습니다.

기본 데이터 조회 및 mutation

useQuery로 사용자 목록을 조회하고, useMutation으로 새 사용자를 추가한 뒤 자동으로 목록을 갱신합니다.

TypeScript
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';

// 데이터 조회
function UserList() {
  const { data, isLoading, error } = useQuery({
    queryKey: ['users'],
    queryFn: () => fetch('/api/users').then(res => res.json())
  });

  if (isLoading) return <div>로딩 중...</div>;
  if (error) return <div>오류 발생</div>;
  return <ul>{data.map(user => <li key={user.id}>{user.name}</li>)}</ul>;
}

// 데이터 변경 후 자동 갱신
function AddUser() {
  const queryClient = useQueryClient();
  const mutation = useMutation({
    mutationFn: (newUser) => fetch('/api/users', { method: 'POST', body: JSON.stringify(newUser) }),
    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['users'] })
  });

  return <button onClick={() => mutation.mutate({ name: '홍길동' })}>추가</button>;
}

처음 쓸 때 흔한 함정

  • 쿼리 키가 배열 형태여야 하며, 의존성이 바뀌면 새 배열을 생성해야 리페칭됩니다.
  • 기본 staleTime은 0이므로, 설정하지 않으면 매번 백그라운드에서 다시 가져옵니다.
  • mutation 후 관련 쿼리를 invalidate하지 않으면 화면에 변경사항이 반영되지 않습니다.

위 개요는 기술 학습을 돕기 위해 자동 생성된 일반 설명입니다. 정확한 사양과 최신 정보는 공식 문서를 확인하세요.

프로젝트별 활용 방식

위 개념이 실제 프로젝트에서 어떻게 쓰였는지 보여줍니다.

함께 사용한 기술

위 프로젝트들에서 같이 쓰인 다른 기술입니다.

Axios3Docker3React3React Hook Form3TypeScript3Vite3Nginx2SCSS2Zustand2FirebaseGitHub ActionsMSW