DevTools

React Query에는 전용 DevTools가 제공되니 두 손을 흔들며 만세를 외쳐 보세요! 🥳

React Query 여정을 시작할 때 이러한 DevTools를 곁에 두는 것이 좋습니다. 이 도구들은 React Query의 모든 내부 작동을 시각화하는 데 도움을 주며, 곤란한 상황에 처했을 때 디버깅 시간을 몇 시간이나 절약해 줄 가능성이 큽니다!

Chrome, Firefox 및 Edge 사용자를 위한 안내: 브라우저 DevTools에서 직접 TanStack Query를 디버깅할 수 있는 서드 파티 브라우저 확장 프로그램이 제공됩니다. 이러한 확장 프로그램은 프레임워크별 devtools 패키지와 동일한 기능을 제공합니다:

• Chrome용 DevTools
• Firefox용 DevTools
• Edge용 DevTools

React Native 사용자를 위한 안내: ANY js 기반 애플리케이션에서 React Query를 디버깅할 수 있는 서드파티 네이티브 macOS 앱이 제공됩니다. 여러 기기의 쿼리를 실시간으로 모니터링합니다. 여기에서 확인하세요: rn-better-dev-tools

버전 5부터 DevTools가 뮤테이션 관찰도 지원한다는 점에 유의하세요.

DevTools 설치 및 가져오기

devtools는 별도로 설치해야 하는 패키지입니다:

npm i @tanstack/react-query-devtools

or

pnpm add @tanstack/react-query-devtools

or

yarn add @tanstack/react-query-devtools

or

bun add @tanstack/react-query-devtools

Next 13+ App Dir에서 작동하게 하려면 dev dependency로 설치해야 합니다.

다음과 같이 DevTools를 가져올 수 있습니다:

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

기본적으로 React Query Devtools는 process.env.NODE_ENV === 'development'일 때만 번들에 포함되므로 프로덕션 빌드 중에 이를 제외하는 것에 대해 걱정할 필요가 없습니다.

플로팅 모드

Floating Mode는 DevTools를 앱에 고정된 플로팅 요소로 마운트하고, 화면 모서리에 DevTools를 표시하거나 숨기는 토글을 제공합니다. 이 토글 상태는 localStorage에 저장되며 다시 로드해도 유지됩니다.

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

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

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      {/* The rest of your application */}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  )
}

옵션

• initialIsOpen: boolean
  • DevTools가 기본적으로 열린 상태가 되게 하려면 이 true를 설정합니다.
• buttonPosition?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "relative"
  • 기본값은 bottom-right입니다
  • DevTools 패널을 열고 닫는 TanStack 로고의 위치
  • relative이면 버튼은 DevTools를 렌더링하는 위치에 배치됩니다.
• position?: "top" | "bottom" | "left" | "right"
  • 기본값은 bottom입니다
  • React Query DevTools 패널의 위치
• client?: QueryClient,
  • 사용자 지정 QueryClient를 사용하려면 이를 사용합니다. 그렇지 않으면 가장 가까운 context의 항목이 사용됩니다.
• errorTypes?: { name: string; initializer: (query: Query) => TError}[]
  • 쿼리에서 발생시킬 수 있는 몇 가지 오류를 미리 정의하려면 이를 사용합니다. UI에서 해당 오류가 활성화되면 초기화 함수가 특정 쿼리와 함께 호출됩니다. 반드시 Error를 반환해야 합니다.
• styleNonce?: string
  • 문서 head에 추가되는 style 태그에 nonce를 전달하려면 이를 사용하세요. 인라인 스타일을 허용하기 위해 Content Security Policy(CSP) nonce를 사용하는 경우 유용합니다.
• shadowDOMTarget?: ShadowRoot
  • 기본 동작은 DOM 내의 head 태그에 devtool의 스타일을 적용합니다.
  • 이를 사용하여 shadow DOM 대상을 devtools에 전달하면 스타일이 light DOM의 head 태그 내부가 아니라 shadow DOM 내부에 적용됩니다.
