React

nuqsとは?useQueryStateの使い方と2.10までの新機能・debounceの使いどころ

nuqsとは?useQueryStateの使い方と2.10までの新機能・debounceの使いどころ

nuqs(作者は「nucks」と、ducksと韻を踏む読み方をしています)は、URLのクエリ文字列をReactのuseStateと同じ書き方で読み書きできるライブラリです。?page=3&sort=newのような値を型付きのstateとして扱え、再読み込みやURLの共有でも画面の状態が残ります。2026年10月31日時点の最新版は2.10.2(2026-10-08公開)です。この記事では、導入手順、既定値の意味、debounceが効く条件、テストの書き方、2.5〜2.10の変更点を説明します。挙動はNode.js 26.5.0・React 19.3.0・nuqs 2.10.2で、jsdom上のtestingアダプター(nuqs/adapters/testing)を使って実測し、掲載コードはTypeScript 7.0.2のstrictで型検査、テストコードはVitest 5.0.5で実行しました。実ブラウザやNext.jsアプリ上での動作は公式ドキュメントの記述に拠っています。

まとめ:nuqs 2.10の要点と使いどころ

  • 最新版は2.10.2。公式アダプターはNext.js(14.2以上・App Router/Pages Router)、React SPA、Remix、React Router v6〜v8、TanStack Router(実験的)で、Vue・Svelte向けの公式版はありません。RemixとReact Router v6のアダプターは3.0で削除予定です。
  • 使い始めはルートをNuqsAdapterで包み、useQueryState('page', parseAsInteger.withDefault(1))のようにキーとパーサーを渡すだけです。
  • 既定は履歴を置き換え(history: 'replace')、サーバーへ通知しない(shallow: true)、スクロールしない、既定値と同じ値ならURLから消す(clearOnDefault: true)の4つです。モーダルやタブで戻るボタンを効かせたいキーだけhistory: 'push'にします。
  • URL更新は既定で50ms間隔に間引かれます。debounceはshallow: falseでサーバーに取りに行く場合の機能で、クライアント側で取得するなら値の側をdebounceします。
  • サーバー側はcreateLoaderで読み、createSerializerでリンクを組み立てます。テストはwithNuqsTestingAdapterで初期URLを渡し、onUrlUpdateで書き込まれたクエリを検証します。
  • TanStack Routerを主に使うアプリでは、ルーター自身の型付きsearch paramsを優先するよう公式が勧めています。

nuqsの役割:useStateの書き方でURLクエリに状態を置く仕組み

Next.jsのApp Routerで検索条件をURLに同期させる場合、useSearchParamsは読み取り専用なので、書き込みはrouter.replace()か、Next.jsがuseSearchParamsと同期すると明記しているwindow.history.replaceState/pushStateで、URL文字列を組み直して行います。どちらの方法でも、数値や配列と文字列の相互変換は自前です。nuqsはこの「読む・変換する・書き戻す」を1つのフックにまとめます。

作者はフランス在住のFrançois Best氏(GitHubの47ng/franky47)で、リポジトリは2020年5月作成、ライセンスはMITです。npmのnuqsパッケージの週間ダウンロード数は7,936,222件(2026年10月23日〜29日)、GitHubスターは10,899件でした。前身のパッケージ名はnext-usequerystateで、Next.js専用から始まり、2.0でアダプター方式に変わって他のフレームワークにも広がりました。2024年以前の日本語記事には「Next.js専用」と書かれたものがありますが、2.x系では当てはまりません。

URLに置くのに向くのは、検索語・絞り込み・並び順・ページ番号・タブ・モーダルの開閉など「その画面をURLだけで再現したい」状態です。入力途中のフォーム全体や認証情報のような、共有されると困る値・長い値は置きません(判断の詳細は後半の「nuqsを選ばない方がよい場面」で扱います)。

nuqsの導入手順:インストールとアダプターの設定

インストールはnpm install nuqs(pnpm・yarn・bun・Denoも可)です。2.x系はフレームワークごとのNuqsAdapterでアプリを包む方式で、アダプターが無いままuseQueryStateを呼ぶとnuqs requires an adapter to work with your framework.というエラーで止まります。このエラーが出たら、NuqsAdapterがフックを使うコンポーネントより上の階層にあるか、使っているフレームワークに合ったimport元かを確認します。

