React TypeScript

型安全な React = コンパイル時保証 = 自信を持ったリファクタリング。

<when_to_use>

• 型付き React コンポーネントの構築
• ジェネリックコンポーネントの実装
• イベントハンドラー、フォーム、ref の型付け
• React 19 機能の使用（Actions、Server Components、use()）
• ルーター統合（TanStack Router、React Router）
• 適切な型付けを備えたカスタムフック

NOT for: React 以外の TypeScript、バニラ JS React

</when_to_use>

<react_19_changes>

React 19 の破壊的変更には移行が必要です。主なパターン：

ref as prop - forwardRef 非推奨：

// React 19 - ref を通常の prop として
type ButtonProps = {
  ref?: React.Ref<HTMLButtonElement>;
} & React.ComponentPropsWithoutRef<'button'>;

function Button({ ref, children, ...props }: ButtonProps) {
  return <button ref={ref} {...props}>{children}</button>;
}

useActionState - useFormState の代わり：

import { useActionState } from 'react';

type FormState = { errors?: string[]; success?: boolean };

function Form() {
  const [state, formAction, isPending] = useActionState(submitAction, {});
  return <form action={formAction}>...</form>;
}

use() - Promise とコンテキストをアンラップ：

function UserProfile({ userPromise }: { userPromise: Promise<User> }) {
  const user = use(userPromise); // 解決まで Suspend
  return <div>{user.name}</div>;
}

詳細は react-19-patterns.md を参照。useOptimistic、useTransition、移行チェックリストを含みます。

</react_19_changes>

<component_patterns>

Props - ネイティブ要素を拡張：

type ButtonProps = {
  variant: 'primary' | 'secondary';
} & React.ComponentPropsWithoutRef<'button'>;

function Button({ variant, children, ...props }: ButtonProps) {
  return <button className={variant} {...props}>{children}</button>;
}

Children 型付け：

type Props = {
  children: React.ReactNode;          // レンダリング可能なもの
  icon: React.ReactElement;           // 単一要素
  render: (data: T) => React.ReactNode;  // Render prop
};

Discriminated unions - バリアント prop 用：

type ButtonProps =
  | { variant: 'link'; href: string }
  | { variant: 'button'; onClick: () => void };

function Button(props: ButtonProps) {
  if (props.variant === 'link') {
    return <a href={props.href}>Link</a>;
  }
  return <button onClick={props.onClick}>Button</button>;
}

</component_patterns>

<event_handlers>

ターゲット型を正確にするために、特定のイベント型を使用：

// Mouse
function handleClick(e: React.MouseEvent<HTMLButtonElement>) {
  e.currentTarget.disabled = true;
}

// Form
function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
  e.preventDefault();
  const formData = new FormData(e.currentTarget);
}

// Input
function handleChange(e: React.ChangeEvent<HTMLInputElement>) {
  console.log(e.target.value);
}

// Keyboard
function handleKeyDown(e: React.KeyboardEvent<HTMLInputElement>) {
  if (e.key === 'Enter') e.currentTarget.blur();
}

詳細は event-handlers.md を参照。フォーカス、ドラッグ、クリップボード、タッチ、ホイールイベントを含みます。

</event_handlers>

<hooks_typing>

useState - 合併型・null に対して明示的：

const [user, setUser] = useState<User | null>(null);
const [status, setStatus] = useState<'idle' | 'loading'>('idle');

useRef - DOM は null、可変は値：

const inputRef = useRef<HTMLInputElement>(null);  // DOM - ?. を使用
const countRef = useRef<number>(0);               // 可変 - 直接アクセス

useReducer - アクション用 discriminated union：

type Action =
  | { type: 'increment' }
  | { type: 'set'; payload: number };

function reducer(state: State, action: Action): State {
  switch (action.type) {
    case 'set': return { ...state, count: action.payload };
    default: return state;
  }
}

Custom hooks - as const による tuple 戻り値：

function useToggle(initial = false) {
  const [value, setValue] = useState(initial);
  const toggle = () => setValue(v => !v);
  return [value, toggle] as const;
}

useContext - null ガードパターン：

const UserContext = createContext<User | null>(null);

function useUser() {
  const user = useContext(UserContext);
  if (!user) throw new Error('useUser outside UserProvider');
  return user;
}

詳細は hooks.md を参照。useCallback、useMemo、useImperativeHandle、useSyncExternalStore を含みます。

</hooks_typing>

<generic_components>

ジェネリックコンポーネントは prop から型を推論 - 呼び出しサイトでの手動アノテーション不要。

パターン - keyof T で列キー、render prop でカスタムレンダリング：

type Column<T> = {
  key: keyof T;
  header: string;
  render?: (value: T[keyof T], item: T) => React.ReactNode;
};

type TableProps<T> = {
  data: T[];
  columns: Column<T>[];
  keyExtractor: (item: T) => string | number;
};

