🎧

nuqs는 Next.js에서 URL 쿼리 파라미터를 상태처럼 쉽게 관리할 수 있게 해주는 라이브러리이다.

오늘은 'nuqs'의 useQueryState에 대해 알아볼 것이다.

기본 개념

useQueryState는 React의 useState와 비슷하게 동작하지만, 상태를 컴포넌트 내부가 아닌 URL 쿼리 파라미터에 저장합니다.

import { useQueryState } from 'nuqs'

function SearchComponent() {
  const [search, setSearch] = useQueryState('search')
  
  // URL: /?search=hello
  // search 값: "hello"
  
  return (
    <input 
      value={search || ''} 
      onChange={(e) => setSearch(e.target.value)}
    />
  )
}

주요 특징

URL과 자동 동기화

• 상태가 변경되면 URL이 자동으로 업데이트됩니다
• 뒤로가기/앞으로가기 버튼이 정상 작동합니다
• URL을 공유하면 같은 상태를 공유할 수 있습니다

타입 안전성

• 파서(parser)를 사용해 타입을 지정할 수 있습니다

import { useQueryState, parseAsInteger, parseAsBoolean } from 'nuqs'

const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1))
const [isActive, setIsActive] = useQueryState('active', parseAsBoolean)

기본값 설정

const [sort, setSort] = useQueryState('sort', { defaultValue: 'name' })

여러 파라미터 동시 관리

import { useQueryStates } from 'nuqs'

const [filters, setFilters] = useQueryStates({
  search: parseAsString,
  page: parseAsInteger.withDefault(1),
  category: parseAsString
})

// 여러 값을 한 번에 업데이트
setFilters({ search: 'test', page: 1 })

실제 사용 예시

검색과 필터링이 있는 상품 목록:

function ProductList() {
  const [search, setSearch] = useQueryState('search')
  const [category, setCategory] = useQueryState('category')
  const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1))

  return (
    <div>
      <input 
        value={search || ''} 
        onChange={(e) => setSearch(e.target.value)}
        placeholder="검색..."
      />
      
      <select 
        value={category || ''} 
        onChange={(e) => setCategory(e.target.value)}
      >
        <option value="">전체</option>
        <option value="electronics">전자제품</option>
        <option value="clothing">의류</option>
      </select>
      
      {/* URL: /?search=laptop&category=electronics&page=2 */}
    </div>
  )
}

장점

• SEO 친화적: 필터링된 상태가 URL에 있어 크롤러가 인덱싱 가능
• 공유 가능: URL만으로 정확한 페이지 상태 공유
• 새로고침 안전: 페이지를 새로고침해도 상태 유지
• 브라우저 히스토리: 뒤로가기/앞으로가기 지원

Next.js의 App Router와 Pages Router 모두에서 사용할 수 있으며, 특히 검색, 필터링, 페이지네이션 같은 기능을 구현할 때 매우 유용합니다.