nuqs

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

Next.js アプリケーションで nuqs を使用した、型安全な URL クエリ状態管理の包括的なガイドです。コード生成、リファクタリング、コードレビューを支援するため、影響度に基づいて優先順位を付けた 8 カテゴリー、42 のルールを掲載しています。

適用する場面

次のような場合に、これらのガイドラインを参照してください。

• nuqs を使った URL ベースの状態を実装する場合
• Next.js プロジェクトで nuqs を設定する場合
• URL パラメーター用のパーサーを設定する場合
• URL 状態を Server Components と統合する場合
• URL 更新のパフォーマンスを最適化する場合
• nuqs 関連の問題をデバッグする場合

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

優先度	カテゴリー	影響度	接頭辞
1	パーサーの設定	重大	parser-
2	アダプターとセットアップ	重大	setup-
3	状態管理	高	state-
4	サーバーとの統合	高	server-
5	パフォーマンスの最適化	中	perf-
6	履歴とナビゲーション	中	history-
7	デバッグとテスト	低～中	debug-
8	高度なパターン	低	advanced-

クイックリファレンス

1. パーサーの設定（重大）

• 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 - URL 上で 1 始まりの表示を行うには parseAsIndex を使用する
• parser-hex-colors - 色の値には parseAsHex を使用する

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

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

3. 状態管理（高）

• 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 にアクセスするにはセッターの戻り値を使用する

4. サーバーとの統合（高）

• server-search-params-cache - Server Components には createSearchParamsCache を使用する
• 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. パフォーマンスの最適化（中）

• perf-throttle-updates - 急速な URL 更新をスロットルする
• perf-clear-on-default - URL をすっきり保つために clearOnDefault を使用する
• perf-avoid-rerender - URL の状態を使用するコンポーネントをメモ化する
• perf-serialize-utility - リンク URL に createSerializer を使用する
• perf-debounce-search - URL を更新する前に検索入力をデバウンスする

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

• history-push-navigation - ナビゲーションのような状態には history:push を使用する
• history-replace-ephemeral - 一時的な状態には history:replace を使用する
• history-scroll-behavior - URL 変更時のスクロール動作を制御する
• history-back-sync - ブラウザーの戻る／進むナビゲーションに対応する

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

• debug-enable-logging - トラブルシューティングのためにデバッグログを有効にする
• debug-common-errors - よくある nuqs のエラーを診断する
• debug-testing - URL の状態を使用するコンポーネントをテストする

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

• advanced-custom-parsers - 複雑な型向けのカスタムパーサーを作成する
• advanced-url-keys - URL を短くするために urlKeys を使用する
• advanced-eq-function - オブジェクトパーサー向けに eq 関数を実装する
• advanced-framework-adapters - フレームワーク固有のアダプターを使用する

使用方法

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

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

リファレンスファイル

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