새로운 TanStack React Query 통합 기능 소개

비공식 베타 번역

이 페이지는 PageTurner AI로 번역되었습니다(베타). 프로젝트 공식 승인을 받지 않았습니다. 오류를 발견하셨나요? 문제 신고 →

tRPC의 next 릴리스에서 이제 새로운 TanStack React Query 통합 기능을 사용할 수 있게 되어 기쁘게 생각합니다. 기존의 React Query 통합과 비교했을 때, 이번 통합은 더 간결하고 TanStack Query의 본질에 가까우며, 자체 클라이언트로 useQuery 및 useMutation을 래핑하는 대신 TanStack React Query의 기본 인터페이스인 QueryOptions와 MutationOptions를 직접 활용합니다.

greeting.tsx
tsx
import { useQuery } from '@tanstack/react-query';
import { useTRPC } from './trpc';
export function Greeting() {
  const trpc = useTRPC();
  const greetingQuery = useQuery(trpc.greeting.queryOptions({ name: 'Jerry' }));
  // greetingQuery.data === 'Hello Jerry'
  // [...]
}

greeting.tsx
tsx
import { useQuery } from '@tanstack/react-query';
import { useTRPC } from './trpc';
export function Greeting() {
  const trpc = useTRPC();
  const greetingQuery = useQuery(trpc.greeting.queryOptions({ name: 'Jerry' }));
  // greetingQuery.data === 'Hello Jerry'
  // [...]
}

이 새로운 클라이언트는 신규 사용자들에게 흔히 혼란을 주는 추상화 계층을 제거하고, TanStack의 공식 문서를 따르는 분들에게 즉시 익숙하게 느껴질 직관적인 작업 방식을 제공합니다. 또한 tRPC 문서로 설명해야 할 내용이 줄어들었으며, 시작을 돕기 위한 설명서도 마련되어 있습니다.

변경 배경

상세한 내용은 이 변경의 근간이 된 원본 RFC를 여기에서 확인하실 수 있습니다. 주요 이유는 다음과 같습니다:

• 간결성: 새로운 클라이언트는 더 단순하고 TanStack Query에 가깝게 설계되었으며, QueryKeys, QueryOptions, MutationOptions와 같은 일반적인 인터페이스를 위한 팩토리를 제공합니다. 이로 인해 공식 TanStack Query 문서를 그대로 따라갈 수 있어 학습 곡선이 낮아집니다.

• 친숙성: 이미 TanStack Query를 사용 중인 개발자들에게 더 익숙한 방식으로, 애플리케이션 내 다른 작업에 TanStack Query를 사용할 때 tRPC를 위해 별도의 문법을 강제하지 않습니다.

• React 적합성: 기존 React Query 통합은 실제로 훅 규칙을 위반합니다. 린팅이 정확히 불가능하며, 훅을 props로 전달하는 등 React 컴파일러에서 문제를 일으킬 수 있는 패턴을 유도합니다. 이 측면에서 새로운 클라이언트는 더 React의 관용적 방식에 부합합니다.

• 유지보수성: 버전 관리에서의 어려움은 tRPC가 TanStack Query의 변화(특히 QueryClient에 주기적으로 추가되는 신기능)와 동기화를 유지하는 데 있었습니다. 기본 인터페이스의 작은 접점을 활용함으로써 React Query 지원이 훨씬 수월해졌으며, TanStack 유지보수자가 권장하는 모범 사례를 따르게 되었습니다.

• 피드백: 기존 클라이언트가 신규 사용자에게 흔히 어려움을 주는 원인이었던 만큼, 이 RFC에 대한 피드백은 압도적으로 긍정적이었으며, 대다수의 사용자가 이 클라이언트 사용을 기대한다는 의견을 남겼습니다. 물론 모든 사용자가 현재 이 클라이언트에 동의하는 것은 아니므로, 기존 클라이언트도 계속 유지할 예정입니다.

기존 tRPC React Query 통합 기능의 향후 계획

당분간 사라지지 않을 예정입니다! 오랜 기간 유지보수를 약속드리지만, 중대한 신기능은 추가되지 않을 것이며 안정화된 상태로 간주될 것입니다.

신규 프로젝트는 새로운 TanStack React Query 통합 기능으로 시작하고, 기존 프로젝트는 점진적 마이그레이션을 고려해 보시길 권장합니다.

마이그레이션 방법

기존 클라이언트는 오랜 기간 유지보수될 예정이지만, 신규 프로젝트는 새 클라이언트로 시작하고 활성 프로젝트는 점진적 전환을 고려해 보시길 권장합니다.

두 클라이언트는 상호 호환되며 동일 애플리케이션 내 공존이 가능하므로, 본인의 페이스대로 마이그레이션할 수 있습니다. 또한 커뮤니티 기여를 간절히 환영하는 코드모드 작업도 진행 중입니다. 지금까지 코드모드에 기여해 주신 @reaper 님께 감사드립니다!

👉 마이그레이션 문서 읽기