function Table<T>({ data, columns, keyExtractor }: TableProps<T>) {
  return (
    <table>
      <thead>
        <tr>{columns.map(col => <th key={String(col.key)}>{col.header}</th>)}</tr>
      </thead>
      <tbody>
        {data.map(item => (
          <tr key={keyExtractor(item)}>
            {columns.map(col => (
              <td key={String(col.key)}>
                {col.render ? col.render(item[col.key], item) : String(item[col.key])}
              </td>
            ))}
          </tr>
        ))}
      </tbody>
    </table>
  );
}

制約付きジェネリクス - 必須プロパティ用：

type HasId = { id: string | number };

function List<T extends HasId>({ items }: { items: T[] }) {
  return <ul>{items.map(item => <li key={item.id}>...</li>)}</ul>;
}

詳細は generic-components.md を参照。Select、List、Modal、FormField パターンを含みます。

</generic_components>

<server_components>

React 19 Server Components はサーバー上で実行され、非同期にできます。

非同期データ取得：

export default async function UserPage({ params }: { params: { id: string } }) {
  const user = await fetchUser(params.id);
  return <div>{user.name}</div>;
}

Server Actions - ミューテーション用 'use server'：

'use server';

export async function updateUser(userId: string, formData: FormData) {
  await db.user.update({ where: { id: userId }, data: { ... } });
  revalidatePath(`/users/${userId}`);
}

Client + Server Action：

'use client';

import { useActionState } from 'react';
import { updateUser } from '@/actions/user';

function UserForm({ userId }: { userId: string }) {
  const [state, formAction, isPending] = useActionState(
    (prev, formData) => updateUser(userId, formData), {}
  );
  return <form action={formAction}>...</form>;
}

Promise ハンドオフ用 use()：

// Server: await なしで promise をパス
async function Page() {
  const userPromise = fetchUser('123');
  return <UserProfile userPromise={userPromise} />;
}

// Client: use() でアンラップ
'use client';
function UserProfile({ userPromise }: { userPromise: Promise<User> }) {
  const user = use(userPromise);
  return <div>{user.name}</div>;
}

詳細は server-components.md を参照。並列取得、ストリーミング、エラーバウンダリーを含みます。

</server_components>

<routing>

TanStack Router と React Router v7 の両方が型安全なルーティングソリューションを提供します。

TanStack Router - Zod 検証による実行時型安全性：

import { createRoute } from '@tanstack/react-router';
import { z } from 'zod';

const userRoute = createRoute({
  path: '/users/$userId',
  component: UserPage,
  loader: async ({ params }) => ({ user: await fetchUser(params.userId) }),
  validateSearch: z.object({
    tab: z.enum(['profile', 'settings']).optional(),
    page: z.number().int().positive().default(1),
  }),
});

function UserPage() {
  const { user } = useLoaderData({ from: userRoute.id });
  const { tab, page } = useSearch({ from: userRoute.id });
  const { userId } = useParams({ from: userRoute.id });
}

React Router v7 - Framework Mode での自動型生成：

import type { Route } from "./+types/user";

export async function loader({ params }: Route.LoaderArgs) {
  return { user: await fetchUser(params.userId) };
}

export default function UserPage({ loaderData }: Route.ComponentProps) {
  const { user } = loaderData; // loader から型付け
  return <h1>{user.name}</h1>;
}

詳細は tanstack-router.md を参照（TanStack パターン）と react-router.md を参照（React Router パターン）。

</routing> <rules>

常に（ALWAYS）：

• 特定のイベント型（MouseEvent、ChangeEvent など）
• 合併型・null に対して明示的な useState
• ネイティブ要素拡張に ComponentPropsWithoutRef
• バリアント prop に discriminated union
• tuple 戻り値に as const
• React 19 での ref as prop（forwardRef なし）
• フォームアクションに useActionState
• 型安全なルーティングパターン（ルーティングセクション参照）

決してしない（NEVER）：

• イベントハンドラーに any
• children に JSX.Element（ReactNode を使用）
• React 19+ での forwardRef
• useFormState（非推奨）
• DOM ref の null 処理を忘れる
• 同じファイルで Server/Client コンポーネントを混在
• use() に渡す promise を await する

</rules> <references>

• hooks.md - useState、useRef、useReducer、useContext、カスタムフック
• event-handlers.md - すべてのイベント型、ジェネリックハンドラー
• react-19-patterns.md - useActionState、use()、useOptimistic、移行
• generic-components.md - Table、Select、List、Modal パターン
• server-components.md - 非同期コンポーネント、Server Actions、ストリーミング
• tanstack-router.md - TanStack Router 型付きルート、サーチパラム、ナビゲーション
• react-router.md - React Router v7 ローダー、アクション、型生成、フォーム

</references>