フレームワーク import元 対応バージョン
Next.js App Router nuqs/adapters/next/app next 14.2.0以上
Next.js Pages Router nuqs/adapters/next/pages next 14.2.0以上
React SPA(Viteなど) nuqs/adapters/react react 18.3/19
Remix(3.0で削除予定) nuqs/adapters/remix @remix-run/react 2
React Router v6/v7/v8 nuqs/adapters/react-router/v6など 各メジャー版
TanStack Router nuqs/adapters/tanstack-router @tanstack/react-router 1(実験的)
テスト(Vitest等) nuqs/adapters/testing –

対応バージョンは公式のInstallationページの表記で、Next.js 14.2未満は旧系列のnuqs@^1を使います。v8向けは2.9.0で追加されました。公式のAdaptersページは、React Router v6向けと、v6を指す汎用のnuqs/adapters/react-router、Remix向けを、上流がサポートを終えたとして3.0で削除すると予告しているため、新規ならv7かv8のアダプターを選びます。2.8.0の「React Router v5対応」はpeerDependenciesの範囲を広げてインストールで失敗しないようにした変更で、v5用アダプター自体は本体に含まれず、shadcnのレジストリから入れる簡易版です(PR #1214の説明によると、浅い更新への追従やキー分離は備えていません)。上の表に無いルーター向けにはnuqs/adapters/customで独自アダプターを作れます。

Next.js App Routerでの設定とSuspenseの扱い

ルートのlayout.tsxでchildrenを包みます。App RouterのNuqsAdapterはServer Componentのlayoutからそのまま使えます(App Routerのファイル規約はApp Routerとは?Next.jsのファイル規約・動的ルーティング・Pages Routerとの違いで解説しています)。

// app/layout.tsx
import { NuqsAdapter } from 'nuqs/adapters/next/app'
import { type ReactNode } from 'react'

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="ja">
      <body>
        <NuqsAdapter>{children}</NuqsAdapter>
      </body>
    </html>
  )
}

ビルド時にMissing Suspense boundary with useSearchParamsが出たら、useQueryStateを使うクライアントコンポーネントをページ側で<Suspense>に入れます。nuqsは内部でNext.jsのuseSearchParamsを読むため、静的レンダリングされるページではこの境界が必要です。

React SPA・React Router・TanStack Routerでの違い

React SPAではmain.tsxで<App />を包みます。サーバーが無い構成なのでshallow: falseは効きません。2.4.0からはサーバー側で描画し直したい場合に、アダプターへfullPageNavigationOnShallowFalseUpdatesを渡すと全ページ遷移に切り替えられます。2.10.0では同じReactアダプターにserverSearchが加わり、AstroやHono、Fastifyのようにlocationが無いサーバー描画でも、リクエストのクエリ文字列を初期値として渡せるようになりました。

React Router系とRemixは既定でshallow: trueなので、loaderを再実行させたいキーにだけshallow: falseを付けます。TanStack Routerのアダプターは公式が実験的と明記しており、TanStack Startはまだ対象外です(TanStack Routerの型安全ルーティングを主に使う場合の考え方は後半で触れます)。

useQueryStateとuseQueryStatesの使い方

基本形はconst [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1))です。第1引数がURLのキー、第2引数がパーサーで、戻り値はuseStateと同じく値と更新関数の組です。パーサーを省くと値はstring | nullになり、setPage(null)でキーがURLから消えます。

パーサーの解析失敗時の挙動と既定値

組み込みパーサーはparseAsString・parseAsInteger・parseAsFloat・parseAsBoolean・parseAsIsoDate・parseAsTimestamp・parseAsStringLiteral・parseAsJson・parseAsArrayOfなど15種類です(2.10.2のnuqsのexportのうちparseAsで始まるものを数えた値で、独自パーサーを作るcreateParserなどは含みません)。testingアダプターで動かした結果は次のとおりでした。ここでの「解析失敗」は文字列を型に変換できない場合のことで、値が業務上妥当かどうかの検証は別に行う必要があります。

  • ?page=abcをparseAsInteger.withDefault(1)で読むと1が返る(例外にならず既定値に落ちる)。
  • setPage(3)でURLは?page=3、setPage(1)で既定値と一致するためキーごと消えて空文字になる。
  • setPage(1, { clearOnDefault: false })なら?page=1が残る。

