Network Mode

TanStack Query의 네트워크 모드는 인터넷 연결이 없을 때 쿼리와 뮤테이션이 어떻게 동작할지 결정하는 3가지 설정을 제공한다. 이 모드는 각 쿼리/뮤테이션에 개별적으로 설정하거나, 기본값을 통해 전역으로 설정할 수 있다.

 

일반적으로 데이터 패칭 라이브러리와 함께 사용되므로, 기본 네트워크 모드는 online이다.

 

Network Mode: online

이 모드에서는 인터넷에 연결되어 있을 때만 쿼리와 뮤테이션이 실행된다. 이것이 기본값이다.

 

인터넷 연결이 없어 쿼리를 실행할 수 없는 경우, 해당 쿼리는 기존의 state(pending, error, success) 상태를 그대로 유지한다. 하지만 이때 fetchStatus라는 추가적인 상태가 제공되어 더 자세한 상황을 알 수 있다.

• fetching: queryFn이 실제로 실행 중이며, 요청이 진행 중인 상태이다.
• paused: 쿼리가 실행되지 않고 일시정지된 상태이다. 인터넷이 다시 연결될 때까지 대기한다.
• idle: 쿼리가 데이터를 가져오고 있지도, 일시정지되지도 않은 유휴 상태이다.

편의를 위해 isFetching과 isPaused라는 flag도 이 상태를 기반으로 제공된다.

 

로딩 스피너를 표시할 때 pending 상태만 확인하는 것으로는 부족할 수 있다. 인터넷 연결이 없는 상태에서 컴포넌트가 처음 마운트되면, 쿼리는 state: 'pending' 이면서 동시에 fetchStatus: 'paused' 상태일 수 있기 때문이다. 

 

만약 온라인 상태에서 쿼리가 실행되었지만 요청이 진행되는 도중에 오프라인이 되면 TanStack Query는 재시도 로직 또한 일시정지된다. 이렇게 일시정지된 쿼리는 인터넷이 다시 연결되면 이어서 실행된다. 이는 refetchOnReconnect 옵션(이 모드에서는 기본값이 true)과는 별개로 동작하는데 데이터를 재요청하는 것이 아니라 이어서 실행하는 것이기 때문이다. 만약 그 사이에 쿼리가 취소되었다면 이어서 실행하지 않는다.

 

Network Mode: always

이 모드에서는 TanStack Query가 온라인/오프라인 상태를 무시하고 항상 쿼리를 실행한다.

 

이 모드는 쿼리가 동작하는 데 네트워크 연결이 필요 없는 환경에서 사용하기 적합하다. 예를 들어, AsyncStorage에서 데이터를 읽어오거나 queryFn에서 단순히 Promise.resolve(5)와 같은 값을 반환할 때 선택할 수 있다.

• 인터넷 연결이 없다고 해서 쿼리가 paused되는 일은 절대 없다.
• 재시도 역시 멈추지 않고, 실패하면 바로 error 상태가 된다.
• 이 모드에서 refetchOnReconnect의 기본값은 false이다. 네트워크 연결이 필요 없는 데이터를 다루기 때문에, 인터넷이 다시 연결됐다고 해서 굳이 데이터를 또 가져올 필요가 없기 때문이다. 원한다면 이 옵션을 다시 켤 수 있다.

Network Mode: offlineFirst

이 모드는 online과 always의 중간 지점에 해당한다. queryFn을 최초 한 번은 실행하지만, 실패 시 재시도는 일시정지한다. 

 

이 방식은 offline-fist PWA처럼 서비스워커가 요청을 가로채 캐싱을 처리하거나, Cache-Control header를 통해 HTTP 캐싱을 사용하는 경우에 매우 유용하다. 

 

이런 상황에서는 첫 요청이 오프라인 저장소나 캐시에서 데이터를 가져와 성공할 수 있다. 하지만 cache miss가 발생하여 실제 네트워크 요청이 실패하는 경우, 이 모드는 online 모드처럼 재시도를 일시정지하며 동작한다.

 

Devtools

TanStack Query 개발자 도구에서는 인터넷 연결이 없어 실행되지 못하는 쿼리를 paused 상태로 표시해준다. 또한, Mock offline behavior(오프라인 동작 흉내내기) 토글 버튼이 있어 오프라인 상태를 시뮬레이션해볼 수 있다. 이 버튼은 실제 인터넷 연결을 끊는 것이 아니라 TanStack Query의 OnlineManager를 오프라인 상태로 설정하는 역할을 한다.

 

Signature

• networkMode: 'online' | 'always' | 'offlineFirst'
  • optional
  • 기본값은 online이다.

https://tanstack.com/query/latest/docs/framework/react/guides/network-mode

Network Mode | TanStack Query React Docs