NUQS

nuqs는 React 애플리케이션에서 URL 쿼리 문자열을 상태 관리에 활용할 수 있도록 도와주는 타입 안전한 쿼리 상태 관리 라이브러리입니다. useState와 유사한 API를 제공하면서, 상태를 URL에 동기화할 수 있어 공유, 북마크, 브라우저 히스토리 활용 등이 쉬워집니다.

✨ 주요 기능

• URL 기반 상태 관리

  • 상태를 URL 쿼리 문자열로 유지함으로써 URL이 상태의 단일 진실 소스(Single Source of Truth)가 됩니다.

• 타입 안전성(Type Safety)

  • 다양한 기본 파서(int, float, boolean 등) 및 커스텀 파서를 제공하여, 타입 안정성이 보장됩니다.

• React의 다양한 라우터 지원

  • Next.js 14.2+, React SPA (18.3 / 19), Remix v2+, React Router v6/v7 등을 지원합니다.

• 히스토리 모드

  • 상태 변경 시 replace 또는 push 방식 선택 가능 (useHistoryMode).

• 서버 컴포넌트 지원 (Next.js)

  • searchParams를 타입 안전하게 다루는 서버 캐시 제공.

• 트랜지션 연동

  • useTransition과 함께 사용하여 서버 업데이트의 로딩 상태를 관리할 수 있습니다.

🧩 설치

pnpm add nuqs
# 또는
npm install nuqs
yarn add nuqs
bun add nuqs

Example

'use client';

import { useQueryState } from 'nuqs';

export default function ExampleComponent() {
  const [name, setName] = useQueryState('name');

  return (
    <>
      <h1>Hello, {name || 'anonymous visitor'}!</h1>
      <input value={name || ''} onChange={e => setName(e.target.value)} />
      <button onClick={() => setName(null)}>Clear</button>
    </>
  );
}