environmentManager

01무엇

environmentManager는 TanStack Query가 "지금 서버인가 클라이언트인가"를 판정하는 로직을 관리하는 전역 싱글턴이다. 기본 판정을 신뢰할 수 없는 특수 런타임에서 이 판단 자체를 바꿔치기할 때 쓴다.

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

const server = environmentManager.isServer()

02무슨 일이 일어나나

기본 판정은 대략 window 존재 여부로 서버/클라이언트를 나눈다. 이 값에 따라 SSR 관련 동작이 갈린다. 브라우저 확장(익스텐션) 워커처럼 window가 없지만 사실상 클라이언트에 가까운 런타임에서는 기본 판정이 틀릴 수 있어, setIsServer로 판정 함수 자체를 교체한다.

03사용법

setIsServer에 판정 함수를 넘긴다. 전역으로 적용되므로, 앱을 초기화하기 전에 한 번만 부른다.

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

environmentManager.setIsServer(() => {
  return typeof window === 'undefined' && !('chrome' in globalThis)
})

기본 판정으로 되돌릴 때는 라이브러리가 내보내는 isServer를 그대로 넘긴다.

import { environmentManager, isServer } from '@tanstack/react-query'

environmentManager.setIsServer(() => isServer)

04실무 예시

브라우저 확장 워커처럼 window는 없지만 서버로 취급하면 안 되는 런타임에서, 판정 로직을 명시적으로 덮어써야 동작이 맞아떨어진다. 일반적인 웹·Next.js 앱에서는 기본값이 이미 맞기 때문에 건드릴 일이 없다.

05왜 중요한가

거의 모든 앱은 기본 서버/클라이언트 판정을 그대로 쓴다. 이 매니저는 window 유무만으로 환경을 나눌 수 없는 드문 런타임(확장 워커 등)을 위한 탈출구다. 존재를 알아 두면 충분하고, 실제로 손댈 일은 흔치 않다.

Reference