2nd/10_Wiki/Topic_Programming/Coding/React_Custom_Hook_Patterns.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases, related_existing, duplicate_check

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases	related_existing	duplicate_check
react-custom-hook-patterns	Custom Hook 작성 패턴	Coding	draft	B	conceptual	2026-05-09	2026-05-09	react hooks custom-hook abstraction vibe-coding	language applicable_to TypeScript / React 18+ Web React Native		reusable hook hook composition	Frontend/Custom_Hooks.md Frontend/Custom-Hooks-Patterns.md	기존 두 파일은 폭넓은 개요. 본 문서는 네이밍·반환형·테스트 측면 보강.

Custom Hook 작성 패턴

Custom hook 은 use 로 시작하는 함수 + 다른 hook 호출. 핵심은 이름이 의도를 정확히 말하는가, 반환형이 사용처에 자연스러운가, 테스트 가능한가.

📖 핵심 개념

• 이름: use<Subject><Action> (e.g. useFormSubmit, useDebouncedValue).
• 반환형: 한두 개면 tuple, 셋 이상이면 객체.
• 부작용은 hook 내부 useEffect 로, 호출자는 dispatcher / state 만 받음.

💻 코드 패턴

// ✅ 단일 값 → 그냥 반환
function useDebouncedValue<T>(value: T, ms: number): T {
  const [debounced, setDebounced] = useState(value);
  useEffect(() => {
    const t = setTimeout(() => setDebounced(value), ms);
    return () => clearTimeout(t);
  }, [value, ms]);
  return debounced;
}

// ✅ state + setter — tuple
function useToggle(initial = false): [boolean, () => void] {
  const [v, set] = useState(initial);
  const toggle = useCallback(() => set(x => !x), []);
  return [v, toggle];
}

// ✅ 다중 반환 — 객체 + 명시적 키
function useInfiniteQuery<T>(...): {
  data: T[]; isLoading: boolean; hasNextPage: boolean; fetchNextPage: () => void;
} { ... }

🤔 의사결정 기준

반환 항목 수	형식
1	그대로 반환
2	tuple [value, setter] (useState 패턴)
3+	객체 (key 명시로 가독성)
다양한 변형이 필요	discriminated union 으로 상태 표현

추출 기준	hook
컴포넌트 간 상태 로직 재사용	✅
단일 컴포넌트 내 정리	❌ (그냥 함수)
외부 시스템 동기화 (websocket, sub)	✅
순수 변환만	❌ (일반 함수)

❌ 안티패턴

• use 가 아닌 이름: ESLint hooks 룰 깨짐. 일반 함수로 인식.
• 조건부 hook 호출: if (x) useEffect(...). React rules 위반.
• 반환 객체 매번 새 reference: 호출자 deps 무한 trigger. 내부 useMemo / 안정 참조.
• 부작용 노출: useDebounced 가 ref / dispatcher 노출 — 호출자가 hook 내부 모르고 mutate.
• 테스트 불가능: hook 안에서 Date.now(), Math.random() 직접. 시간/랜덤 주입 가능하게.

🤖 LLM 활용 힌트

• LLM에게 "이 컴포넌트에서 X 로직을 hook 으로 추출" 요청 시 위 네이밍 + 반환형 규칙 강조.
• 테스트는 @testing-library/react 의 renderHook 사용.

🔗 관련 문서

• React_useEffect_Pitfalls
• Pure_Functions_in_Practice