Next.js에서 URLSearchParams를 수동으로 관리하지 마세요 — 대신 nuqs 사용

Source: Dev.to

현대 웹 애플리케이션은 종종 UI 상태를 URL에 나타냅니다. 예를 들어:

• 검색 필터
• 페이지네이션
• 정렬
• 탭 선택
• 대시보드 파라미터

일반적인 URL은 다음과 같습니다:

/products?category=books&sort=price&page=2

UI 상태를 URL과 동기화하면 여러 가지가 개선됩니다:

• 공유 가능성 – 사용자가 필터링된 뷰를 공유할 수 있습니다
• 북마크
• 브라우저 탐색 (뒤로/앞으로)
• 예측 가능한 애플리케이션 상태

하지만 Next.js App Router에서 이를 구현하면 반복적이고 취약한 코드가 생기기 쉽습니다.

최근 nuqs라는 라이브러리를 사용하기 시작했으며, URL 상태를 관리할 때 개발자 경험이 크게 향상되었습니다.

이 글에서는 다음 내용을 다룹니다:

• 쿼리 파라미터를 수동으로 관리하는 것이 왜 어려운지
• 내가 nuqs를 선택한 이유
• 실제 프로젝트에서 사용하는 방법
• 개발 워크플로우에서 개선된 점

문제: 수동 URL 상태 관리

헬퍼 라이브러리 없이 URL 상태를 관리하려면 보통 다음을 조합해야 합니다:

• useSearchParams
• useRouter
• URLSearchParams
• useState
• useEffect

예시

'use client'

import { useRouter, useSearchParams } from 'next/navigation'
import { useState, useEffect } from 'react'

export default function ProductFilter() {
  const router = useRouter()
  const searchParams = useSearchParams()

  const [category, setCategory] = useState(
    searchParams.get('category') ?? ''
  )

  useEffect(() => {
    const params = new URLSearchParams(searchParams)
    params.set('category', category)

    router.push(`?${params.toString()}`)
  }, [category, router, searchParams])

  return (
     setCategory(e.target.value)}
    >
      All
      Books
      Games
    
  )
}

문제점 ⚡️

• 어디서든 보일러플레이트 코드가 존재
• URLSearchParams를 수동으로 파싱
• 여러 필터가 늘어날수록 확장 어려움
• 버그가 쉽게 생김
• 내장 타입 안전성 부재

애플리케이션이 성장함에 따라(예: 검색 페이지나 대시보드) 이 로직은 빠르게 유지보수가 어려워집니다.

nuqs란 무엇인가?

nuqs는 URL 쿼리 파라미터를 React 상태로 다루는 가벼운 라이브러리입니다.
상태와 URL을 수동으로 동기화하는 대신, 훅을 간단히 사용하면 됩니다.

URL Query    React State

이렇게 하면 쿼리 파라미터 관리가 크게 단순화됩니다.

nuqs 설치

npm install nuqs
# or
yarn add nuqs
# or
pnpm add nuqs

그게 전부입니다.

nuqs를 사용한 동일한 예시

'use client'

import { useQueryState } from 'nuqs'

export default function ProductFilter() {
  const [category, setCategory] = useQueryState('category')

  return (
     setCategory(e.target.value)}
    >
      All
      Books
      Games
    
  )
}

상태가 변경될 때 URL이 자동으로 업데이트됩니다.

결과 URL

/products?category=books

수동 구현과 비교:

• 라우터 로직 없음
• useEffect 없음
• 수동 쿼리 파싱 없음

타입‑안전 쿼리 파라미터

nuqs의 가장 강력한 기능 중 하나는 파서 시스템입니다.

예시: 페이지네이션

import { useQueryState, parseAsInteger } from 'nuqs'

const [page, setPage] = useQueryState(
  'page',
  parseAsInteger.withDefault(1)
)

장점

• page는 항상 숫자입니다
• 기본값은 1입니다
• 잘못된 쿼리 값이 안전하게 처리됩니다

이는 많은 런타임 버그를 방지합니다.

여러 쿼리 파라미터 관리

복잡한 UI는 보통 여러 필터를 가집니다. nuqs는 useQueryStates를 사용해 이를 깔끔하게 처리합니다.

import { useQueryStates, parseAsString } from 'nuqs'

const [filters, setFilters] = useQueryStates({
  category: parseAsString,
  sort: parseAsString,
})

필터 업데이트

setFilters({
  category: 'books',
  sort: 'price',
})

결과 URL

?category=books&sort=price