• theme?: "light" | "dark" | "system"
  • 기본값은 system입니다.
  • devtools 패널의 테마를 변경하려면 이를 설정합니다.

임베디드 모드

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

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

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

function App() {
  const [isOpen, setIsOpen] = React.useState(false)

  return (
    <QueryClientProvider client={queryClient}>
      {/* The rest of your application */}
      <button
        onClick={() => setIsOpen(!isOpen)}
      >{`${isOpen ? 'Close' : 'Open'} the devtools panel`}</button>
      {isOpen && <ReactQueryDevtoolsPanel onClose={() => setIsOpen(false)} />}
    </QueryClientProvider>
  )
}

옵션

• style?: React.CSSProperties
  • DevTools 패널의 사용자 지정 스타일
  • 기본값: { height: '500px' }
  • 예제: { height: '100%' }
  • 예제: { height: '100%', width: '100%' }
• onClose?: () => void
  • DevTools 패널이 닫힐 때 호출되는 콜백 함수
• client?: QueryClient,
  • 사용자 지정 QueryClient를 사용하려면 이를 사용합니다. 그렇지 않으면 가장 가까운 context의 항목이 사용됩니다.
• errorTypes?: { name: string; initializer: (query: Query) => TError}[]
  • 쿼리에서 발생시킬 수 있는 몇 가지 오류를 미리 정의하려면 이를 사용합니다. UI에서 해당 오류가 활성화되면 초기화 함수가 특정 쿼리와 함께 호출됩니다. 반드시 Error를 반환해야 합니다.
• styleNonce?: string
  • 문서 head에 추가되는 style 태그에 nonce를 전달하려면 이를 사용하세요. 인라인 스타일을 허용하기 위해 Content Security Policy(CSP) nonce를 사용하는 경우 유용합니다.
• shadowDOMTarget?: ShadowRoot
  • 기본 동작은 DOM 내의 head 태그에 devtool의 스타일을 적용합니다.
  • 이를 사용하여 shadow DOM 대상을 devtools에 전달하면 스타일이 light DOM의 head 태그 내부가 아니라 shadow DOM 내부에 적용됩니다.
• theme?: "light" | "dark" | "system"
  • 기본값은 system입니다.
  • devtools 패널의 테마를 변경하려면 이를 설정합니다.

프로덕션 환경의 DevTools

Devtools는 프로덕션 빌드에서 제외됩니다. 하지만 프로덕션에서 Devtools를 지연 로드하는 것이 바람직할 수 있습니다:

import * as React from 'react'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
import { Example } from './Example'

const queryClient = new QueryClient()

const ReactQueryDevtoolsProduction = React.lazy(() =>
  import('@tanstack/react-query-devtools/build/modern/production.js').then(
    (d) => ({
      default: d.ReactQueryDevtools,
    }),
  ),
)

function App() {
  const [showDevtools, setShowDevtools] = React.useState(false)

  React.useEffect(() => {
    // @ts-expect-error
    window.toggleDevtools = () => setShowDevtools((old) => !old)
  }, [])

  return (
    <QueryClientProvider client={queryClient}>
      <Example />
      <ReactQueryDevtools initialIsOpen />
      {showDevtools && (
        <React.Suspense fallback={null}>
          <ReactQueryDevtoolsProduction />
        </React.Suspense>
      )}
    </QueryClientProvider>
  )
}

export default App

이렇게 하면 window.toggleDevtools()를 호출할 때 DevTools 번들을 다운로드하여 표시합니다.

최신 번들러

번들러가 package exports를 지원하는 경우 다음 import 경로를 사용할 수 있습니다:

const ReactQueryDevtoolsProduction = React.lazy(() =>
  import('@tanstack/react-query-devtools/production').then((d) => ({
    default: d.ReactQueryDevtools,
  })),
)

TypeScript의 경우 tsconfig에서 moduleResolution: 'nodenext'을 설정해야 하며, 이를 위해서는 최소 TypeScript v4.7이 필요합니다.