既定値の変更でURLの意味が変わるのを避けたいページ(共有リンクを長く残す一覧など)では、clearOnDefault: falseを付けて値を明示的に残す方が安全です。

複数キーをまとめるuseQueryStatesとurlKeys

ページ番号と並び順のように一緒に変わるキーはuseQueryStatesでまとめます。1回の呼び出しで複数キーを更新しても、URL更新は1回にまとまります。urlKeysを使うとコード上の名前とURL上の短いキーを分けられます。

'use client'
import { useQueryStates, parseAsInteger, parseAsStringLiteral } from 'nuqs'

const sortOrders = ['new', 'old'] as const

export function useListParams() {
  return useQueryStates(
    {
      page: parseAsInteger.withDefault(1),
      sort: parseAsStringLiteral(sortOrders).withDefault('new'),
    },
    { urlKeys: { page: 'p' } }
  )
}

このフックで?p=5&sort=badを読むと{ page: 5, sort: 'new' }になり、リストに無いbadは既定値に置き換わりました。setParams({ page: 9, sort: 'old' })で?p=9&sort=old、setParams(null)ではこのフックが管理するpとsortだけが消え、管理外のキー(例:other=x)はURLに残りました。sortの型はtsc 7.0.2で'new' | 'old'と推論されました。2.5.0でリテラル系パーサーの引数にconst修飾子が付いたため、parseAsStringLiteral(['new', 'old'])のように配列を直接渡しても同じリテラル型になります。

注意点として、同じキーに別のパーサーを使うフックが2つあると、最後の更新が両方に伝わります。公式のトラブルシューティングにある例では、parseAsIntegerで読んでいる側にも1.234が入ります。キーとパーサーの組は上のような専用フックに閉じ込めておくのが確実です。

配列の2つの書式:parseAsArrayOfとparseAsNativeArrayOf

配列には書式が2つあります。parseAsArrayOf(parseAsString)は?tags=a,bのように区切り文字で1キーに詰め、2.7.0で入ったマルチパーサーのparseAsNativeArrayOfは?tag=a&tag=bのように同じキーを繰り返します。後者はHTMLフォームのGET送信やバックエンドのフレームワークが標準で解釈する形式なので、既存APIにクエリをそのまま渡す場合はこちらが合います。

オプションの既定値:history・shallow・scroll・clearOnDefault

オプションはパーサーの.withOptions()、フックの第2引数、更新関数の第2引数のどこでも指定でき、呼び出し時の指定が最優先です。2.10.2で確認した既定値は次の4つです。

オプション 既定値 変えたときの動き
history 'replace' 'push'で更新ごとに履歴を追加
shallow true falseでRSC・loaderを再実行
scroll false trueで更新時にページ先頭へ
clearOnDefault true falseで既定値もURLに残す

shallow: trueはNext.jsの浅いルーティングと同じ意味で、URLだけ書き換えてサーバーには知らせません。Server Componentで検索結果を描くページなら、そのキーだけshallow: falseにします。clearOnDefaultは1.x系ではfalseが既定で、2.0.0でtrueに変わりました。1.x時代の記事のコードをそのまま写すと、既定値がURLに出なくなる差が出ます。

2.5.0からはNuqsAdapterのdefaultOptionsでアプリ全体の既定を変えられ、historyは2.9.0で対象に加わりました。

モーダル・タブで戻るボタンを効かせるhistory: ‘push’

詳細モーダルを開いた状態をURLに残し、ブラウザの戻るボタンで閉じられるようにするには、そのキーだけhistory: 'push'にします。

'use client'
import { useQueryState, parseAsBoolean } from 'nuqs'

export function useDetailModal() {
  const [open, setOpen] = useQueryState(
    'detail',
    parseAsBoolean.withDefault(false).withOptions({ history: 'push' })
  )
  return {
    open,
    show: () => setOpen(true),
    close: () => setOpen(null, { history: 'replace' }),
  }
}

