- name
- frontend-typescript-rules
- description
- React/TypeScriptの型安全性、コンポーネント設計、状態管理ルールを適用。Reactコンポーネント実装時に使用。
TypeScript 開発ルール（フロントエンド）
実装向けの frontend 固有 React/TypeScript ルール: レビューシグナル、境界での型安全性、コンポーネント/状態の設計、エラーハンドリング、プロジェクト規約。
前提条件の検出
プロジェクト規約を適用する前に、TypeScript、bundler/framework、lint・format、path alias、React Compiler、代表的なコンポーネントの設定を確認する。設定またはリポジトリで確立済みのパターンに裏付けられた規約を確認済みとして扱い、限られた例から導いた結論には推測であることを明記する。競合するパターンによって公開される振る舞い、互換性、コンポーネント境界が変わる場合は作業を止め、必要な情報源または判断を具体的に示す。
設計のレビューシグナル
合否のしきい値ではなく、見直しのきっかけとして使う。既存のプロジェクト規約とそのコンポーネントの責務を優先する。
- prop drilling が 3 階層以上: Context または状態管理への持ち上げを見直す
- コンポーネントが 300 行超: 複数の責務が混在していないか見直す
- Props が 10 個超: 所有の範囲または分割を見直す
- optional Props が 50% 超: デフォルト値または所有の範囲を見直す
- Props のネストが 2 階層超: フラット化を見直す
境界での型安全性
信頼できない型または取得できない型はunknownで受け、型ガードで絞り込む。asは、runtime/frameworkの不変条件によって対象の型が保証される場合にのみ使用し、その不変条件を近くのコメントに記録する。既存の生成コードまたはサードパーティの型宣言に含まれるanyは、ラップすべき境界入力であり、アプリケーションの契約へanyを広げる根拠にはならない。
アプリ内部では React の Props/State は型保証されており unknown は不要。外部境界では必ず unknown で受け、使用前に型ガードで絞り込む: API レスポンス、localStorage/sessionStorage、URL パラメータ、パースした JSON。制御コンポーネントのフォーム入力は React 合成イベントを通じて型安全に保たれる。
const raw: unknown = await (await fetch(url)).json()
if (!isUser(raw)) throw new ValidationError('invalid user')
const user = raw // User に絞り込み済み
コンポーネントと状態の設計
- Function component のみ。 class component は Error Boundary に限り許可（hook の代替が存在しないため）
- Props は名前付き型で明示し分割代入する:
function UserCard({ user, onSelect }: UserCardProps)。propsを関数に直接型付けしてProps契約を明示する - Props 駆動: 1つの明確な親コンポーネントが所有する依存はPropsで渡す。互いに隣接しない複数の子孫が値を共有し、Propsの中継によって所有責務を持たない中間コンポーネントが増える場合は、Contextまたは確立済みのグローバルstateを使用する
- Custom hook をロジック再利用と依存注入の単位とする（テスト容易性のため、依存オブジェクトは hook 経由で注入する）
- 関数引数: 位置引数は 0〜2 個。3 個以上は単一の options オブジェクトで受ける
- 状態の形: 状態は明示的に型付けする。複数フィールドかつ離散的な遷移を持つ状態は、複数の
useStateではなく discriminated union の action 型を用いたuseReducerにする