본문으로 건너뛰기

DevTools

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

DevTools 활성화​

DevTools는 쿼리와 뮤테이션을 디버깅하고 검사하는 데 도움이 됩니다. provideTanStackQuery에 withDevtools를 추가하여 DevTools를 활성화할 수 있습니다.

기본적으로 Angular Query Devtools는 개발 모드 번들에만 포함되므로 프로덕션 빌드에서 제외할 필요가 없습니다.

import {
  QueryClient,
  provideTanStackQuery,
} from '@tanstack/angular-query-experimental'

import { withDevtools } from '@tanstack/angular-query-experimental/devtools'

export const appConfig: ApplicationConfig = {
  providers: [provideTanStackQuery(new QueryClient(), withDevtools())],
}

프로덕션 환경의 DevTools​

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

프로덕션 빌드에서 withDevtools를 사용하려면 production 하위 경로를 사용해 가져오세요. 프로덕션 하위 경로에서 내보낸 함수는 기본 함수와 동일하지만 프로덕션 빌드에서 제외되지 않습니다.

import { withDevtools } from '@tanstack/angular-query-experimental/devtools/production'

DevTools가 로드되는 시점을 제어하려면 loadDevtools 옵션을 사용할 수 있습니다.

옵션을 설정하지 않거나 'auto'로 설정하면 Angular가 개발 모드에서 실행될 때만 DevTools가 자동으로 로드됩니다.

import { withDevtools } from '@tanstack/angular-query-experimental/devtools'

provideTanStackQuery(new QueryClient(), withDevtools())

// which is equivalent to
provideTanStackQuery(
  new QueryClient(),
  withDevtools(() => ({ loadDevtools: 'auto' })),
)

옵션을 true로 설정하면 devtools가 개발 모드와 프로덕션 모드 모두에서 로드됩니다.

이는 Angular 환경 구성을 기반으로 DevTools를 불러오려는 경우 유용합니다. 예를 들어 애플리케이션이 프로덕션 빌드의 스테이징 환경에서 실행될 때 이를 true로 설정할 수 있습니다.

import { environment } from './environments/environment'
// Make sure to use the production sub-path to load devtools in production builds
import { withDevtools } from '@tanstack/angular-query-experimental/devtools/production'

provideTanStackQuery(
  new QueryClient(),
  withDevtools(() => ({ loadDevtools: environment.loadDevtools })),
)

옵션을 false로 설정하면 DevTools가 로드되지 않습니다.

provideTanStackQuery(
  new QueryClient(),
  withDevtools(() => ({ loadDevtools: false })),
)

반응성을 통해 옵션 도출하기​

signal을 통한 반응성을 지원하기 위해 콜백 함수에서 withDevtools로 옵션을 전달합니다. 다음 예시에서는 키보드 단축키에서 값을 방출하는 RxJS observable로부터 signal이 생성됩니다. 파생된 signal이 true로 설정되면 devtools가 지연 로드됩니다.

아래 예시는 개발 모드에서는 항상 DevTools를 로드하고, 프로덕션 모드에서는 키보드 단축키를 누를 때 필요에 따라 로드합니다.

import { Injectable, isDevMode } from '@angular/core'
import { fromEvent, map, scan } from 'rxjs'
import { toSignal } from '@angular/core/rxjs-interop'

@Injectable({ providedIn: 'root' })
export class DevtoolsOptionsManager {
  loadDevtools = toSignal(
    fromEvent<KeyboardEvent>(document, 'keydown').pipe(
      map(
        (event): boolean =>
          event.metaKey && event.ctrlKey && event.shiftKey && event.key === 'D',
      ),
      scan((acc, curr) => acc || curr, isDevMode()),
    ),
    {
      initialValue: isDevMode(),
    },
  )
}

콜백에서 서비스 같은 주입 가능한 항목을 사용하려면 deps를 사용할 수 있습니다. 주입된 값은 콜백 함수에 매개변수로 전달됩니다.

이는 Angular의 useFactory provider에 있는 deps와 유사합니다.

// ...
// 👇 Note we import from the production sub-path to enable devtools lazy loading in production builds
import { withDevtools } from '@tanstack/angular-query-experimental/devtools/production'

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(),
    provideTanStackQuery(
      new QueryClient(),
      withDevtools(
        (devToolsOptionsManager: DevtoolsOptionsManager) => ({
          loadDevtools: devToolsOptionsManager.loadDevtools(),
        }),
        {
          // `deps` is used to inject and pass `DevtoolsOptionsManager` to the `withDevtools` callback.
          deps: [DevtoolsOptionsManager],
        },
      ),
    ),
  ],
}

콜백에서 반환되는 옵션​

이 옵션 중 loadDevtools, client, position, errorTypes, buttonPosition, initialIsOpen 및 theme은 signal을 통한 반응성을 지원합니다.

  • loadDevtools?: 'auto' | boolean
    • 기본값은 auto입니다: 개발 모드에서는 devtools를 지연 로드합니다. 프로덕션 모드에서는 로드를 건너뜁니다.
    • DevTools를 로드할지 제어하려면 이를 사용합니다.
  • initialIsOpen?: Boolean
    • 도구가 기본적으로 열린 상태가 되게 하려면 이를 true로 설정합니다
  • buttonPosition?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "relative"
    • 기본값은 bottom-right입니다
    • DevTools 패널을 열고 닫는 TanStack 로고의 위치
    • relative이면 버튼은 DevTools를 렌더링하는 위치에 배치됩니다.
  • position?: "top" | "bottom" | "left" | "right"
    • 기본값은 bottom입니다
    • Angular Query DevTools 패널의 위치
  • client?: QueryClient,
    • 사용자 지정 QueryClient를 사용하려면 이것을 사용합니다. 그렇지 않으면 provideTanStackQuery를 통해 제공된 QueryClient가 주입됩니다.
  • 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 내부에 적용됩니다.
  • hideDisabledQueries?: boolean
    • 비활성화된 쿼리를 DevTools 패널에서 숨기려면 이를 true로 설정합니다.
  • theme?: "light" | "dark" | "system"
    • 기본값은 system입니다.
    • devtools 패널의 테마를 변경하려면 이를 설정합니다.