nuqs

LLM リファレンス： ドキュメントのインデックスと最新の API を取得するには、llms.txt を参照してください。全ドキュメントをまとめたファイル：llms-full.txt。人間が読みやすいドキュメント：nuqs.dev/docs。

このスキルで上流の API リファレンスを重複させないでください。パーサー、オプション、テストアダプター、トラブルシューティングには llms.txt ／ llms-full.txt を使用してください。

---

URL 状態のルール（FMC）

アプリ	URL 状態
TanStack Router を使用（SPA または Start）	ルーターの検索パラメーター：validateSearch — スキル tanstack-router-conventions。nuqs は使用しないでください。
TanStack Router を使用しない Vite React アプリ	nuqs

TanStack Router では、代わりに validateSearch を使用してください（tanstack-router-conventions → references/params-search-ui-routes.md）。

---

セットアップ（Vite、ルーターなし）

上流の詳細：インストール · アダプター。

import { NuqsAdapter } from 'nuqs/adapters/react'

createRoot(root).render(
  <NuqsAdapter>
    <App />
  </NuqsAdapter>,
)

nuqs 2.9.5 でアダプターのエクスポートを確認済みです：nuqs/adapters/react の NuqsAdapter。テストでは nuqs/adapters/testing の NuqsTestingAdapter を使用してください（上流のテストを参照）。

状態の分割： URL で共有可能な状態 → nuqs、エフェメラルな UI → Zustand（zustand-state-management）。

---

影響の大きい注意点

1. clearOnDefault — デフォルトは true です（デフォルト値と等しい値は URL から削除されます）。デフォルト値でもパラメーターを表示したままにする必要がある場合に限り、false を設定してください。
2. 履歴と shallow — 履歴のデフォルトは replace です（戻るボタンの履歴を残す場合は history: 'push' を渡します）。shallow のデフォルトは true です。
3. parseAsJson — v2 以降では、実行時バリデーター（Zod スキーマなど）が必要です。
4. デバッグ — localStorage.debug = 'nuqs'。
5. パッケージ — ESM 専用です。v2 で nuqs/parsers エントリーポイントが削除されたため、パーサーは nuqs からインポートしてください。
6. useQueryStates — 関連するパラメーター（フィルター、緯度／経度／ズーム）をまとめて、1 回の URL 更新にしてください。

---

関連する FMC スキル

スキル	役割
tanstack-router-conventions	TanStack Router を使用するアプリでの validateSearch
zustand-state-management	URL に含めないエフェメラルなクライアント状態