jotai-tanstack

Jotai + TanStack Query v5 상태관리

상태 유형별 도구

상태 유형	도구	위치
서버 상태 (API 데이터)	TanStack Query v5	packages/shared/queries/
전역 UI/세션 상태	Jotai	packages/shared/atoms/
폼 상태	React Hook Form	컴포넌트 내부
로컬 UI 상태	useState/useReducer	컴포넌트 내부

판단 기준

• 서버에서 온 데이터인가? → React Query
• 여러 컴포넌트가 공유해야 하는 UI 상태인가? → Jotai
• 폼 입력값인가? → React Hook Form
• 이 컴포넌트에서만 쓰는 상태인가? → useState

---

TanStack Query 구조

디렉토리 구조

packages/shared/
├── queries/
│   └── {도메인}/
│       ├── index.ts       # useXxxQuery, useXxxMutation 훅
│       └── queryKeys.ts   # 쿼리 키 정의
├── services/
│   └── {도메인}/
│       ├── index.ts       # API 호출 함수
│       └── types.ts       # 요청/응답 타입

쿼리 키 패턴 (queryKeys 팩토리)

// packages/shared/queries/{도메인}/queryKeys.ts
export const orderKeys = {
  all: ['order'] as const,
  lists: () => [...orderKeys.all, 'list'] as const,
  list: (filters: OrderFilters) => [...orderKeys.lists(), filters] as const,
  details: () => [...orderKeys.all, 'detail'] as const,
  detail: (id: string) => [...orderKeys.details(), id] as const,
};

쿼리 훅 작성 규칙

// packages/shared/queries/{도메인}/index.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { orderKeys } from './queryKeys';
import { orderService } from '@repo/shared/services/order';

export const useOrderQuery = (orderId: string) => {
  return useQuery({
    queryKey: orderKeys.detail(orderId),
    queryFn: () => orderService.getOrder(orderId),
  });
};

export const useUpdateOrderMutation = () => {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: orderService.updateOrder,
    onSuccess: (_, variables) => {
      queryClient.invalidateQueries({
        queryKey: orderKeys.detail(variables.orderId),
      });
    },
  });
};