왜 nuqs인가

이미 널리 사용되고 있습니다

nuqs(구 next-usequerystate)는 Next.js 생태계에서 URL 상태 관리의 사실상 표준으로 자리잡았습니다. 공식 Next.js 문서에서도 search params 관리 시 참조되는 라이브러리입니다.

필터 상태가 URL에 자동으로 반영됩니다

사용자가 Sent 탭에서 DELIVERED 필터를 적용하고 2페이지를 보고 있다면, URL이 아래처럼 바뀝니다. 이 URL을 복사해서 공유하거나, 새로고침해도 동일한 상태가 복원됩니다.

수동 배관 코드가 선언적 파서로 대체됩니다

// 모듈 레벨 동기 hydration hack
// qs.parse() 수동 파싱
// ensureArray() 헬퍼
// .map(Number).filter(isInteger)
// subscribe() + debounce 300ms
// equality check
// window.history.replaceState()
// whitelist 검증

parseAsArrayOf(parseAsInteger)
  .withDefault([])

// ✓ 배열 파싱 — 자동
// ✓ 숫자 변환 — 자동
// ✓ 기본값 처리 — 자동
// ✓ URL 동기화 — 자동
// ✓ hydration — React 표준

수동 구현에서 발견된 3가지 CRITICAL 이슈가 사라집니다

기획 요구사항이 모두 자연스럽게 충족됩니다

URL 파라미터 설계

실제 구현 코드

1. URL 파서 정의

import {
  parseAsString, parseAsInteger, parseAsArrayOf,
  parseAsStringLiteral,
} from 'nuqs'
import { useQueryStates } from 'nuqs'

const tabValues = ['inbox', 'sent'] as const
const listValues = ['all', 'buyers'] as const
const statusValues = ['ALL', 'PENDING', 'DELIVERED', 'FAILED'] as const

const emailSearchParams = {
  tab:      parseAsStringLiteral(tabValues).withDefault('inbox'),
  list:     parseAsStringLiteral(listValues).withDefault('all'),
  q:        parseAsString.withDefault(''),
  accounts: parseAsArrayOf(parseAsString).withDefault([]),
  status:   parseAsStringLiteral(statusValues).withDefault('ALL'),
  buyers:   parseAsArrayOf(parseAsInteger).withDefault([]),
  page:     parseAsInteger.withDefault(1),
  size:     parseAsInteger.withDefault(20),
}

2. 래퍼 훅 — 기존 인터페이스 유지

export function useEmailPageParams() {
  const [params, setParams] = useQueryStates(emailSearchParams, {
    history: 'replace',
    throttleMs: 300,
  })

  // 탭 전환 → 전체 필터 atomic 리셋
  const setActiveTab = (tab: typeof params.tab) =>
    setParams({ tab, list:'all', q:'', accounts:[], status:'ALL', buyers:[], page:1 })

  const resetFilters = () =>
    setParams({ list:'all', q:'', accounts:[], status:'ALL', buyers:[], page:1 })

  return {
    // 기존 이름 alias — 소비자 변경 최소화
    activeTab: params.tab,
    activeListFilter: params.list,
    searchQuery: params.q,
    accountFilters: params.accounts,
    statusFilter: params.status,
    buyerFilters: params.buyers,
    currentPage: params.page,
    perPage: params.size,
    // actions
    setActiveTab,
    resetFilters,
    setStatusFilter: (s) => setParams({ status: s, page: 1 }),
    setCurrentPage: (p) => setParams({ page: p }),
    setPerPage: (s) => setParams({ size: s, page: 1 }),
    setBuyerFilters: (b) => setParams({ buyers: b, page: 1 }),
    setActiveListFilter: (l) => setParams({ list: l, page: 1 }),
    setSearchQuery: (q) => setParams({ q }),
    setAccountFilters: (a) => setParams({ accounts: a, page: 1 }),
    clearSearch: () => setParams({ q: '' }),
  }
}

3. 소비자 변경 — import 한 줄

// Before
const { activeTab, statusFilter } = useEmailPageStore(
  useShallow(s => ({ activeTab: s.activeTab, statusFilter: s.statusFilter }))
)

// After — useShallow도 불필요
const { activeTab, statusFilter } = useEmailPageParams()

수정 파일 목록

마이그레이션 타임라인

왜 nuqs인가 — 한 눈에

향후 검토 사항