onlineManager

01무엇

onlineManager는 TanStack Query가 네트워크 연결 여부를 판단하는 방식을 관리하는 전역 싱글턴이다. 기본은 브라우저의 online/offline 이벤트고, 필요하면 판단 로직을 통째로 바꿀 수 있다.

import { onlineManager } from '@tanstack/react-query'

기본값은 online: true로 시작하고, navigator.onLine을 직접 참조하지 않는다. 크로미움 계열 브라우저에서 이 값이 실제 연결 상태와 어긋나는 경우가 있어, window의 online/offline 이벤트만 본다.

02무슨 일이 일어나나

onlineManager가 오프라인으로 판단하면, networkMode가 기본(online)인 쿼리·뮤테이션은 실행을 멈추고 대기한다. 다시 온라인이 되면 밀려 있던 요청이 이어서 돈다. 브라우저 이벤트가 없는 환경(React Native 등)에서는 이 기본 감지가 동작하지 않으므로, setEventListener로 감지 로직 자체를 바꿔야 한다.

03사용법

커스텀 이벤트 소스는 setEventListener로 붙인다. 콜백이 setOnline 함수를 받고, 그 함수를 호출해 상태를 갱신한다.

import NetInfo from '@react-native-community/netinfo'
import { onlineManager } from '@tanstack/react-query'

onlineManager.setEventListener((setOnline) => {
  return NetInfo.addEventListener((state) => {
    setOnline(!!state.isConnected)
  })
})

상태를 직접 지정할 수도 있다.

onlineManager.setOnline(false) // 강제로 오프라인
const online = onlineManager.isOnline()

04실무 예시

subscribe로 상태만 관찰해 오프라인 배너를 만드는 정도가 웹에서 현실적인 쓰임이다.

import { useEffect, useState } from 'react'
import { onlineManager } from '@tanstack/react-query'

export function OfflineBanner() {
  const [isOnline, setIsOnline] = useState(() => onlineManager.isOnline())

  useEffect(() => {
    return onlineManager.subscribe(setIsOnline)
  }, [])

  if (isOnline) return null
  return <div className="offline-banner">오프라인 상태다</div>
}

05왜 중요한가

브라우저 앱은 기본 감지로 충분하다. 실사용은 거의 React Native처럼 window 이벤트가 없는 런타임에서 네이티브 네트워크 API로 갈아 끼울 때뿐이다. 그 밖에는 상태를 관찰만 하는 정도로 쓰인다.

Reference