Network Mode

TanStack Query는 네트워크 연결이 없을 때 Queries와 Mutations의 동작 방식을 구분하기 위해 세 가지 네트워크 모드를 제공합니다. 이 모드는 각 Query/Mutation별로 개별적으로 설정할 수 있으며, 전역적으로는 Query/Mutation 기본값을 통해 설정할 수도 있습니다.

TanStack Query는 데이터 가져오기를 데이터 가져오기 라이브러리와 함께 사용할 때 가장 자주 사용되므로, 기본 네트워크 모드는 online입니다.

Network Mode: online

이 모드에서는 네트워크 연결이 없으면 Queries와 Mutations가 실행되지 않습니다. 이것이 기본 모드입니다. Query에 대한 요청이 시작되면, 네트워크 연결이 없어서 요청을 할 수 없는 경우 현재의 state (pending, error, success) 상태를 계속 유지합니다. 그러나 추가적으로 fetchStatus도 노출됩니다. 이 상태는 다음 중 하나일 수 있습니다:

fetching: queryFn이 실제로 실행 중입니다 - 요청이 진행 중입니다.
paused: Query가 실행되지 않습니다 - 네트워크 연결이 다시 생길 때까지 paused 상태입니다.
idle: Query가 데이터를 가져오지 않으며 paused 상태도 아닙니다.

isFetching과 isPaused 플래그는 이 상태에서 파생되어 편의를 위해 노출됩니다.

pending 상태만으로 로딩 스피너를 표시하기에는 부족할 수 있습니다. Queries가 state: 'pending' 상태일 수 있지만, 네트워크 연결이 없으면 fetchStatus: 'paused' 상태일 수 있습니다.

쿼리가 온라인 상태일 때 실행되지만, 가져오는 동안 오프라인 상태가 되면 TanStack Query는 재시도 메커니즘도 일시 중지합니다. 일시 중지된 Queries는 네트워크 연결이 다시 생기면 계속 실행됩니다. 이는 refetchOnReconnect와는 독립적이며 (이 모드에서는 기본값이 true), refetch가 아니라 continue이기 때문입니다. Query가 그 사이에 cancelled된 경우, 계속 실행되지 않습니다.

Network Mode: always

이 모드에서는 TanStack Query가 항상 데이터를 가져오며 온라인/오프라인 상태를 무시합니다. 네트워크 연결이 필요 없는 환경에서 TanStack Query를 사용하는 경우 이 모드를 선택하는 것이 좋습니다. 예를 들어, AsyncStorage에서 읽기만 하거나, queryFn에서 Promise.resolve(5)를 반환하는 경우입니다.

Queries는 네트워크 연결이 없어서 paused 상태가 되는 일이 없습니다.
재시도도 일시 중지되지 않습니다 - Query가 실패하면 error 상태로 전환됩니다.
refetchOnReconnect는 이 모드에서는 기본값이 false입니다. 네트워크에 다시 연결되는 것이 더 이상 Queries가 새로고침되어야 한다는 좋은 지표가 아니기 때문입니다. 원한다면 여전히 켤 수 있습니다.

Network Mode: offlineFirst

이 모드는 처음 두 옵션 사이의 중간 상태로, TanStack Query가 queryFn을 한 번 실행하지만, 이후 재시도를 일시 중지합니다. 오프라인 저장소/캐시에서 요청을 가로채는 offline-first PWA (opens in a new tab)나 Cache-Control header (opens in a new tab)를 사용하는 경우에 유용합니다.

이 경우 첫 번째 fetch 요청은 오프라인 저장소/캐시에서 성공할 수 있습니다. 그러나 캐시 미스가 발생하면 네트워크 요청이 나가고 실패하게 되며, 이 경우 이 모드는 online Query처럼 작동하여 재시도를 일시 중지합니다.

Devtools

TanStack Query Devtools는 Queries가 네트워크 연결이 없을 때 paused 상태로 표시됩니다. 또한 Mock offline behavior를 토글하는 버튼이 있습니다. 이 버튼은 실제로 네트워크 연결을 조작하지는 않지만 (브라우저 개발자 도구에서 조작할 수 있습니다), OnlineManager를 오프라인 상태로 설정합니다.

Signature

networkMode: 'online' | 'always' | 'offlineFirst'
- 선택 사항
- 기본값은 'online'

Query Options Parallel Queries