typescript-react-patterns

TypeScript React パターン

TypeScript による型安全な React。コンポーネントの型付け、フック、イベント処理、ref、ジェネリクス、コンテキスト、ユーティリティ型を網羅する、7 カテゴリーにわたる 33 のルールが含まれています。

メタデータ

• バージョン： 2.0.0
• ルール数： 7 カテゴリーにわたる 33 のルール
• ライセンス： MIT

適用するタイミング

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

• React コンポーネントの props に型を付けるとき
• TypeScript でカスタムフックを作成するとき
• 適切な型でイベントを処理するとき
• ref（DOM、可変値、命令型）を扱うとき
• ジェネリックで再利用可能なコンポーネントを構築するとき
• 型付き Context プロバイダーを設定するとき
• React コードの TypeScript エラーを修正するとき

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

優先度	カテゴリー	影響度	プレフィックス
1	コンポーネントの型付け	CRITICAL	comp-
2	フックの型付け	CRITICAL	hook-
3	イベント処理	HIGH	event-
4	ref の型付け	HIGH	ref-
5	ジェネリックコンポーネント	MEDIUM	generic-
6	コンテキストと状態	MEDIUM	ctx-
7	ユーティリティ型	LOW	util-

クイックリファレンス

1. コンポーネントの型付け（CRITICAL）

• comp-props-interface - props には interface、ユニオンには type を使用する
• comp-children-types - children に正しい型を付ける（ReactNode、ReactElement）
• comp-default-props - 分割代入のデフォルト値でデフォルト props を設定する
• comp-forward-ref - forwardRef コンポーネントに型を付ける
• comp-polymorphic - ポリモーフィックな "as" prop に型を付ける
• comp-fc-vs-function - 関数宣言と React.FC の使い分け
• comp-display-name - デバッグ用の表示名
• comp-rest-props - 適切な型で rest props をスプレッドする

2. フックの型付け（CRITICAL）

• hook-usestate - useState に適切なジェネリック型を指定する
• hook-useref - DOM 要素や可変値に useRef を使用する
• hook-use-reducer - 判別可能なユニオン型のアクションで useReducer を使用する
• hook-use-callback - 型付きパラメーターで useCallback を使用する
• hook-use-memo - 戻り値に型を付けて useMemo を使用する
• hook-use-context - null チェックを行いながら useContext を使用する
• hook-custom-hooks - カスタムフックの戻り値の型
• hook-generic-hooks - ジェネリックなカスタムフック

3. イベント処理（HIGH）

• event-handler-types - イベントハンドラーの型パターン
• event-click-handler - クリックイベントの型付け
• event-form - フォームイベントの処理（submit、change、select）
• event-keyboard - キーボードイベントの型

4. ref の型付け（HIGH）

• ref-dom-elements - 特定の HTML 要素型で useRef を使用する
• ref-callback - DOM の測定にコールバック ref パターンを使用する
• ref-imperative-handle - useImperativeHandle に型を付ける

5. ジェネリックコンポーネント（MEDIUM）

• generic-list - ジェネリックなリストコンポーネント
• generic-select - ジェネリックなセレクト／ドロップダウン
• generic-table - 列に型を付けたジェネリックなテーブル
• generic-constraints - extends を使ったジェネリック制約

6. コンテキストと状態（MEDIUM）

• ctx-create - 型付きコンテキストを作成する
• ctx-provider - null チェックフックを使うプロバイダーパターン
• ctx-reducer - useReducer を使ったコンテキスト

7. ユーティリティ型（LOW）

• util-component-props - HTML props に ComponentPropsWithoutRef を使用する
• util-pick-omit - props の派生に Pick、Omit、Partial を使用する
• util-discriminated-unions - 状態マシンに判別可能なユニオン型を使用する

重要なパターン

コンポーネントの props

interface ButtonProps {
  variant: 'primary' | 'secondary' | 'danger'
  size?: 'sm' | 'md' | 'lg'
  children: React.ReactNode
  onClick?: () => void
}

function Button({ variant, size = 'md', children, onClick }: ButtonProps) {
  return (
    <button className={`btn-${variant} btn-${size}`} onClick={onClick}>
      {children}
    </button>
  )
}

null チェック付きの型付きコンテキスト

interface AuthContextType {
  user: User | null
  login: (credentials: Credentials) => Promise<void>
  logout: () => void
}

const AuthContext = createContext<AuthContextType | null>(null)

function useAuth() {
  const context = useContext(AuthContext)
  if (!context) throw new Error('useAuth must be used within AuthProvider')
  return context
}

ジェネリックコンポーネント

interface ListProps<T> {
  items: T[]
  renderItem: (item: T) => React.ReactNode
  keyExtractor: (item: T) => string
}

function List<T>({ items, renderItem, keyExtractor }: ListProps<T>) {
  return <ul>{items.map(item => <li key={keyExtractor(item)}>{renderItem(item)}</li>)}</ul>
}

使用方法

詳しい説明については、個別のルールファイルを参照してください：

rules/comp-props-interface.md
rules/hook-usestate.md
rules/event-form.md
rules/ref-dom-elements.md
rules/util-discriminated-unions.md

参考資料

• React TypeScript チートシート
• React + TypeScript ガイド
• TypeScript ハンドブック

完全版ドキュメント

すべてのルールを展開した完全なガイド：AGENTS.md