이렇게 하면 필터 로직을 예측 가능하고 유지 보수가 쉽게 할 수 있습니다.

왜 nuqs를 선택했는가

URL 상태 관리를 위한 라이브러리를 선택할 때 여러 요소를 고려했습니다.

1. 개발자 경험

nuqs는 상태와 URL을 수동으로 동기화할 필요를 없애줍니다.
useEffect, URLSearchParams, 라우터 업데이트를 일일이 다루는 대신, 쿼리 파라미터가 일반 React 상태처럼 동작합니다. 이로 인해 보일러플레이트가 크게 줄어들고 가독성이 향상됩니다.

2. 타입 안전성

파서 시스템을 통해 쿼리 파라미터에 타입을 지정할 수 있어, 예측 가능한 값들을 보장하고 TypeScript 프로젝트에서 런타임 오류를 감소시킵니다.

3. 제로 의존성 & 경량

nuqs는 런타임 의존성이 전혀 없으며, 이는 여러 장점을 제공합니다:

• 번들 크기 감소
• 잠재적인 보안 취약점 감소
• 의존성 충돌 위험 감소
• 장기 유지보수 용이

현대 프론트엔드 프로젝트에서는 의존성 트리가 빠르게 커질 수 있습니다. 최소한의 의존성을 가진 집중된 라이브러리를 사용하면 애플리케이션을 가볍게 유지할 수 있으며, nuqs는 이 철학을 잘 따릅니다.

4. 최신 Next.js에 맞게 설계

nuqs는 Next.js App Router와 React 훅에 자연스럽게 통합됩니다. 추가적인 복잡성을 도입하지 않고 현대 React 아키텍처에 매끄럽게 녹아듭니다.

내 프로젝트에서의 실제 영향

nuqs를 도입한 후, 나는 다음과 같은 변화를 관찰했습니다:

• URL 처리와 관련된 컴포넌트 보일러플레이트가 ~30% 감소
• 형식이 잘못된 쿼리 문자열로 인한 버그 감소 (타입‑안전 파서 덕분)
• API가 직관적이고 자체 문서화되어 있어 신규 팀원의 온보딩이 빨라짐
• 관심사의 명확한 분리: UI 컴포넌트가 라우팅 세부 정보를 알 필요가 없어짐

전체적으로, nuqs는 내 코드베이스에서 고통스럽고 오류가 발생하기 쉬운 부분을 선언적이고 타입‑안전한 경험으로 바꾸었습니다.

TL;DR

만약 UI 상태를 위해 쿼리 파라미터에 의존하는 Next.js 앱을 구축하고 있다면, nuqs를 한 번 사용해 보세요. URL 관리를 간단한 훅 기반 워크플로우로 바꾸고, 타입 안전성을 추가하며, 번들을 가볍게 유지합니다. 즐거운 코딩 되세요!

nuqs를 도입했을 때, 여러 개선점이 명확해졌습니다

보일러플레이트 감소

쿼리 상태 로직이 크게 작아지고 이해하기 쉬워졌습니다.

유지보수성 향상

새 필터를 추가하는 데 이제 몇 줄만 필요합니다.

버그 감소

타입‑안전 파싱으로 잘못된 쿼리 상태를 방지합니다.

사용자 경험 향상

UI 상태가 URL에 존재하기 때문에:

• 필터를 공유할 수 있습니다
• 페이지를 즐겨찾기 할 수 있습니다
• 브라우저 탐색이 자연스럽게 동작합니다

nuqs가 특히 유용한 경우

제 경험에 따르면, nuqs는 다음과 같은 경우에 특히 잘 작동합니다:

• search / filter pages
• e‑commerce listings
• dashboards
• analytics tools
• pagination systems
• sorting UIs

다시 말해:

✨ UI 상태가 URL에 반영되어야 하는 모든 인터페이스.

최종 생각

Next.js에서 URL 상태를 수동으로 관리하면 반복적이고 깨지기 쉬운 코드가 생기기 쉽습니다.
nuqs는 쿼리 매개변수를 React 상태처럼 다루는 깔끔한 추상화를 제공하면서 모든 것이 타입‑안전하고 가볍게 유지됩니다.

현대적인 React 및 Next.js 애플리케이션에 대해, 두 가지 모두 크게 개선할 수 있습니다:

• 개발자 경험
• 코드 유지보수성

필터가 많이 필요한 인터페이스나 대시보드를 구축하고 있다면, nuqs를 사용해 보시길 강력히 추천합니다!