25:I[536515,["/_next/static/immutable/chunks/1l88qfqr214lg.js","/_next/static/immutable/chunks/140lucvgzny1t.js","/_next/static/immutable/chunks/0h72irdf5jbkp.js","/_next/static/immutable/chunks/0uomrwa0d9fep.js","/_next/static/immutable/chunks/1_6tb_46uudug.js","/_next/static/immutable/chunks/1hk1clakksktf.js","/_next/static/immutable/chunks/0tos9h9-naode.js","/_next/static/immutable/chunks/304dqzeb6b0bn.js","/_next/static/immutable/chunks/1g-elbz1od49w.js","/_next/static/immutable/chunks/0u4n3l2vaan_d.js","/_next/static/immutable/chunks/3egm3pk02913o.js","/_next/static/immutable/chunks/2fwgykkvpr8o7.js","/_next/static/immutable/chunks/0zdgidr3ia25h.js","/_next/static/immutable/chunks/3jzx7fql_a9f-.js","/_next/static/immutable/chunks/3zcg661ahxixb.js"],"PostViewTracker"] 26:I[207142,["/_next/static/immutable/chunks/1l88qfqr214lg.js","/_next/static/immutable/chunks/140lucvgzny1t.js","/_next/static/immutable/chunks/0h72irdf5jbkp.js","/_next/static/immutable/chunks/0uomrwa0d9fep.js","/_next/static/immutable/chunks/1_6tb_46uudug.js","/_next/static/immutable/chunks/1hk1clakksktf.js","/_next/static/immutable/chunks/0tos9h9-naode.js","/_next/static/immutable/chunks/304dqzeb6b0bn.js","/_next/static/immutable/chunks/1g-elbz1od49w.js","/_next/static/immutable/chunks/0u4n3l2vaan_d.js","/_next/static/immutable/chunks/3egm3pk02913o.js","/_next/static/immutable/chunks/2fwgykkvpr8o7.js","/_next/static/immutable/chunks/0zdgidr3ia25h.js","/_next/static/immutable/chunks/3jzx7fql_a9f-.js","/_next/static/immutable/chunks/3zcg661ahxixb.js"],"PostBackButton"] 27:I[390236,["/_next/static/immutable/chunks/1l88qfqr214lg.js","/_next/static/immutable/chunks/140lucvgzny1t.js","/_next/static/immutable/chunks/0h72irdf5jbkp.js","/_next/static/immutable/chunks/0uomrwa0d9fep.js","/_next/static/immutable/chunks/1_6tb_46uudug.js","/_next/static/immutable/chunks/1hk1clakksktf.js","/_next/static/immutable/chunks/0tos9h9-naode.js","/_next/static/immutable/chunks/304dqzeb6b0bn.js","/_next/static/immutable/chunks/1g-elbz1od49w.js","/_next/static/immutable/chunks/0u4n3l2vaan_d.js","/_next/static/immutable/chunks/3egm3pk02913o.js","/_next/static/immutable/chunks/2fwgykkvpr8o7.js","/_next/static/immutable/chunks/0zdgidr3ia25h.js","/_next/static/immutable/chunks/3jzx7fql_a9f-.js","/_next/static/immutable/chunks/3zcg661ahxixb.js"],"PostSummary"] 2b:I[948688,["/_next/static/immutable/chunks/1opgw09b2rf0r.js"],"IconMark"] 28:T19f5,

