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

TanStack React Query

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

이 기술은 무엇인가요?

React 애플리케이션에서 서버 상태를 가져오고 캐싱하며 동기화하는 라이브러리

TanStack React Query는 서버에서 가져온 데이터를 관리하기 위한 React 전용 라이브러리입니다. 전통적인 상태 관리 도구들이 클라이언트 상태와 서버 상태를 구분 없이 다루면서 발생하는 복잡성을 해결하기 위해 만들어졌습니다. 데이터 fetching, 캐싱, 백그라운드 동기화, 에러 처리 등을 선언적으로 처리할 수 있어 보일러플레이트 코드를 크게 줄여줍니다.

이럴 때 사용합니다

  • 서버 API 응답을 여러 컴포넌트에서 공유하고 자동으로 캐싱하고 싶을 때
  • 데이터 fetching 로딩, 에러, 성공 상태를 간결하게 처리하고 싶을 때
  • 백그라운드에서 자동으로 데이터를 최신 상태로 유지해야 할 때
  • 페이지네이션, 무한 스크롤 같은 복잡한 데이터 fetching 패턴을 구현할 때

핵심 개념

Query
서버에서 데이터를 읽어오는 비동기 작업을 나타냅니다. 고유한 키로 식별되며, 자동으로 캐싱되고 리페치됩니다.
Mutation
서버 데이터를 생성, 수정, 삭제하는 비동기 작업을 나타냅니다. 성공 시 관련 Query를 무효화하거나 직접 업데이트할 수 있습니다.
Query Key
각 Query를 고유하게 식별하는 배열 형태의 키입니다. 캐시 관리, 자동 리페칭, 무효화 등의 기준으로 사용됩니다.
Stale Time
데이터가 신선한 상태로 간주되는 시간입니다. 이 시간이 지나면 데이터는 stale 상태가 되어 다음 사용 시 백그라운드에서 리페치됩니다.
Cache Time
사용되지 않는 캐시 데이터가 메모리에 보관되는 시간입니다. 이 시간이 지나면 가비지 컬렉션됩니다.
Invalidation
특정 Query를 stale 상태로 표시하여 다음 렌더링 시 자동으로 리페치되도록 만드는 작업입니다. Mutation 후 서버 데이터와 동기화할 때 주로 사용됩니다.

기본적인 Query와 Mutation 사용

useQuery로 사용자 목록을 가져오고 캐싱하며, useMutation으로 새 사용자를 추가한 뒤 invalidateQueries로 목록을 자동 갱신합니다.

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

// Query: 사용자 목록 가져오기
function UserList() {
  const { data, isLoading, error } = useQuery({
    queryKey: ['users'],
    queryFn: () => fetch('/api/users').then(res => res.json())
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  return <ul>{data.map(user => <li key={user.id}>{user.name}</li>)}</ul>;
}

// Mutation: 사용자 추가 후 목록 갱신
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: 'New User' })}>Add</button>;
}

처음 쓸 때 흔한 함정

  • Query Key를 객체로 사용할 때 참조가 바뀌면 매번 리페치됩니다. 배열 형태로 안정적인 값을 사용하세요.
  • Stale Time 기본값은 0이므로, 설정하지 않으면 매번 백그라운드 리페치가 발생합니다.
  • Mutation 성공 후 invalidate 대신 직접 캐시를 수정하면 optimistic update가 가능하지만, 서버 응답과 동기화를 놓치기 쉽습니다.

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

프로젝트별 활용 방식

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

함께 사용한 기술

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

AxiosDockerFirebaseMSWnginxReactReact Hook FormReact RouterSCSSSentryTypeScriptVite