🔥 개발 도구

React Query에는 전용 개발 도구가 있어 기쁨의 박수를 보냅니다! 🥳

React Query를 시작할 때 이 개발 도구를 곁에 두는 것이 좋습니다. React Query의 내부 작동을 시각화하여 보여주기 때문에 문제가 생겼을 때 디버깅 시간을 크게 줄일 수 있습니다.

현재 개발 도구는 React Native를 지원하지 않습니다. 개발 도구를 플랫폼에 구애받지 않게 만드는 데 도움을 주고 싶다면 알려주세요!

반가운 소식이 있습니다! React Native용 React Query 개발 도구 패키지가 새로 나왔습니다. 이제 React Native 프로젝트에 개발 도구를 직접 통합할 수 있습니다. react-native-react-query-devtools에서 자세히 알아보고 기여해 보세요.

외부 대시보드를 통해 React Query 개발 도구를 사용할 수 있는 외부 도구도 있습니다. react-query-external-sync에서 자세한 정보를 확인하고 기여해 보세요.

버전 5부터 개발 도구에서 변경 사항도 관찰할 수 있게 되었습니다.

개발 도구 설치 및 불러오기

개발 도구는 별도의 패키지로 제공되므로 따로 설치해야 합니다:

$ npm i @tanstack/react-query-devtools
# 또는
$ pnpm add @tanstack/react-query-devtools
# 또는
$ yarn add @tanstack/react-query-devtools
# 또는
$ bun add @tanstack/react-query-devtools
 
shell복사

Next 13+ App Dir을 사용한다면 개발 의존성으로 설치해야 작동합니다.

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

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

기본적으로 React Query 개발 도구는 process.env.NODE_ENV === 'development'일 때만 번들에 포함되므로 프로덕션 빌드에서 제외하는 것을 걱정할 필요가 없습니다.

플로팅 모드

플로팅 모드는 개발 도구를 앱에 고정된 부유 요소로 마운트하고 화면 구석에 개발 도구를 표시하거나 숨기는 토글을 제공합니다. 이 토글 상태는 localStorage에 저장되어 페이지를 새로 고쳐도 유지됩니다.

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

import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
 
function App() {
  return (
    <QueryClientProvider client={queryClient}>
      {/* 애플리케이션의 나머지 부분 */}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  )
}
 
typescript복사

옵션

• 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 대상을 전달하려면 이 옵션을 사용하세요. 그러면 스타일이 head 태그 대신 섀도우 DOM 내에 적용됩니다.

프로덕션 환경의 개발 도구

개발 도구는 프로덕션 빌드에서 제외됩니다. 그러나 프로덕션 환경에서 개발 도구를 지연 로딩하고 싶을 수 있습니다:

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
 
typescript복사

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

최신 번들러

번들러가 패키지 내보내기를 지원한다면 다음과 같은 가져오기 경로를 사용할 수 있습니다:

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

TypeScript를 사용하는 경우 tsconfig에서 moduleResolution: 'nodenext'를 설정해야 합니다. 이 설정은 TypeScript v4.7 이상이 필요합니다.