@howmuchhome-web/utils-react-query

API 메서드와 React Query를 연결하는 훅 및 서버 유틸리티 패키지입니다. 사용법 개요는 API 관리를, 컨벤션은 API 컨벤션을 참고하세요.

클라이언트 훅

useAPIQuery

단일 데이터를 조회하는 Suspense 기반 쿼리 훅입니다. @QueryOptions 데코레이터가 적용된 API 메서드와 함께 사용합니다.


import {useAPIQuery} from '@howmuchhome-web/utils-react-query';
 
const {data} = useAPIQuery(SomeAPI.getResource, {id});
 
// 옵션 재정의
const {data} = useAPIQuery(SomeAPI.getResource, {id}, {
  staleTime: 1000 * 60 * 5,
});

인자	타입	설명
`method`	API 메서드	`@QueryOptions` 데코레이터 필요
`args`	메서드 인자	메서드가 인자를 받지 않는 경우 생략 가능
`overrideOptions`	`UseSuspenseQueryOptions`	`queryKey`, `queryFn` 제외한 옵션 재정의

useAPIMutation

데이터를 변경하는 뮤테이션 훅입니다.


import {useAPIMutation} from '@howmuchhome-web/utils-react-query';
 
const mutation = useAPIMutation(SomeAPI.createResource);
 
await mutation.mutateAsync({name: 'value'});
// 또는
mutation.mutate({name: 'value'}, {onSuccess: () => { ... }});

인자	타입	설명
`mutationFn`	API 메서드	`@MutationOptions` 데코레이터 선택
`overrideOptions`	`UseMutationOptions`	`onSuccess`, `onError`, `onMutate` 등

useAPIInfiniteQuery

무한 스크롤 / 페이지네이션 쿼리 훅입니다. @InfiniteQueryOptions 데코레이터가 적용된 API 메서드와 함께 사용합니다.


import {useAPIInfiniteQuery} from '@howmuchhome-web/utils-react-query';
 
const {data, fetchNextPage, hasNextPage} = useAPIInfiniteQuery(
  SomeAPI.getList,
  {unionId},
);
 
// data.pages: 각 페이지 데이터 배열
// data.pages[n].data: n번째 페이지 아이템 목록
// data.pages[n].isLast: 마지막 페이지 여부

useAPIQueries

여러 쿼리를 병렬로 실행합니다.


import {useAPIQueries} from '@howmuchhome-web/utils-react-query';
 
const [voteResult, userResult] = useAPIQueries({
  queries: [
    VoteAPI.getVoteDetail.queryOptions({voteId}),
    UserAPI.getMe.queryOptions(undefined),
  ],
});

서버 유틸리티

@howmuchhome-web/utils-react-query/server에서 가져옵니다.

fetchAPIQuery

서버 컴포넌트에서 데이터를 미리 fetch해 쿼리 캐시를 채웁니다.


import {fetchAPIQuery} from '@howmuchhome-web/utils-react-query/server';
 
await fetchAPIQuery(VoteAPI.getVoteDetail, {voteId});

fetchAPIInfiniteQuery

무한 쿼리 데이터를 서버에서 미리 fetch합니다.


import {fetchAPIInfiniteQuery} from '@howmuchhome-web/utils-react-query/server';
 
await fetchAPIInfiniteQuery(CafeAPI.getPostList, {unionId});

Hydration

서버에서 채운 쿼리 캐시를 클라이언트로 전달하는 컴포넌트입니다. fetchAPIQuery와 함께 사용합니다.


import {Hydration} from '@howmuchhome-web/utils-react-query/server';
 
export default async function Page() {
  await fetchAPIQuery(VoteAPI.getVoteDetail, {voteId});
 
  return (
    <Hydration>
      <VoteDetail voteId={voteId} />
    </Hydration>
  );
}

getQueryClient

서버에서 쿼리 클라이언트 인스턴스를 가져옵니다. React cache()로 감싸져 있어 같은 요청 내에서 중복 생성되지 않습니다.


import {getQueryClient} from '@howmuchhome-web/utils-react-query/server';
 
const queryClient = getQueryClient();

공통 유틸리티

getQueryKey

API 메서드에서 쿼리 키를 추출합니다. 수동 캐시 무효화에 사용합니다.


import {getQueryKey} from '@howmuchhome-web/utils-react-query';
 
queryClient.invalidateQueries({
  queryKey: getQueryKey(VoteAPI.getVoteDetail, {voteId}),
});

updateInfiniteQueryData

무한 쿼리 캐시에서 특정 조건에 맞는 아이템만 업데이트합니다.


import {updateInfiniteQueryData} from '@howmuchhome-web/utils-react-query';
 
updateInfiniteQueryData({
  queryClient,
  queryKey: getQueryKey(CafeAPI.getPostList, {unionId}),
  condition: (item) => item.id === targetId,
  updater: (item) => ({...item, likeCount: item.likeCount + 1}),
});

옵션	설명
`queryClient`	쿼리 클라이언트 인스턴스
`queryKey`	업데이트할 쿼리 키
`condition`	업데이트 대상 아이템 판별 함수
`updater`	아이템을 받아 새 아이템을 반환하는 함수
`function`	`'setQueryData'`(기본) 또는 `'setQueriesData'`

프로바이더

TanstackQueryProvider

앱 최상위에 한 번 배치합니다.


import {TanstackQueryProvider} from '@howmuchhome-web/utils-react-query';
 
export default function RootLayout({children}) {
  return <TanstackQueryProvider>{children}</TanstackQueryProvider>;
}

QueryOptionsOverrider

하위 트리의 기본 쿼리 옵션을 재정의합니다. 테스트나 특수 환경에서 사용합니다.


import {QueryOptionsOverrider} from '@howmuchhome-web/utils-react-query';
 
<QueryOptionsOverrider options={{queries: {staleTime: Infinity}}}>
  <SomeComponent />
</QueryOptionsOverrider>