Nuqs 라이브러리로 Next.js에서 URL 쿼리 파라미터를 효율적으로 관리하기
Nuqs는 Next.js 애플리케이션에서 URL 쿼리 파라미터를 더 쉽고 타입 세이프하게 관리할 수 있도록 도와주는 라이브러리입니다. 이 라이브러리는 URL 기반 상태 관리를 간소화하고, 타입스크립트를 통해 안정성과 생산성을 높일 수 있는 강력한 도구입니다.
Nuqs의 주요 장점
- 쿼리 파라미터가 많은 페이지에서 유용
- 필터링이나 정렬 기능이 있는 목록 페이지
- 복잡한 검색 기능이 필요한 페이지
- 여러 상태값을 URL에 저장해야 하는 경우
- 주요 기능
- 타입스크립트 지원으로 타입 안정성 제공
- URL 쿼리 파라미터를 React 상태처럼 사용 가능
- URL 업데이트 자동 처리
- 쿼리 파라미터의 파싱 및 직렬화 자동화
Nuqs 사용법
1. App Router에서 사용하기
layout.tsx에서 NuqsAdapter를 추가하여 사용합니다.
//layout.tsx
import { NuqsAdapter } from 'nuqs/adapters/next/app'
import { type ReactNode } from 'react'
export default function RootLayout({
children
}: {
children: ReactNode
}) {
return (
<html>
<body>
<NuqsAdapter>{children}</NuqsAdapter>
</body>
</html>
)
}2. Page Router에서 사용하기
page.tsx에서 NuqsAdapter를 적용합니다.
//page.tsx
import type { AppProps } from 'next/app'
import { NuqsAdapter } from 'nuqs/adapters/next/pages'
export default function MyApp({ Component, pageProps }: AppProps) {
return (
<NuqsAdapter>
<Component {...pageProps} />
</NuqsAdapter>
)
}
3. App & Page Router 통합
App Router와 Page Router를 모두 사용하는 경우, 통합 어댑터를 사용할 수 있습니다. 하지만 이 경우 번들 크기가 약간 증가할 수 있습니다.
import { NuqsAdapter } from 'nuqs/adapters/next'useQueryState를 활용한 동기화
String 파라미터 관리
'use client'
import { useQueryState } from 'nuqs'
export function Demo() {
const [name, setName] = useQueryState('name')
return (
<>
<input value={name || ''} onChange={e => setName(e.target.value)} />
<button onClick={() => setName(null)}>Clear</button>
<p>Hello, {name || 'anonymous visitor'}!</p>
</>
)
}
Number 파라미터 관리
parseAsInteger를 활용해 쿼리 파라미터를 정수로 변환합니다.
'use client'
import {parseAsInteger, useQueryState} from "nuqs";
export default function Home() {
const [count, setCount] = useQueryState('count', parseAsInteger)
return (
<>
<pre>count: {count}</pre>
<button onClick={() => setCount(0)}>Reset</button>
<button onClick={() => setCount(c => (c ?? 0) + 1)}>+</button>
<button onClick={() => setCount(c => (c ?? 0) - 1)}>-</button>
<button onClick={() => setCount(null)}>Clear</button>
</>
);
}
Parser 함수 종류
- parseAsFloat: 부동 소수점으로 파싱
- parseAsBoolean: 불리언으로 파싱
- parseAsJson: JSON 객체로 파싱
- parseAsArrayOf: 배열로 파싱
초기값 설정
const [value, setValue] = useQueryState('key', {
defaultValue: '초기값', // 쿼리 파라미터가 없을 때의 기본값
parse: parseAsInteger, // 파서 지정
})
Nuqs의 성능 최적화
- Nuqs는 URL 변경 시에만 컴포넌트가 업데이트되도록 내부적으로 최적화되어 있습니다. 이를 통해 불필요한 리렌더링을 방지하고 성능을 극대화할 수 있습니다.
사용하면서 느낀 점
Nuqs를 사용하면서 URL 쿼리 파라미터를 관리하는 작업이 훨씬 간편해졌습니다. 특히 타입스크립트 지원과 자동화된 파라미터 처리 기능 덕분에 코드의 가독성과 안정성이 크게 향상되었습니다. 다만, 페이지 이동 시 Next.js의 클라이언트 사이드 네비게이션을 활용하면 쿼리 파라미터가 유지되지만, 완전한 페이지 리로드 시에는 초기화되는 한계가 있었습니다. 이를 보완하기 위해 필요한 경우 localStorage나 sessionStorage와 같은 추가적인 상태 관리 도구를 함께 사용하는 것이 유용하다고 느꼈습니다.
nuqs | Type-safe search params state management for React
Type-safe search params state management for React. Like useState, but stored in the URL query string.
nuqs.47ng.com
'TIL' 카테고리의 다른 글
| [Tailwind CSS] gap vs space 유틸리티의 차이점 이해하기 (0) | 2025.02.01 |
|---|---|
| [데이터베이스] One-to-Many와 Many-to-Many 관계 (0) | 2025.01.17 |
| [회고] 다사다난 했던 2024년도 회고 (1) | 2024.12.23 |
| 가챠권 소모 로직과 공정한 랜덤 확률 시스템 구현: 사용자 재방문율 20% 향상 (0) | 2024.12.17 |
| [테오스프린트] 테오스프린트 18기를 시작하며 (0) | 2024.12.04 |
