동기

TanStack Query는 강력하지만, 실제 애플리케이션에서 사용하면 마찰이 생깁니다 — 훅 때문에 불필요한 컴포넌트 분리가 필요하고, 서버 사이드 프리페칭에는 보일러플레이트가 많고, 일부 API는 아예 없습니다. @suspensive/react-query는 그 마찰을 제거합니다.

훅 때문에 컴포넌트를 쪼개야 합니다

useSuspenseQuery를 사용하려면 <Suspense> 아래에 별도의 자식 컴포넌트를 만들어야 합니다. Suspensive의 <SuspenseQuery/>를 활용하면 데이터 페칭을 JSX 안에서 바로 선언할 수 있습니다 — 래퍼 컴포넌트도, 인위적인 중첩도 필요 없습니다.

뮤테이션과 프리페칭도 마찬가지입니다. Suspensive의 <Mutation/>과 <PrefetchQuery/>를 활용하면 훅이 사용 불가능한 반복문이나 조건문 안에서도 인라인으로 사용할 수 있습니다.

서버 사이드 프리페칭 보일러플레이트가 너무 많습니다

QueryClient 생성, 쿼리마다 ensureQueryData 호출, HydrationBoundary로 감싸기 — 금방 코드가 불어납니다. Suspensive의 <QueriesHydration/>을 활용하면 쿼리를 한 번 선언하는 것만으로 프리페칭, 디하이드레이션, 하이드레이션을 자동 처리할 수 있습니다.

서버 사이드 프리페칭이 실패하면 대응이 어렵습니다

서버에서 ensureQueryData가 실패하면 쿼리마다 try-catch를 작성하고, fallback을 렌더링하고, 클라이언트에서 재시도할지 결정해야 합니다. Suspensive의 <QueriesHydration/>을 활용하면 skipSsrOnError가 이 모든 것을 처리합니다 — SSR을 건너뛰고 브라우저에서 재시도하거나, 커스텀 fallback을 보여주면서 클라이언트가 이어받게 할 수 있습니다. timeout과 함께 사용하면 느린 쿼리도 전체 페이지를 블로킹하지 않고 클라이언트 사이드 렌더링으로 자연스럽게 전환됩니다.

서버에서 QueryClient가 요청 간 데이터를 공유합니다

서버에서 QueryClient를 공유하면 한 사용자의 요청 데이터가 다른 사용자에게 노출될 수 있습니다. Suspensive의 createGetQueryClient를 활용하면 서버에서는 요청마다 새 인스턴스를, 브라우저에서는 싱글턴을 사용하며 — 안전한 GC 설정이 기본으로 내장되어 있습니다.

v5는 구형 브라우저를 지원하지 않습니다

TanStack Query v5는 ES private fields 때문에 Safari >= 15를 요구하지만, 많은 팀이 여전히 Safari 12–14를 지원해야 합니다. @suspensive/react-query-4를 설치하면 v5 인터페이스를 사용하면서도 구형 브라우저 호환성을 유지할 수 있습니다.

브라우저 호환성 비교

TanStack Query 지원 브라우저	v4	v5
Chrome	>= 73	>= 91
Firefox	>= 78	>= 90
Edge	>= 79	>= 91
Safari	>= 12.1	>= 15
iOS	>= 12.2	>= 15
Opera	>= 53	>= 77

공식 TanStack Query 커뮤니티 리소스입니다

@suspensive/react-query는 TanStack Query 공식 커뮤니티 리소스 로 등록되어 있습니다. 적극적으로 유지보수하고 있으며, 이슈에 신속하게 대응합니다.