testingアダプターでshow()→close()の順に呼ぶと、URL更新は?detail=true(history: 'push')と空文字('replace')の2回でした。閉じる側をreplaceにしているのは、setOpen(null)のままだと閉じる操作も'push'で履歴を1つ積み(同じ実測で確認)、戻るボタンでモーダルが再び開いてしまうためです。公式のOptionsページは、戻るボタンの挙動を変えるのはタブやモーダルのような画面遷移に近い操作に限るよう警告しています。defaultOptionsで'push'を全体に設定すると、検索語の1文字ごとに履歴が増えます。

shallow: falseとuseTransitionによる読み込み状態の表示

shallow: falseでServer Componentを描き直すと、新しい結果が届くまで画面は古いままです。ReactのuseTransitionが返すstartTransitionをオプションに渡すと、その間isPendingがtrueになり、読み込み中の表示を出せます。

'use client'
import { useTransition, type ReactNode } from 'react'
import { useQueryState, parseAsString } from 'nuqs'

export function ResultsPane({ children }: { children: ReactNode }) {
  const [isPending, startTransition] = useTransition()
  const [category, setCategory] = useQueryState(
    'category',
    parseAsString.withDefault('all').withOptions({ shallow: false, startTransition })
  )
  return (
    <section aria-busy={isPending}>
      <select value={category} onChange={(e) => setCategory(e.target.value)}>
        <option value="all">すべて</option>
        <option value="book">書籍</option>
      </select>
      {isPending ? <p>読み込み中…</p> : children}
    </section>
  )
}

