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. パフォーマンスの最適化（MEDIUM）

• perf-throttle-updates - limitUrlUpdates を使って URL の更新をスロットリングする
• perf-clear-on-default - clearOnDefault を使って URL をすっきりさせる
• perf-avoid-rerender - URL の状態を使うコンポーネントをメモ化する
• perf-serialize-utility - リンク URL に createSerializer を使う
• perf-debounce-search - サーバーに送信する検索更新をデバウンスする

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 - urlKeys を使って URL を短くする
• advanced-eq-function - オブジェクトパーサー用の eq 関数を実装する
• advanced-framework-adapters - フレームワーク固有のアダプターを使う

使い方

まず、プロジェクトのルートで実行します。

npx -y @pymodel/react-frontend-skills detect             # installed vs. targeted versions
npx -y @pymodel/react-frontend-skills scan --skill nuqs  # deprecated APIs → rule IDs

タスクに該当する上記の各ルールと、各 scan のヒットについて、references/<rule-id>.md を読み、重要な理由と、誤ったコードと正しいコードを確認してください。