Community nuqs Best Practices for Next.js & React

Next.js、React Router、TanStack Router、Remix、プレーン React 全般にわたる、nuqs を使用した型安全な URL クエリ状態管理の包括ガイド。nuqs v2.5–v2.8 の機能をカバー。8 カテゴリーにおける 46 のルールを含み、コード生成、リファクタリング、コードレビューをガイドするため影響度で優先順位付けされています。

適用場面

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

• nuqs を使用した URL ベースの状態実装
• Next.js または React Router プロジェクトで nuqs をセットアップ
• URL パラメータ用のパーサー設定
• URL 状態を Server Components と統合
• URL 更新パフォーマンスの最適化 (limitUrlUpdates、キー分離)
• tRPC / TanStack Router / フォームと Standard Schema 経由でパーサー定義を共有
• 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 — 制約された値に enum パーサーを使用
• parser-array-format — 正しい配列パーサー形式を選択
• parser-json-validation — JSON パーサー入力を検証
• parser-date-format — 適切な日付パーサーを選択
• parser-index-offset — 1 ベースの URL 表示に parseAsIndex を使用
• parser-hex-colors — カラー値に parseAsHex を使用

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-functional-updates — 派生状態に関数更新を使用
• state-clear-with-null — null で URL パラメータをクリア
• state-controlled-inputs — 制御入力値を適切に処理
• state-avoid-derived — URL パラメータからの派生状態を回避
• state-options-inheritance — パーサーレベルの設定に withOptions を使用
• state-setter-return — URL アクセスにセッターの戻り値を使用
• state-standard-schema — クロスライブラリ検証に Standard Schema を使用 (v2.5+)

4. サーバー統合 (HIGH)

• 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-share-parsers — クライアントとサーバー間でパーサーを共有
• server-next15-async — Next.js 15+ で非同期 searchParams を処理

5. パフォーマンス最適化 (MEDIUM)

• 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. 履歴 & ナビゲーション (MEDIUM)

• history-push-navigation — ナビゲーション的な状態に history:push を使用
• history-replace-ephemeral — エフェメラル状態に history:replace を使用
• history-scroll-behavior — URL 変更時のスクロール動作を制御
• history-back-sync — ブラウザの戻る/進むナビゲーションを処理

7. デバッグ & テスト (LOW-MEDIUM)

• debug-enable-logging — トラブルシューティング用のデバッグログを有効化
• debug-common-errors — 一般的な nuqs エラーを診断
• debug-testing — URL 状態でコンポーネントをテスト

8. アドバンスパターン (LOW)

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

使用方法

詳細な説明とコード例については、個別の参考ファイルを読んでください：

• セクション定義 — カテゴリー構造と影響度レベル
• ルールテンプレート — 新しいルール追加用テンプレート

参考ファイル

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