nuqs를 사용한 검색 기능

nuqs 검색 기능 구현 과정 정리

1. 어떤 문제점이 있었는지

초기 문제상황

• 실시간 API 호출 문제: 사용자가 검색어를 타이핑할 때마다 API가 즉시 호출됨

• 성능 이슈: 불필요한 네트워크 요청이 과도하게 발생

• 사용자 경험 저하: 타이핑 중에 계속해서 로딩이 발생하고 서버 부하 증가

• 비효율적인 리소스 사용: 완성되지 않은 검색어로도 API 요청이 발생

근본 원인

• useQueryState를 직접 API 호출에 연결했을 때, 상태 변경 시마다 즉시 API가 실행되는 구조

2. nuqs를 사용하려고 한 이유

URL 상태 관리의 필요성

• 검색 상태의 지속성: 페이지 새로고침 후에도 검색어가 유지되어야 함

• 공유 가능한 URL: 특정 검색 결과를 URL로 공유할 수 있어야 함

• 브라우저 히스토리: 뒤로가기/앞으로가기 버튼으로 검색 히스토리 탐색 가능

• SEO 및 북마크: 검색 상태가 URL에 반영되어 검색엔진 최적화와 북마크 기능 지원

nuqs 선택 이유

• Next.js와의 완벽한 호환성

• 타입 안전성 제공

• 간단한 API로 URL 상태 관리 가능

3. nuqs를 사용하면서 문제를 어떻게 해결하려고 했는지

첫 번째 시도: useState + useEffect 조합

const [search, setSearch] = useQueryState('search');
const [debouncedSearch, setDebouncedSearch] = useState(search ?? '');

useEffect(() => {
  const timer = setTimeout(() => {
    setDebouncedSearch(search ?? '');
  }, 500);
  return () => clearTimeout(timer);
}, [search]);

• 별도의 debounced 상태를 만들어 API 호출 지연

두 번째 시도: nuqs 내장 옵션 활용

const [search, setSearch] = useQueryState('search', {
  limitUrlUpdates: {
    method: 'debounce', // 또는 'throttle'
    timeMs: 500,
  },
});

• nuqs의 내장 debounce 기능 활용 시도

문제점 발견

• limitUrlUpdates는 URL 업데이트만 debounce하지만, useQueryState의 반환값 자체는 즉시 변경됨

• 따라서 여전히 API가 즉시 호출되는 문제 지속

4. 실제로 문제를 어떻게 해결했는지

최종 해결책: 역할 분리 + useSearchParams 활용

BlogHeader (검색 입력 처리)

const [search, setSearch] = useQueryState('search', {
  limitUrlUpdates: {
    method: 'debounce',
    timeMs: 500,
  },
});

• 타이핑 시 즉시 UI 반응

• 500ms 후 URL 업데이트

BlogMainPage (API 호출)

const searchParams = useSearchParams();
const search = searchParams.get('search');

const { posts, isLoading } = usePost({
  search: search ?? '',
  page: 1,
  limit: 10,
});

• useSearchParams로 URL에서 직접 파라미터 읽기

• URL이 실제로 변경될 때만 컴포넌트 리렌더링 및 API 호출

해결책의 핵심 원리

1. 입력과 API 호출 분리: 입력 처리와 API 호출을 서로 다른 컴포넌트에서 담당

2. URL 기반 상태 관리: URL이 단일 진실 공급원(Single Source of Truth) 역할

3. debounce된 URL 업데이트: 사용자 입력은 즉시 반영되지만 URL은 debounce로 업데이트

4. React 렌더링 최적화: useSearchParams는 URL 변경 시에만 리렌더링 트리거

최종 결과

• 사용자 타이핑 시 즉시 UI 반응 (UX 향상)

• API 호출은 500ms debounce로 최적화 (성능 향상)

• URL 상태 관리로 검색 결과 공유 및 북마크 가능

• 브라우저 히스토리 완전 지원