SWRデータ管理スキル

重要: useSWR/useSWRMutation/hcをコンポーネント内で直接使用せず、必ずカスタムフック経由で使用します。

いつ使うか

このスキルは以下の場合に使用してください：

• サーバーからデータを取得する
• サーバーのデータを作成・更新・削除する
• データ取得・変更のロジックをコンポーネントから分離したい
• キャッシュ管理を統一したい

注意: クライアント内で完結する UI 状態（サイドバー、テーマ、URL 同期）には manage-client-state スキルを使用してください。

クイックスタート

1. SWRキー定義

// apps/admin/src/swr/users/user-swr-keys.ts
import type { SearchUsersParams } from '@/features/users/lib/search-params'

export const userSwrKeys = {
  list: (params: SearchUsersParams) => ['admin', 'users', params] as const,
  detail: (id: string) => ['admin', 'users', id] as const,
} as const

2. データ取得フック

// apps/admin/src/swr/users/use-user.ts
import useSWR from 'swr'
import { parseResponse } from 'hono/client'
import { hc } from '@/utils/hc'
import { userSwrKeys } from './user-swr-keys'

export function useUser(id: string) {
  return useSWR(userSwrKeys.detail(id), async () => {
    const data = await parseResponse(
      hc.admin.users[':id'].$get({ param: { id } })
    )
    return data.user
  })
}

3. データ変更フック

// apps/admin/src/swr/users/use-mutate-user.ts
import { useRouter } from 'next/navigation'
import type { CreateUserBody } from '@repo/schemas/request/admin/users.dto'
import { parseResponse } from 'hono/client'
import { toast } from 'sonner'
import useSWRMutation from 'swr/mutation'
import { hc } from '@/utils/hc'

export function useCreateUser() {
  const router = useRouter()

  const { trigger, isMutating: isCreating } = useSWRMutation(
    ['/admin/users', 'create'],
    async (_key, { arg }: { arg: CreateUserBody }) => {
      return await parseResponse(hc.admin.users.$post({ json: arg }))
    },
    {
      onSuccess: () => {
        toast.success('ユーザーを作成しました')
        router.push('/users')
      },
      onError: (e) => {
        toast.error(e instanceof Error ? e.message : 'ユーザーの作成に失敗しました')
      },
    }
  )

  return { createUser: trigger, isCreating }
}

重要ルール

データ取得

• カスタムフック経由:

  useSWR/hc

  を直接使用しない
• 配置:

  apps/admin/src/swr/[entity]/use-[entity].ts

  （単一）、

  use-[entities].ts

  （一覧）
• SWRキー:

  [entity]-swr-keys.ts

  で一元管理
• parseResponse: Hono RPCの型安全なエラーハンドリング

データ変更

• 配置:

  apps/admin/src/swr/[entity]/use-mutate-[entity].ts

  （同一ファイル内で複数export function）
• フックの使用場所: カスタムボタンコンポーネント内、またはConfirmation Dialog内
• 状態管理:

  useState

  不要、

  isMutating

  を直接使用
• ナビゲーション:

  router.push()

  のみ（

  router.refresh()

  は不要）
• キャッシュ無効化:

  mutate()

  は使用しない（Background Revalidationに任せる）

Mutation パターン

2つのパターンがあり、エンティティの特性に応じて使い分けます：

パターンA（一般的）: 詳細ページ（

/[entity]/[id]

）がある

• Mutation key:

  entityKeys.detail(id)

• Hook定義:

  useUpdateEntity(id: string)

  - 初期化時にidを受け取る

パターンB（例外）: 一覧で直接CRUD操作

• Mutation key:

  entityKeys.list()

• Hook定義:

  useUpdateEntity()

  - 実行時にidを受け取る

詳細は mutation-patterns.md を参照してください。

ディレクトリ構造

apps/admin/src/swr/
└── [entity]/
    ├── [entity]-swr-keys.ts      # SWRキー定義
    ├── use-[entity].ts            # 単一データ取得
    ├── use-[entities].ts          # 一覧データ取得
    └── use-mutate-[entity].ts     # データ変更（複数フック定義）

詳細パターン

詳細な実装パターンについては references を参照してください：

• fetch-data.md - データ取得、エラーハンドリング、条件付きフェッチ
• mutate-data.md - データ変更、カスタムボタン、Confirmation Dialog
• mutation-patterns.md - パターンA/B、楽観的更新、キャッシュ戦略

関連スキル

• build-api-hono: Hono RPC統合、型安全なAPI呼び出し
• handle-forms-rhf-zod: フォームとの統合
• optimize-conditional-rendering-activity: データ取得状態の表示
• manage-client-state: UI状態管理との使い分け