버전 안내: 이 문서는 2.x 기준입니다. 실제 게시 버전은 위 npm 배지에서 확인하세요. 1.x를 사용 중이라면 1.3.0 문서와 마이그레이션 가이드를 참고하세요. 아직 게시되지 않은 변경은 소스에서 설치할 수 있습니다.

무엇을 줄여주나요?

같은 API를 컴포넌트, prefetch, 캐시 조회에서 사용할 때 반복되는 키와 옵션 구성을 줄입니다. 훅이나 HTTP 클라이언트를 새로 만들지 않습니다. 기존 API 함수와 TanStack Query를 그대로 사용합니다.

| 직접 관리하던 것 | 생성 후 | | -------------------------- | --------------------------------------------------------- | | 곳곳에 흩어진 쿼리 키 | 파일 경로·함수명·인자를 반영한 키 | | 같은 요청을 위한 반복 옵션 | useQuery, useSuspenseQuery, fetch/prefetch에서 재사용 | | API와 별도로 유지하는 타입 | 인자·응답·select·캐시 데이터 타입 추론 | | API 변경 후 생성 파일 정리 | watch 재생성, 오래된 소유 파일 정리, CI의 --check |

기본 캐싱 정책과 재시도는 TanStack Query/QueryClient를 따릅니다. 이름 기반 생성 규칙은 설정으로 재정의할 수 있습니다.

빠른 시작

1. 설치하고 초기화

npm install @uiwwsw/react-query-helper@^2 @tanstack/react-query react
npx @uiwwsw/react-query-helper init

생성 코드가 이 패키지를 import하므로 -D가 아닌 일반 dependency로 설치합니다. React와 TanStack Query가 이미 설치되어 있다면 필요한 의존성만 추가하세요.

2. API 경로 지정

init이 만든 rqh.config.ts의 경로를 앱 구조에 맞춥니다. 별도 플러그인이나 alias 설정 없이 시작할 수 있습니다.

// rqh.config.ts
import type { AutoQueryConfig } from "@uiwwsw/react-query-helper/config";

export default {
  sourceDir: "./libs",
  outputDir: "./src/options",
  ignoredFiles: ["domain.ts", "adaptor.ts", "**/*.test.ts", "**/*.spec.ts"],
  template: { artifactStrategy: "smart" },
} satisfies AutoQueryConfig;

실제 API 함수를 해당 디렉토리에 두세요. 아래는 흐름을 확인하기 위한 간단한 예시입니다.

// libs/users/api.ts
export const getUser = async (id: string) => ({ id, name: "Ada" });

3. 생성하고 사용

npx @uiwwsw/react-query-helper generate

src/options/users/apiOptions.ts에 getUserKey, getUserQueryOption, getUserInfiniteQueryOption이 생성됩니다. 생성 파일 대신 원본 API를 수정하세요. 무한 쿼리 팩토리도 생성되지만 실제 페이지네이션 설정은 API에 맞게 별도로 지정합니다.

// src/UserName.tsx
import { useQuery } from "@tanstack/react-query";
import { getUserQueryOption } from "./options/users/apiOptions";

export function UserName({ id }: { id: string }) {
  const user = useQuery(
    getUserQueryOption.withOptions(
      { staleTime: 60_000, select: (data) => data.name },
      id,
    ),
  );

  if (user.isPending) return <p>Loading...</p>;
  if (user.isError) return <p>{user.error.message}</p>;
  return <p>{user.data}</p>;
}

앱 상위에 QueryClientProvider가 필요합니다. 위의 user.data는 select에 따라 string으로 추론됩니다. 옵션은 훅 바깥에서도 재사용할 수 있습니다.

// 기존 QueryClient 인스턴스 client에서
await client.prefetchQuery(getUserQueryOption("u1"));
const cached = client.getQueryData(getUserQueryOption("u1").queryKey);
// { id: string; name: string } | undefined

4. 개발 흐름에 연결

{
  "scripts": {
    "query:generate": "react-query-helper generate",
    "query:watch": "react-query-helper watch",
    "query:check": "react-query-helper generate --check"
  }
}

개발할 때는 npm run query:watch, 앱 CI에서는 npm run query:check를 실행하세요. check는 파일을 수정하지 않고 누락·변경·오래된 결과를 발견하면 종료 코드 1을 반환합니다. 생성물을 커밋하지 않는 프로젝트라면 CI에서 query:generate 후 앱 타입 검사를 실행하세요.

필요한 예제 찾기

| 하고 싶은 일 | 가이드 | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------- | | 설정 파일, 경로, ignore glob 변경 | 설정 | | 함수별 query/mutation 생성 제어 | 생성 규칙과 캐시 키 | | mutation 인자, 취소, 옵션 확장 | 런타임 옵션 | | 커서 페이지네이션과 maxPages | 무한 쿼리 | | 기존 1.x 프로젝트 업그레이드 | 마이그레이션 체크리스트 | | 지원하지 않는 문법, 커스텀 플러그인 | 지원 범위와 확장 | | 테스트, 로컬 설치, npm 배포 설정 | 개발과 배포 | | 이번 개선의 근거와 남은 한계 | 저장소 검토 기록 |

지원 환경과 주의점

| 구분 | 지원 기준 | | -------------- | -------------------------------------------------- | | Node.js | CLI/빌드에 22 이상, CI는 22/24 | | React | 18/19 | | TanStack Query | >=5.102.8 <6 | | TypeScript | 5.8 이상, 생성 코드는 TS 번들러용 | | 브라우저 | 루트 import는 브라우저용, Node 도구는 별도 subpath |

• 2.x는 호환성을 깨는 변경입니다. 기존 생성 파일을 옮긴 뒤 재생성하고, 수동 키와 persisted cache를 마이그레이션하세요.
• API 인자는 캐시 키에 포함됩니다. 직렬화 가능한 값만 전달하고 토큰·인증 헤더는 넣지 마세요.
• 페이지네이션과 요청 취소는 자동 추측하지 않습니다. 커서 매핑과 AbortSignal 전달은 API에 맞춰 설정하세요.
• 최상위 함수가 기본 대상입니다. re-export barrel, 메서드, 모든 generic/overload 관계를 처리하는 범용 TypeScript 변환기는 아닙니다.

변경 이력 · 로고와 브랜드 자산 · MIT License

독립적인 커뮤니티 도구이며 React 또는 TanStack의 공식 프로젝트가 아닙니다.