nuqs-v2

Next.js と React 向けの nuqs コミュニティベストプラクティス

Next.js、React Router、TanStack Router、Remix、プレーンな React で nuqs を使用した、型安全な URL クエリ状態管理の包括的なガイドです。nuqs v2.5〜v2.9 の機能を扱います。8 つのカテゴリにわたる 39 のルールを収録し、コード生成、リファクタリング、コードレビューの指針となるよう、影響度の高い順に優先順位を付けています。

適用するタイミング

以下の場合に、このガイドラインを参照してください。

• nuqs を使って URL ベースの状態を実装する場合
• Next.js または React Router プロジェクトで nuqs を設定する場合
• URL パラメーター用のパーサーを設定する場合
• URL 状態をサーバーコンポーネントと連携させる場合
• URL 更新のパフォーマンスを最適化する場合（limitUrlUpdates、キーの分離）
• Standard Schema を通じて、tRPC／TanStack Router／フォームとパーサー定義を共有する場合
• nuqs 関連の問題をデバッグする場合

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	パーサー設定	CRITICAL	parser-
2	アダプターとセットアップ	CRITICAL	setup-
3	状態管理	HIGH	state-
4	サーバー連携	HIGH	server-
5	パフォーマンス最適化	MEDIUM	perf-
6	履歴とナビゲーション	MEDIUM	history-
7	デバッグとテスト	LOW-MEDIUM	debug-
8	高度なパターン	LOW	advanced-

クイックリファレンス

1. パーサー設定（CRITICAL）

• parser-use-typed-parsers — 文字列以外の値には型付きパーサーを使用する
• parser-with-default — null を許容しない状態には withDefault を使用する
• parser-enum-validation — 制約付きの値には列挙型パーサーを使用する
• parser-array-format — 適切な配列パーサーの形式を選択する
• parser-json-validation — JSON パーサーの入力を検証する
• parser-date-format — 適切な日付パーサーを選択する
• parser-index-offset — URL で 1 始まりの表示を行うには parseAsIndex を使用する

2. アダプターとセットアップ（CRITICAL）

• setup-nuqs-adapter — アプリを NuqsAdapter でラップする
• setup-use-client — フックには 'use client' ディレクティブを追加する
• setup-import-server — サーバーユーティリティは nuqs/server からインポートする
• setup-nextjs-version — 互換性のある Next.js バージョンを確認する
• setup-shared-parsers — 専用ファイルで共有パーサーを定義する
• setup-default-options — NuqsAdapter でアプリ全体のデフォルトを設定する（v2.5+）

3. 状態管理（HIGH）

• state-use-query-states — 関連するパラメーターには useQueryStates を使用する
• state-clear-with-null — null を使用して URL パラメーターをクリアする
• state-avoid-derived — URL パラメーターから派生状態を作成しない
• state-options-inheritance — パーサーレベルの設定には withOptions を使用する
• state-setter-return — URL にアクセスするにはセッターの戻り値を使用する
• state-standard-schema — ライブラリ間の検証には Standard Schema を使用する（v2.5+）

4. サーバー統合（高）

• server-search-params-cache — Server Components では createSearchParamsCache（または createLoader）を使用します
• server-shallow-false — サーバーで再レンダリングをトリガーするには shallow:false を使用します
• server-use-transition — ローディング状態に useTransition を統合します
• server-parse-before-get — Server Components では get() の前に parse() を呼び出します
• server-next15-async — Next.js 15 以降で非同期の searchParams を処理します

5. パフォーマンス最適化（中）

• perf-throttle-updates — limitUrlUpdates で頻繁な URL 更新をスロットリングします
• perf-debounce-search — 組み込みの limitUrlUpdates で検索入力をデバウンスします
• perf-clear-on-default — URL を簡潔にするために clearOnDefault を使用します
• perf-avoid-rerender — URL 状態を使用するコンポーネントをメモ化します（Next.js）
• perf-key-isolation — Next.js 以外ではキーの分離を利用します（v2.5+）
• perf-serialize-utility — リンク URL には createSerializer を使用します

6. 履歴とナビゲーション（中）

• history-push-navigation — history:push と history:replace のどちらを使うか選択します
• history-scroll-behavior — URL 変更時のスクロール動作を制御します

7. デバッグとテスト（低〜中）

• debug-enable-logging — トラブルシューティングのためにデバッグログを有効にします
• debug-testing — URL 状態を使用するコンポーネントをテストします

8. 高度なパターン（低）

• advanced-custom-parsers — 複雑な型用のカスタムパーサーを作成します
• advanced-url-keys — URL を短くするために urlKeys を使用します
• advanced-eq-function — オブジェクトパーサー用の eq 関数を実装します
• advanced-framework-adapters — フレームワーク固有のアダプターを使用します
• advanced-process-url-search-params — processUrlSearchParams で URL の形式を正規化します（v2.6+）

使用方法

詳しい説明とコード例については、各リファレンスファイルをお読みください。

• セクションの定義 — カテゴリー構成と影響レベル
• ルールのテンプレート — 新しいルールを追加するためのテンプレート

リファレンスファイル

ファイル	説明
compiled.md	すべてのルールを含む完全なコンパイル済みガイド
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとリファレンス情報

相互連携

• URL に含まれないグループ化された／ローカルな状態については、ahooks-v3 と併用します
• 非同期のサーバーデータ（クエリのローディング／エラー）については、tanstack-query-v5 と併用します
• 状態の判断ツリー：URL で共有可能な UI → nuqs、グループ化された一時的な UI → ahooks、非同期データ → TanStack Query