[React Query 공식문서] React Query Devtools, Floating Mode / Embedded Mode

React Query 를 사용한다면 React Query Devtools을 함께 사용하는 것이 좋습니다.

이 도구는 React Query의 내부 작동을 시각화하는 데 도움을 주며, 문제가 생겼을 때 디버깅에 많은 시간을 절약할 수 있습니다

---

개발 도구 설치 및 가져오기

개발 도구는 별도의 패키지로 설치해야 합니다

 

npm i @tanstack/react-query-devtools

 

또는

 

pnpm add @tanstack/react-query-devtools

 

또는

 

yarn add @tanstack/react-query-devtools

 

또는

 

bun add @tanstack/react-query-devtools

 

 

Next 13+ App Dir에서는 작동하기 위해 개발 종속성으로 설치해야 합니다.

 

개발 도구는 다음과 같이 가져올 수 있습니다:

import { ReactQueryDevtools } from '@tanstack/react-query-devtools'

 

기본적으로 React Query Devtools는

process.env.NODE_ENV === 'development'일 때만 번들에 포함되므로,

프로덕션 빌드에서 제외하는 것에 대해 걱정할 필요가 없습니다.

---

Floating Mode

Floating Mode는

개발 도구를 앱 내의 고정된 Floating 요소로 마운트하고,

화면 모서리에 개발 도구를 표시하고 숨길 수 있는 토글을 제공합니다.

 

이 토글 상태는 로컬 스토리지에 저장되어 새로 고침 간에 기억됩니다.

 

다음 코드를 React 앱의 가능한 높은 위치에 배치하세요.

페이지의 루트에 가까울수록 더 잘 작동합니다!

 

옵션

initialIsOpen: Boolean

개발 도구가 기본적으로 열리도록 하려면 true로 설정하세요.

 

buttonPosition?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "relative"

기본값은 bottom-right입니다.

React Query 로고의 위치를 설정하여 개발 도구 패널을 열고 닫습니다.

relative로 설정하면 개발 도구를 렌더링하는 위치에 버튼이 배치됩니다.

 

position?: "top" | "bottom" | "left" | "right"

기본값은 bottom입니다.

React Query 개발 도구 패널의 위치를 설정합니다.

 

client?: QueryClient

사용자 정의 QueryClient를 사용하려면 이 옵션을 사용하세요.

그렇지 않으면 가장 가까운 컨텍스트의 QueryClient가 사용됩니다.

 

errorTypes?: { name: string; initializer: (query: Query) => TError}[]

쿼리에서 트리거할 수 있는 일부 오류를 미리 정의하는 데 사용합니다.

UI에서 해당 오류가 토글될 때 특정 쿼리와 함께 초기화 함수가 호출됩니다.

이 함수는 Error를 반환해야 합니다.

 

styleNonce?: string

문서 헤드에 추가되는 스타일 태그에 nonce를 전달하는 데 사용합니다.

이는 인라인 스타일을 허용하기 위해 콘텐츠 보안 정책(CSP) nonce를 사용하는 경우 유용합니다.

 

shadowDOMTarget?: ShadowRoot

기본 동작은 개발 도구의 스타일을 DOM 내의 head 태그에 적용합니다.

이 옵션을 사용하여 개발 도구에 그림자 DOM 대상을 전달하면 스타일이 라이트 DOM의 head 태그가 아닌 그림자 DOM 내에 적용됩니다.

---

Embedded Mode

임베디드 모드는

개발 도구를 애플리케이션 내의 고정 요소로 표시하므로, 자체 개발 도구에서 패널을 사용할 수 있습니다.

 

다음 코드를 React 앱의 가능한 높은 위치에 배치하세요. 페이지의 루트에 가까울수록 더 잘 작동합니다!

 

옵션

style?: React.CSSProperties

개발 도구 패널에 대한 사용자 정의 스타일

• 기본값: { height: '500px' }
• 예: { height: '100%' }
• 예: { height: '100%', width: '100%' }

 

onClose?: () => unknown

개발 도구 패널이 닫힐 때 호출되는 콜백 함수

 

client?: QueryClient

사용자 정의 QueryClient를 사용하려면 이 옵션을 사용하세요.

그렇지 않으면 가장 가까운 컨텍스트의 QueryClient가 사용됩니다.

 

errorTypes?: { name: string; initializer: (query: Query) => TError}[]

쿼리에서 트리거할 수 있는 일부 오류를 미리 정의하는 데 사용합니다.

UI에서 해당 오류가 토글될 때 특정 쿼리와 함께 초기화 함수가 호출됩니다.

이 함수는 Error를 반환해야 합니다.

 

styleNonce?: string

문서 헤드에 추가되는 스타일 태그에 nonce를 전달하는 데 사용합니다.

이는 인라인 스타일을 허용하기 위해 콘텐츠 보안 정책(CSP) nonce를 사용하는 경우 유용합니다.

 

shadowDOMTarget?: ShadowRoot

기본 동작은 개발 도구의 스타일을 DOM 내의 head 태그에 적용합니다.

이 옵션을 사용하여 개발 도구에 그림자 DOM 대상을 전달하면 스타일이 라이트 DOM의 head 태그가 아닌 그림자 DOM 내에 적용됩니다.

---

프로덕션에서의 개발 도구

개발 도구는 프로덕션 빌드에서 제외됩니다.

그러나 프로덕션에서 개발 도구를 지연 로드하는 것이 바람직할 수 있습니다

이렇게 하면 window.toggleDevtools()를 호출하여 개발 도구 번들을 다운로드하고 표시할 수 있습니다.

 

최신 번들러

번들러가 패키지 내보내기를 지원하는 경우, 다음 가져오기 경로를 사용할 수 있습니다:

TypeScript의 경우, tsconfig에서 moduleResolution: 'nodenext'를 설정해야 하며,

이는 최소한 TypeScript v4.7이 필요합니다.