TanStack Query v4, 5를 모두 지원

@suspensive/react-query는 내부적으로 @tanstack/react-query의 버전에 대응하여 인터페이스를 제공하는 @suspensive/react-query-4와 @suspensive/react-query-5로 구성되어 있습니다. 사용자 환경에 설치된 @tanstack/react-query 버전을 감지하여 자동으로 호환되는 인터페이스를 제공합니다.

Command-Line Interface (CLI)

@suspensive/react-query의 Command-Line Interface (CLI)는 @tanstack/react-query와의 호환성 문제를 해결하기 위한 도구입니다. 명령어를 통해 사용자 환경에 설치된 @tanstack/react-query와의 호환성을 확인하고, @suspensive/react-query의 인터페이스를 호환되는 인터페이스로 전환할 수 있습니다.

하지만 실제로 CLI를 사용할 일은 드물며, @suspensive/react-query 설치 시 자동으로 사용자 환경에 설치된 @tanstack/react-query과 호환되는 인터페이스를 제공합니다.

시작하기

CLI는 @suspensive/react-query 패키지에 포함되어 있습니다. 추가적인 설치는 필요 없으며, 아래 명령어를 통해 바로 사용할 수 있습니다.

npx suspensive-react-query

또는 간단히 srq로도 사용할 수 있습니다.

npx srq

명령어

현재 CLI가 제공하는 명령어는 총 5개로, 각 명령어의 설명은 다음과 같습니다.

version

현재 설치된 @suspensive/react-query의 버전을 표시합니다. 이는 패키지의 버전으로 package.json에 명시된 버전을 표시하며, @tanstack/react-query와 호환되도록 내부적으로 구성하는 @suspensive/react-query-4 또는 @suspensive/react-query-5의 버전을 의미하지는 않습니다.

npx suspensive-react-query -v

또는

npx suspensive-react-query --version

help

명령어의 사용 방법을 콘솔에서 확인할 수 있습니다. 예를 들어 fix 명령어에 대해 자세히 알고 싶다면, 다음과 같이 명령어를 사용하여 확인할 수 있습니다.

npx suspensive-react-query fix -h

또는

npx suspensive-react-query --help

status

현재 사용자 환경에 설치된 @tanstack/react-query와 @suspensive/react-query의 호환성 상태를 확인할 수 있으며, 사용 가능한 인터페이스 항목에서 어떤 인터페이스가 현재 환경에서 사용 가능한지 확인할 수 있습니다.

npx suspensive-react-query status

예를 들어, @suspensive/react-query@2.12.1 버전과 @tanstack/react-query@5.51.21 버전을 사용 중인 경우, 다음과 같은 결과를 확인할 수 있습니다.

┌─────────────────────────────────────────┬──────────┬────────────────────────────────────┐
│ @suspensive/react-query@2.12.1          │ status   │ available interfaces               │
├──────────┬──────────────────────────────┼──────────┼────────────────────────────────────┤
│ exports  │ @suspensive/react-query-5    │ 🟢       │ SuspenseQuery SuspenseQueries      │
│ from     │ @2.12.1                      │          │ SuspenseInfiniteQuery              │
│          │                              │          │ QueryErrorBoundary Mutation        │
│          ├──────────────────────────────┼──────────┼────────────────────────────────────┤
│          │ @tanstack/react-query        │ 🟢       │ useSuspenseQuery                   │
│          │ @5.51.21                     │          │ useSuspenseQueries                 │
│          │                              │          │ useSuspenseInfiniteQuery           │
│          │                              │          │ queryOptions infiniteQueryOptions  │
└──────────┴──────────────────────────────┴──────────┴────────────────────────────────────┘

switch

사용자 환경에 설치된 @tanstack/react-query의 version과 호환되는 Suspensive 인터페이스를 사용하도록 @suspensive/react-query의 내보내기(exports)를 전환합니다. 이 작업은 @suspensive/react-query의 엔트리 파일(dist/index.js)을 업데이트하여 수행됩니다.

// dist/index.js of @suspensive/react-query
 
// "npx suspensive-react-query switch 4"를 사용할 때
// @suspensive/react-query의 dist/index.js
export * from '@suspensive/react-query-4' // @tanstack/react-query@4용 Suspensive 인터페이스
// "npx suspensive-react-query switch 5"를 사용할 때
// @suspensive/react-query의 dist/index.js
export * from '@suspensive/react-query-5' // @tanstack/react-query@5용 Suspensive 인터페이스

@tanstack/react-query v5를 사용하고 있는데 오류가 발생하면, 다음 명령어를 사용하여 엔트리 파일(dist/index.js)을 업데이트하여 호환되는 인터페이스로 전환할 수 있습니다.

npx suspensive-react-query switch 5

fix

fix 명령어는 @suspensive/react-query와 @tanstack/react-query이 호환되지 않는 환경에서 손쉽게 버전을 맞추는 간편한 방법입니다. 사용자 환경의 @tanstack/react-query의 버전과 호환되는 Suspensive 인터페이스를 사용하도록 @suspensive/react-query의 내보내기(exports)를 자동으로 전환합니다.

npx suspensive-react-query fix

문제 해결

빌드 중 @suspensive/react-query에 대한 오류가 발생하면, 대부분 설치된 @tanstack/react-query와의 호환성 문제로 발생되는 것입니다.

다음과 같은 방법으로 package.json에 사용하고자 하는 버전을 지정할 수 있습니다. 빌드 시 자동으로 올바른 버전을 사용하게 하려면 다음과 같이 스크립트를 사용할 수 있습니다.

{
  "scripts": {
    "build": "suspensive-react-query fix && next build"
  }
}

또는 @suspensive/react-query의 버전을 고정하려면 다음과 같이 설정할 수 있습니다.

{
  "scripts": {
    "build": "suspensive-react-query switch 5 && next build"
  }
}