nuqs를 사용한 검색 기능
nuqs 검색 기능 구현 과정 정리
1. 어떤 문제점이 있었는지
초기 문제상황
- 실시간 API 호출 문제: 사용자가 검색어를 타이핑할 때마다 API가 즉시 호출됨
- 성능 이슈: 불필요한 네트워크 요청이 과도하게 발생
- 사용자 경험 저하: 타이핑 중에 계속해서 로딩이 발생하고 서버 부하 증가
- 비효율적인 리소스 사용: 완성되지 않은 검색어로도 API 요청이 발생
근본 원인
- useQueryState를 직접 API 호출에 연결했을 때, 상태 변경 시마다 즉시 API가 실행되는 구조
2. nuqs를 사용하려고 한 이유
URL 상태 관리의 필요성
- 검색 상태의 지속성: 페이지 새로고침 후에도 검색어가 유지되어야 함
- 공유 가능한 URL: 특정 검색 결과를 URL로 공유할 수 있어야 함
- 브라우저 히스토리: 뒤로가기/앞으로가기 버튼으로 검색 히스토리 탐색 가능
- SEO 및 북마크: 검색 상태가 URL에 반영되어 검색엔진 최적화와 북마크 기능 지원
nuqs 선택 이유
- Next.js와의 완벽한 호환성
- 타입 안전성 제공
- 간단한 API로 URL 상태 관리 가능
3. nuqs를 사용하면서 문제를 어떻게 해결하려고 했는지
첫 번째 시도: useState + useEffect 조합
```
const [search, setSearch] = useQueryState('search');
const [debouncedSearch, setDebouncedSearch] = useState(search ?? '');

useEffect(() => {
  const timer = setTimeout(() => {
    setDebouncedSearch(search ?? '');
  }, 500);
  return () => clearTimeout(timer);
}, [search]);
```
- 별도의 debounced 상태를 만들어 API 호출 지연
두 번째 시도: nuqs 내장 옵션 활용
```
const [search, setSearch] = useQueryState('search', {
  limitUrlUpdates: {
    method: 'debounce', // 또는 'throttle'
    timeMs: 500,
  },
});
```
- nuqs의 내장 debounce 기능 활용 시도
문제점 발견
- limitUrlUpdates는 URL 업데이트만 debounce하지만, useQueryState의 반환값 자체는 즉시 변경됨
- 따라서 여전히 API가 즉시 호출되는 문제 지속
4. 실제로 문제를 어떻게 해결했는지
최종 해결책: 역할 분리 + useSearchParams 활용
BlogHeader (검색 입력 처리)
```
const [search, setSearch] = useQueryState('search', {
  limitUrlUpdates: {
    method: 'debounce',
    timeMs: 500,
  },
});
```
- 타이핑 시 즉시 UI 반응
- 500ms 후 URL 업데이트
BlogMainPage (API 호출)
```
const searchParams = useSearchParams();
const search = searchParams.get('search');

const { posts, isLoading } = usePost({
  search: search ?? '',
  page: 1,
  limit: 10,
});
```
- useSearchParams로 URL에서 직접 파라미터 읽기
- URL이 실제로 변경될 때만 컴포넌트 리렌더링 및 API 호출
해결책의 핵심 원리
1. 입력과 API 호출 분리: 입력 처리와 API 호출을 서로 다른 컴포넌트에서 담당
2. URL 기반 상태 관리: URL이 단일 진실 공급원(Single Source of Truth) 역할
3. debounce된 URL 업데이트: 사용자 입력은 즉시 반영되지만 URL은 debounce로 업데이트
4. React 렌더링 최적화: useSearchParams는 URL 변경 시에만 리렌더링 트리거
최종 결과
- 사용자 타이핑 시 즉시 UI 반응 (UX 향상)
- API 호출은 500ms debounce로 최적화 (성능 향상)
- URL 상태 관리로 검색 결과 공유 및 북마크 가능
- 브라우저 히스토리 완전 지원