このコードはtsc 7.0.2のstrictで型エラーなしでした。1.x系ではstartTransitionを渡すとshallow: falseが自動で付きましたが、2.x系では明示が必要です。React Router v7以降のデータルーターでは、React 19と組み合わせるとloaderの完了までisPendingが続きます。2.10.2では、トランジション中の更新が同期描画に割り込まれたときに値がnullと新しい値の間でちらつく不具合(issue #1567)が修正されたため、startTransitionを使っているなら2.10.2へ上げておきます。

URL更新の間引き:throttleとdebounceの使い分け

ブラウザはHistory APIの呼び出し回数を制限しているため、nuqsはURL更新をキューに溜めて間引きます。既定のthrottleは50msで、Safari 17以上は120ms、それより古いSafariは320msです(2.10.2のソースはUser-AgentのSafariの版でこの値を切り替えています)。testingアダプターで同じティックに3回setQを呼んだところ、URL更新は最後の値で1回だけでした。

2.5.0でthrottleMsは非推奨になり、limitUrlUpdates: throttle(1000)の書き方に移りました。同じlimitUrlUpdatesにdebounce(ms)を渡すと、最後の入力から指定時間たってからURLを更新します。300msのdebounceで「r」「re」「rea」を100ms間隔で入力した実測では、stateは即座にreaになり、URL更新は最後の入力の約330ms後に?q=reaの1回だけでした。

サーバー取得を抑えるdebounceとshallow: falseの組み合わせ

URLの更新を遅らせることと、データの取得を遅らせることは別の話です。公式は、debounceが意味を持つのはshallow: falseと組み合わせてRSCやloaderでサーバー側取得をする場合だけで、TanStack Queryなどでクライアント側取得をするなら、フックが返すstateの側を別のdebounceフックで遅らせるよう案内しています。stateは常に即時更新されるため、URLだけdebounceしてもクライアント側の取得回数は減りません。2.6.0からはshallow: trueとdebounceを組み合わせると開発時に警告が出ます。

'use client'
import { useQueryState, parseAsString, debounce } from 'nuqs'

export function SearchBox() {
  const [q, setQ] = useQueryState(
    'q',
    parseAsString.withDefault('').withOptions({ shallow: false })
  )
  return (
    <input
      type="search"
      aria-label="検索語"
      value={q}
      onChange={(e) =>
        setQ(e.target.value, {
          limitUrlUpdates: e.target.value === '' ? undefined : debounce(500),
        })
      }
    />
  )
}

空にしたときだけ即時更新にしているのは公式の例と同じ考え方で、入力を消した直後に結果を戻すためです。debounceを途中で解除したい呼び出しにはdefaultRateLimitを渡します。

サーバー側での読み取り:createLoader・createSearchParamsCache・createSerializer

サーバー側のAPIはnuqs/serverから読み込みます。クライアントと同じパーサー定義を1ファイルに置けば、URLの形式がずれません。

// app/search/searchParams.ts
import { createLoader, createSerializer, parseAsInteger, parseAsString } from 'nuqs/server'

export const searchParams = {
  q: parseAsString.withDefault(''),
  page: parseAsInteger.withDefault(1),
}
export const loadSearchParams = createLoader(searchParams)
export const serialize = createSerializer(searchParams)

// app/search/page.tsx
import type { SearchParams } from 'nuqs/server'
import { loadSearchParams, serialize } from './searchParams'

type PageProps = { searchParams: Promise<SearchParams> }

export default async function Page({ searchParams }: PageProps) {
  const { q, page } = await loadSearchParams(searchParams)
  const next = serialize('/search', { q, page: page + 1 })
  return <a href={next}>{q} の {page + 1} ページ目へ</a>
}

このコードはtsc 7.0.2のstrictで型エラーなしでした。createLoaderはURL文字列・URLSearchParams・オブジェクト・それらのPromiseを受け取ります。実測では、loadSearchParams('https://ex.com/?page=4&q=nuqs')は{ q: 'nuqs', page: 4 }を返し、{ page: 'x' }のような変換できない値はpage: 1の既定値に落ちました。不正な値で例外を投げたい場合は、2.5.0で入った{ strict: true }を第2引数に渡します。

ページより深いServer Componentで同じ値を読む方法は2つあります。propsで順に渡すか、createSearchParamsCacheで1リクエスト内だけ有効なキャッシュを作るかです。後者はページでawait cache.parse(searchParams)を先に呼び、子のServer Componentではcache.get('q')やcache.all()で読みます(Next.js App RouterのServer Component専用で、Client Componentからは使えません)。階層が浅いならpropsで十分です。createSerializerはclearOnDefaultを既定でtrueとして扱うため、serialize({ page: 1 })は空文字になり、{ page: 2 }で?page=2を返しました。

nuqsを使うコンポーネントのテスト:withNuqsTestingAdapterとVitest

nuqs 2.x系は、テスト用のアダプターnuqs/adapters/testingを同梱しています。ルーターやURLをモックせずに、初期のクエリ文字列を渡し、書き込まれたURLをonUrlUpdateで受け取って検証できます。renderHook向けのwithNuqsTestingAdapterは2.2.0で入りました。前の章のuseListParamsを検証するテストは次のとおりで、Vitest 5.0.5(jsdom環境)で通りました。Vitest自体の設定はVitestの使い方と書き方で扱っています。

import { renderHook, act } from '@testing-library/react'
import { withNuqsTestingAdapter, type UrlUpdateEvent } from 'nuqs/adapters/testing'
import { expect, it } from 'vitest'
import { useListParams } from './useListParams'

it('ページ送りでpだけが更新される', async () => {
  const updates: UrlUpdateEvent[] = []
  const { result } = renderHook(() => useListParams(), {
    wrapper: withNuqsTestingAdapter({
      searchParams: '?p=2&sort=old',
      onUrlUpdate: (e) => updates.push(e),
    }),
  })
  expect(result.current[0]).toEqual({ page: 2, sort: 'old' })
  await act(() => result.current[1]({ page: 3 }))
  expect(updates).toHaveLength(1)
  expect(updates[0]!.queryString).toBe('?p=3&sort=old')
  expect(updates[0]!.options.history).toBe('replace')
})

onUrlUpdateが受け取るイベントには、searchParams(URLSearchParams)、queryString、更新に使われたoptionsが入ります。historyやshallowの指定が意図どおり渡ったかまで確かめられるので、前の章のモーダルのように'push'を使うキーはここで固定しておきます。

つまずきやすいのは、testingアダプターが既定でURLを記憶しない点です。公式のTestingページのとおり、更新は毎回初期のクエリ文字列を土台に組み立てられます。?page=2から始めて{ q: 'a' }→{ page: 5 }と2回更新した実測では、2回目のURLは?page=5で、1回目のq=aは含まれませんでした(フックのstateは{ page: 5, q: 'a' })。hasMemory: trueを渡すと2回目は?page=5&q=aになり、実際のアダプターと同じく更新が積み重なります。複数の操作を続けて検証するテストではhasMemory: trueを付けます。また、testingアダプターは既定でthrottleの待ち時間を0にしています(rateLimitFactorの既定値が0)。throttleの間隔まで検証するならrateLimitFactor: 1を渡します。debounceはこの係数の影響を受けず、テスト中も指定した時間だけ待ちます。

nuqs 2.5〜2.10の新機能と変更点

2.5.0から2.10.0まで、マイナー版は6つ出ています。日付はGitHub Releasesの公開日です。

版 公開日 主な変更
2.5.0 2025-08-22 debounce、キー分離、Standard Schema、TanStack Router
2.6.0 2025-09-05 processUrlSearchParams、debounce警告
2.7.0 2025-09-30 マルチパーサー、testingのmemory
2.8.0 2025-11-17 React Router v5の依存範囲を許容
2.9.0 2026-06-30 React Router v8対応、defaultOptionsにhistory
2.10.0 2026-08-20 ReactアダプターのserverSearch
2.10.1 2026-08-25 不具合修正3件
2.10.2 2026-10-08 不具合修正2件(npm latest)

2.5.0では他にNuqsAdapterのdefaultOptionsとリテラル型パーサーのconst修飾子が入り、throttleMsが非推奨になりました。2.6.0のprocessUrlSearchParamsは、URLに書き出す直前のクエリをアプリ側で加工する仕組みです。2.10.1は、初回描画でURLに値があるときに描画が1回で済むようにする修正など3件、2.10.2はトランジション中の値のちらつきと、別のキーを続けて浅く更新したときにもう一方の値が一時的にnullへ戻る問題(Next.js 16.4で報告されたissue #1612)の2件を直しました。

2026年10月31日時点で3.0は公開されていません(npmのbetaタグは2.10.2-beta.1で、latestより前の版です)。公式のAdaptersページは3.0でRemix・React Router v6・汎用nuqs/adapters/react-routerの各アダプターを削除すると予告しており、作者の2025年の振り返りでは、2026年の目標として実行時にStandard Schemaで検証する3.0と、コアを単一ストアへ書き直すことが挙がっています。

キー分離(Key Isolation)の対応範囲:Next.jsは対象外

キー分離は、URLのあるキーを読むコンポーネントが、そのキーの値が変わったときだけ再描画される仕組みです。無い場合、URLのどこかが変わるたびにURLを読む全コンポーネントが再描画されます。2.5.0の公式ブログが挙げる対応アダプターはReact SPA、React Router(v6・v7)、Remix、TanStack Routerで、Next.jsは含まれていません。Next.jsはURLSearchParamsを1つのContextで配っており、どのキーが変わってもuseSearchParamsの呼び出し元が全部再描画されるためです。2.10.2の配布物でも、キー分離のモジュールを読み込んでいるのはReactアダプターとReact Router系の共通実装で、Next.js用の実装は読み込んでいませんでした。Next.jsでフィルタ項目の多い画面を作る場合は、URLを読むコンポーネントを小さく分けて再描画の範囲を絞ります。

Standard Schema対応とTanStack Routerでの使い方

createStandardSchemaV1はパーサーの組からStandard Schema準拠の検証器を作ります。実測では{ page: '3', q: 'x' }を渡すと{ value: { page: 3, q: 'x' } }が返り、page: 'abc'ではissuesにエラーが入りました。用途は、TanStack RouterのvalidateSearchやtRPCの入力検証のように、Standard Schemaを受け付けるツールへ同じ定義を渡すことです。仕様そのものはStandard Schemaとは?Zod・Valibot・ArkTypeを共通で受け取る仕組みで解説しています。

TanStack Routerについて公式ブログは、ルーター自身の型付きsearch paramsのAPIを使うよう勧めたうえで、nuqsを使ったコンポーネントをnpmや共有ライブラリから読み込む場合の互換手段としてアダプターを位置づけています。

nuqsを選ばない方がよい場面

nuqsは「URLが状態の正本である」画面には強い一方、次の条件では採用しない判断をすべきです。

  • アプリ全体がTanStack Router:ルーターのvalidateSearchとuseSearchで型付きのsearch paramsが揃っており、URLの状態管理だけが目的ならnuqsは原則不要です。nuqsで書かれた既存コンポーネントを再利用する場合が例外です。
  • URLが長くなる状態:公式のLimitsページは2,000文字を超えるなら設計を見直す目安としています。フォームの下書きや大きなJSONはZustandなどの状態管理ライブラリやサーバー側に置きます。
  • 共有されてはいけない値:URLは履歴・ログ・Refererに残ります。トークンや個人情報は置きません。
  • クライアント取得の回数を減らしたいだけ:前述のとおりURLのdebounceでは減りません。TanStack Queryのキーに渡す値をdebounceします。

検索エンジン向けには、表示内容を変えないクエリ(UIの開閉など)だけを持つページならクエリを除いたcanonicalを指定し、内容を決めるクエリ(商品IDなど)ならcanonicalにも含める、というのが公式のSEOページの方針です。後者はcreateSerializerでcanonical URLを組み立てられます。操作の順番でキーの並びが変わり、同じ内容のURLが何通りもできるのが気になる場合は、NuqsAdapterのprocessUrlSearchParamsでsearch.sort()を呼んでキーを常にアルファベット順に並べます。検索・絞り込みの多い業務画面を、URL設計から含めて作りたい場合は、弊社の業務用・Webアプリ開発でもご相談を受けています。

よくある質問

nuqsはVueやSvelteでも使えますか?

使えません。nuqsはReact向けで、公式アダプターもReact系フレームワークだけです。作者は2026年の目標としてコアの単一ストア化を挙げ、それによりSolid・Svelte・Vue版も理論上は可能になるとしつつ、React側の保守だけで手一杯だとも書いています。

nuqsはTanStack Startで使えますか?

2.10.2時点では公式の対象外です。TanStack Router向けのアダプター(nuqs/adapters/tanstack-router)は実験的な扱いで、公式のAdaptersページはTanStack Startにはまだ対応していないと明記しています。TanStack Startでは、ルーターのvalidateSearchとuseSearchでsearch paramsを扱う方が確実です。

shallowオプションは何を切り替えますか?

URLを書き換えたときにサーバーへ知らせるかどうかです。既定のtrueはURLだけ更新し、falseでNext.jsのServer ComponentやReact Router・Remixのloaderが再実行されます。React SPAでは効果がありません。

NuqsAdapterを入れないとどうなりますか?

nuqs requires an adapter to work with your framework.というエラーで止まります。2.x系はアダプターが必須で、Next.js App Routerならルートのlayout.tsxをnuqs/adapters/next/appのNuqsAdapterで包みます。

nuqsはReact Routerで使えますか?

使えます。公式アダプターはv6・v7・v8の版ごとにあり、v6向けは3.0で削除予定なので、新規ならv7かv8を使います。loaderで値を使うキーにはshallow: falseを付けます。

関連記事

お気に入りに入れた記事の一覧

一創の公式 SNS

X では毎朝の新着記事と IT ニュースの速報を、YouTube・TikTok・Instagram・LinkedIn・Facebook では記事の解説動画を配信しています。

この記事は以下の記事からリンクされています

資料請求

今日のトレンド記事 直近 24 時間で、いつもより多く読まれている記事

  1. 2026.11.18 テックブログ Java脆弱性CVE-2026-114938(Java4Shell)とは?影響版・修正版と回避フラグの実装手順
  2. 2026.11.11 テックブログ Vite 脆弱性 GHSA-p4f5-76q4-ffq7:開発サーバーRCEの確認と修正版への更新
  3. 2026.11.18 テックブログ 楽天証券の不正アクセス:最大約447万口座の対象確認と、テスト環境に本番データを置かない実装
  4. 2026.11.17 テックブログ チャットプラスの不正アクセス:導入企業がチャット履歴の個人データと報告準備を確かめる手順
  5. 2026.11.19 テックブログ 大崎電気のランサムウェア被害|スマートメーター生産停止の経緯と工場の生産系を守る手順

RELATED POSTS 関連記事

目次