ahooks-v3

スキル：ahooks

対象範囲

• 対象：ahooks v3 以降の、React の状態管理、状態の一括更新、localStorage への永続化のためのユーティリティフック
• 対象外：データ取得（TanStack Query を使用）、URL の状態管理（nuqs を使用）、複雑な状態マシン、非同期処理

前提条件

• ahooks v3 以降
• フックをサポートする React 18 以降
• 型推論のための TypeScript v5 以降
• クライアントサイドのみ（フックが localStorage 用のブラウザー API を必要とします）

原則

• 一緒に変更される状態のグループ化には useSetState を使用します（URL で共有しない場合）
• ブラウザーセッションをまたいで状態を永続化するには useLocalStorageState を使用します
• URL で共有する状態には、localStorage より nuqs を優先します
• 非同期処理とローディング状態には、TanStack Query を優先します
• useState は単純で独立した状態にのみ使用します（まれです）

制約

必須

• URL に含めない状態をグループ化するには useSetState を使用します（フォームの状態、ゲームエンジンの状態、一時的な UI の状態）
• localStorage への永続化には useLocalStorageState を使用します

推奨

• URL で共有する状態には、localStorage より nuqs を優先します
• 非同期処理とローディング状態には、TanStack Query を優先します
• 型安全な状態のために TypeScript のジェネリクスを使用します：useLocalStorageState<boolean>('key', { defaultValue: false })

回避

• URL の状態管理に使用すること（代わりに nuqs を使用します）
• ローディング状態やエラー状態に使用すること（代わりに TanStack Query を使用します）
• 複雑な非同期処理に使用すること（代わりに TanStack Query を使用します）
• 明示的な同期ロジックなしに、URL の状態と localStorage を混在させること

相互連携

• URL の状態管理には nuqs-v2 を併用します（双方向に同期できます）
• 非同期処理には TanStack Query を併用します（データ取得には TanStack Query を使用します）
• 状態管理の選択ツリーの一部です（React のルールを参照）
• React 18 以降のフックアーキテクチャで動作します

パターン

useSetState パターン

一緒に更新される状態のグループに使用します：

import { useSetState } from 'ahooks'

const [state, setState] = useSetState({
  name: '',
  email: '',
  age: 0,
})

// Partial updates (shallow merge)
setState({ name: 'John' })
setState(prev => ({ ...prev, email: '[email protected]' }))

使用する場合：フォームの状態、ゲームエンジンの状態、一緒に変更される UI の状態（URL で共有しない場合）

使用しない場合：URL で共有する状態（nuqs を使用）、ローディング状態（TanStack Query を使用）

useLocalStorageState パターン

ブラウザーセッションをまたいで永続化する状態に使用します：

import { useLocalStorageState } from 'ahooks'

const [value, setValue] = useLocalStorageState<boolean>('key', {
  defaultValue: false,
})

// Type-safe with generics
const [settings, setSettings] = useLocalStorageState<Settings>('settings', {
  defaultValue: { theme: 'light', fontSize: 14 },
})

使用する場合：ユーザー設定、デバッグフラグ、セッションをまたいで保持する設定

使用しない場合：URL で共有する状態（nuqs を使用）、機密データ（セキュアストレージを使用）

nuqs との連携

URL と localStorage 間の双方向同期：

import { useLocalStorageState } from 'ahooks'
import { useQueryState } from 'nuqs'
import { useEffect, useRef } from 'react'

const [queryState, setQueryState] = useQueryState('debug')
const [storageState, setStorageState] = useLocalStorageState<boolean>('debug', {
  defaultValue: false,
})
const isFirstMount = useRef(true)

// Sync on mount: localStorage → URL
useEffect(() => {
  if (isFirstMount.current) {
    isFirstMount.current = false
    if (storageState && queryState !== 'true') {
      setQueryState('true')
      return
    }
  }
  // Sync changes: URL → localStorage
  if (queryState === 'true' && !storageState) {
    setStorageState(true)
  } else if (queryState === 'false' && storageState) {
    setStorageState(false)
  }
}, [queryState, storageState, setQueryState, setStorageState])

ユースケース：URL で共有でき、かつ永続化するデバッグフラグや機能切り替え

状態管理の選択ツリー

1. URL で共有する状態 → nuqs を使用します（フィルター、検索、タブ、ページネーション）
2. URL に含めない状態のグループ → useSetState を使用します（フォームの状態、ゲームエンジン、一時的な UI）
3. 非同期処理 → TanStack Query を使用します（データ取得、ミューテーション、キャッシュ）
4. localStorage への永続化 → useLocalStorageState を使用します（ユーザー設定、設定）
5. 単純で独立した状態 → useState を使用します（まれです。他の選択肢を優先してください）

参考資料

• ahooks ドキュメント - 公式ドキュメント
• React のルール - 状態管理の選択ツリーとパターン
• TanStack Query - 非同期処理とデータ取得のパターン