1d:[["$","script",null,{"type":"application/ld+json","dangerouslySetInnerHTML":{"__html":"{\"@context\":\"https://schema.org\",\"@type\":\"BlogPosting\",\"headline\":\"nuqs 사용기\",\"description\":\"nuqs를 사용한 검색 기능nuqs 검색 기능 구현 과정 정리1. 어떤 문제점이 있었는지초기 문제상황실시간 API 호출 문제: 사용자가 검색어를 타이핑할 때마다 API가 즉시 호출됨성능 이슈: 불필요한 네트워크 요청이 과도하게 발생사용자 경험 저하: 타이핑 중에 계속해서 로딩이...\",\"image\":[\"https://3d-blog.vercel.app/blog/category/nextjs/post/nuqs-%EC%82%AC%EC%9A%A9%EA%B8%B0/opengraph-image\"],\"author\":{\"@type\":\"Person\",\"name\":\"성창수\"},\"publisher\":{\"@type\":\"Organization\",\"name\":\"3D Blog\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://3d-blog.vercel.app/opengraph-image\"}},\"datePublished\":\"2025-10-21T13:27:30.992Z\",\"dateModified\":\"2026-08-17T08:22:58.381Z\",\"mainEntityOfPage\":{\"@type\":\"WebPage\",\"@id\":\"https://3d-blog.vercel.app/blog/category/nextjs/post/nuqs-%EC%82%AC%EC%9A%A9%EA%B8%B0\"},\"url\":\"https://3d-blog.vercel.app/blog/category/nextjs/post/nuqs-%EC%82%AC%EC%9A%A9%EA%B8%B0\"}"}}],["$","$1f",null,{"fallback":null,"children":["$","$L25",null,{"postId":15,"slug":"nuqs-사용기","categorySlug":"nextjs"}]}],["$","div",null,{"className":"mx-4 max-w-4xl lg:mx-auto","children":[["$","$L26",null,{"href":"/blog/category/nextjs"}],["$","section",null,{"className":"relative mb-12 mt-0 px-4 py-8 sm:px-6 md:rounded-2xl md:px-8 md:overflow-hidden md:border md:border-[#ff9a3c]/20 md:bg-gradient-to-br md:from-[#2a1545]/90 md:via-[#1c0e38]/85 md:to-[#12082a]/80 md:shadow-[0_0_32px_rgba(255,154,60,0.1)] dark:md:border-[#3de8ff]/[0.15] dark:md:from-[#0a0618]/90 dark:md:via-[#070414]/90 dark:md:to-[#000008]/85 dark:md:shadow-[0_0_32px_rgba(61,232,255,0.08)]","children":[["$","div",null,{"className":"pointer-events-none absolute inset-0 z-0 hidden md:block","children":["$","div",null,{"className":"h-full w-full bg-gradient-to-tr from-[#8a4a68]/15 via-[#1c0e38]/20 to-[#ffc090]/10 blur-[2px] dark:from-cyan-900/20 dark:via-fuchsia-900/10 dark:to-cyan-800/10"}]}],["$","h1",null,{"className":"relative z-10 mb-4 text-3xl font-extrabold md:drop-shadow-sm dark:md:drop-shadow-[0_2px_8px_#7dd3fc55] text-[#ffe8d0] dark:text-[#c8e8ff]","children":"nuqs 사용기"}],["$","div",null,{"className":"relative z-10 mb-6 flex items-center gap-3 text-xs text-[#d4a8c0]/85 dark:text-[#7ec8ff]/75","children":[["$","span",null,{"className":"font-mono","children":"성창수"}],["$","span",null,{"className":"opacity-60","children":"|"}],["$","span",null,{"children":"2025-10-21"}],[["$","span",null,{"className":"opacity-60","children":"|"}],["$","span",null,{"className":"text-[#ffb870] dark:text-[#3de8ff]","children":"next.js"}]]]}],false,["$","div",null,{"className":"relative z-10 mb-2 min-h-[88px] p-2","children":["$","$1f",null,{"fallback":["$","div",null,{"className":"mb-6 min-h-[88px]","aria-hidden":true}],"children":[["$","$L4",null,{"moduleIds":["3623811150574836874"]}],["$","$L27",null,{"post":{"id":15,"title":"nuqs 사용기","content":"$28","updatedAt":"$D2026-08-17T08:22:58.381Z"}}]]}]}],"$L29"]}],"$L2a"]}]] 20:null 24:[["$","title","0",{"children":"nuqs 사용기"}],["$","meta","1",{"name":"description","content":"nuqs를 사용한 검색 기능nuqs 검색 기능 구현 과정 정리1. 어떤 문제점이 있었는지초기 문제상황실시간 API 호출 문제: 사용자가 검색어를 타이핑할 때마다 API가 즉시 호출됨성능 이슈: 불필요한 네트워크 요청이 과도하게 발생사용자 경험 저하: 타이핑 중에 계속해서 로딩이..."}],["$","meta","2",{"name":"author","content":"성창수"}],["$","meta","3",{"name":"creator","content":"3D Blog"}],["$","meta","4",{"name":"publisher","content":"3D Blog"}],["$","meta","5",{"name":"robots","content":"index, follow"}],["$","meta","6",{"name":"googlebot","content":"index, follow, max-video-preview:-1, max-image-preview:large, max-snippet:-1"}],["$","link","7",{"rel":"canonical","href":"https://3d-blog.vercel.app/blog/category/nextjs/post/nuqs-%EC%82%AC%EC%9A%A9%EA%B8%B0"}],["$","meta","8",{"name":"google-site-verification","content":"txYmXq1GLSvBcoTz6-zWwFTe4Wl0bmJ1DYYi97AnAB0"}],["$","meta","9",{"property":"og:title","content":"nuqs 사용기"}],["$","meta","10",{"property":"og:description","content":"nuqs를 사용한 검색 기능nuqs 검색 기능 구현 과정 정리1. 어떤 문제점이 있었는지초기 문제상황실시간 API 호출 문제: 사용자가 검색어를 타이핑할 때마다 API가 즉시 호출됨성능 이슈: 불필요한 네트워크 요청이 과도하게 발생사용자 경험 저하: 타이핑 중에 계속해서 로딩이..."}],["$","meta","11",{"property":"og:url","content":"https://3d-blog.vercel.app/blog/category/nextjs/post/nuqs-%EC%82%AC%EC%9A%A9%EA%B8%B0"}],["$","meta","12",{"property":"og:site_name","content":"3D Blog"}],["$","meta","13",{"property":"og:locale","content":"ko_KR"}],["$","meta","14",{"property":"og:image","content":"https://3d-blog.vercel.app/blog/category/nextjs/post/nuqs-%EC%82%AC%EC%9A%A9%EA%B8%B0/opengraph-image-10g31z?ff75c0294565acbf"}],["$","meta","15",{"property":"og:image:type","content":"image/png"}],["$","meta","16",{"property":"og:image:width","content":"1200"}],["$","meta","17",{"property":"og:image:height","content":"630"}],["$","meta","18",{"property":"og:image:alt","content":"3D Blog Post"}],["$","meta","19",{"property":"og:type","content":"article"}],["$","meta","20",{"property":"article:published_time","content":"2025-10-21T13:27:30.992Z"}],["$","meta","21",{"property":"article:modified_time","content":"2026-08-17T08:22:58.381Z"}],["$","meta","22",{"property":"article:author","content":"성창수"}],["$","meta","23",{"name":"twitter:card","content":"summary_large_image"}],["$","meta","24",{"name":"twitter:creator","content":"성창수"}],["$","meta","25",{"name":"twitter:title","content":"nuqs 사용기"}],["$","meta","26",{"name":"twitter:description","content":"nuqs를 사용한 검색 기능nuqs 검색 기능 구현 과정 정리1. 어떤 문제점이 있었는지초기 문제상황실시간 API 호출 문제: 사용자가 검색어를 타이핑할 때마다 API가 즉시 호출됨성능 이슈: 불필요한 네트워크 요청이 과도하게 발생사용자 경험 저하: 타이핑 중에 계속해서 로딩이..."}],["$","meta","27",{"name":"twitter:image","content":"https://3d-blog.vercel.app/blog/category/nextjs/post/nuqs-%EC%82%AC%EC%9A%A9%EA%B8%B0/opengraph-image-10g31z?ff75c0294565acbf"}],["$","meta","28",{"name":"twitter:image:alt","content":"3D Blog Post"}],["$","meta","29",{"name":"twitter:image:type","content":"image/png"}],["$","meta","30",{"name":"twitter:image:width","content":"1200"}],["$","meta","31",{"name":"twitter:image:height","content":"630"}],["$","link","32",{"rel":"icon","href":"/favicon.ico?favicon.43c1ha936bzt6.ico","sizes":"256x256","type":"image/x-icon"}],["$","$L2b","33",{}]]

nuqs 검색 기능 구현 과정 정리

1. 어떤 문제점이 있었는지

초기 문제상황

근본 원인

2. nuqs를 사용하려고 한 이유

URL 상태 관리의 필요성

nuqs 선택 이유

3. nuqs를 사용하면서 문제를 어떻게 해결하려고 했는지

첫 번째 시도: useState + useEffect 조합

두 번째 시도: nuqs 내장 옵션 활용

문제점 발견

4. 실제로 문제를 어떻게 해결했는지

최종 해결책: 역할 분리 + useSearchParams 활용

BlogHeader (검색 입력 처리)

BlogMainPage (API 호출)

해결책의 핵심 원리

최종 결과

nuqs 사용기

댓글