react-19-component-scaffolder

React 19 コンポーネントスキャフォルダー

パラメーター化されたテンプレートから、React 19／19.2 のコンポーネント、ページ、フック、関連ファイルを生成します。すべてのテンプレートでは、同階層の react スキルで定められたパターンを適用します。つまり、ref は通常の props として扱う（forwardRef は使用しない）、Context をプロバイダーとして直接レンダリングする（.Provider は使用しない）、useActionState ＋ useFormStatus でフォームアクションを実装する、ドキュメントのメタデータをインラインで記述する、外部サブスクリプションには useSyncExternalStore を使う、フック本体は YMNNAE に準拠させる、といったパターンです。

適用する場面

• 新しい React コンポーネント（Server、Client、または未指定。デフォルトは Server）を作成する
• React 19 アプリに新しいルート／ページを追加する
• プログレッシブエンハンスメント、楽観的 UI、または保留状態が必要なフォームを作成する
• state と dispatch を分割した新しい Context プロバイダーを設定する
• 外部状態をサブスクライブする、または非同期処理をラップするカスタムフックを記述する
• 型付き reducer で複雑な状態をモデル化する
• ドキュメントのメタデータ（<title>、<meta>、<link>）またはリソースヒント（preload、preconnect、prefetchDNS）を追加する
• ユーザーが「scaffold」「boilerplate」「generate」「new component」「new page」「new hook」と言う、またはいずれかのテンプレートの種類を指定する

使用可能なテンプレート

ファイル名はすべてケバブケースです。エクスポートする React の識別子（{Name}、use{Name}）は PascalCase／camelCase です。

#	テンプレート	使用場面	生成されるファイル
1	function-component	汎用の再利用可能なコンポーネント（Server または Client で動作）	{name-kebab}.tsx、{name-kebab}.test.tsx
2	server-component-page	サーバーでのデータ取得、Suspense、メタデータを含むルートページ	page.tsx
3	client-island	サーバーページ内にネストされた 'use client' のインタラクティブ要素	{name-kebab}-island.tsx、{name-kebab}-island.test.tsx
4	form-action	useActionState ＋ Zod スキーマ ＋サーバーアクションを使う変更フォーム	{name-kebab}-form.tsx、actions.ts、schema.ts
5	context-provider	state／dispatch を分割し、アクセサーフックを備えた共有状態	{name-kebab}-context.tsx
6	custom-hook	YMNNAE に準拠したフック（外部サブスクリプションまたは組み合わせたエフェクト）	use-{name-kebab}.ts、use-{name-kebab}.test.ts
7	reducer	判別可能なユニオン型のアクションと網羅的な switch を備えた型付き reducer	{name-kebab}-reducer.ts、{name-kebab}-reducer.test.ts
8	head-and-hints	ファーストビューのアセット向けドキュメントメタデータとリソースヒント	{name-kebab}-head.tsx

使用方法

1. ユーザーの依頼に合うテンプレートを特定します。判断が難しい場合は質問してください。条件を指定せずに「コンポーネントを作って」と依頼された場合は、function-component をデフォルトで使用します。
2. assets/templates/{name}.template のテンプレートを読みます。
3. references/conventions.md の関連する規約を読みます。すべてのテンプレートは、これらの規約に従うコードを生成します。
4. パラメーターを収集します（下記の「パラメーター」を参照）。文脈から推測できないパラメーターについてのみ、ユーザーに確認します。
5. テンプレート内のプレースホルダーを置き換えます。すべてのプレースホルダーは {curly_braces} で囲まれています。値が空のプレースホルダー（該当するものがない場合の {additional_hooks} など）は、空文字列に置き換えます。
6. Write ツールを使って、各出力ファイルを書き込みます。config.json のパス規約（module_path、route_path）に従ってください。
7. 適用した規約を説明し、生成されたコードがそのような形式になっている理由をユーザーに伝えます（例：「forwardRef ではなく ref を prop として使用しました。なぜなら…」）。

パラメーター

共通パラメーター（ほとんどのテンプレートで使用できます）：

パラメーター	必須	デフォルト	説明
name	はい	—	PascalCase（フック／リデューサーの場合は camelCase）で記述するコンポーネント／フック／リデューサーの識別子です。スキャフォルダーが file_name（ケバブケース）と name_kebab を自動的に生成します。
module_path	いいえ	src/components（または config.json の値）	生成ファイルを配置する、プロジェクトルート以下のディレクトリです
props	いいえ	[]	{name, type, required} のリストです。props インターフェースとして出力されます
with_test	いいえ	true	対応する *.test.tsx／*.test.ts ファイルを生成します
with_ref	いいえ	false	props に ref?: Ref<T> を追加します（テンプレート 1 と 3）

テンプレート固有のパラメーターは、各テンプレート冒頭のコメントに記載されています。

セットアップ

初回使用時に config.json にプロジェクト固有のパスを設定すると、生成ファイルが適切な場所に配置されます。デフォルトでは、標準的な src/ をルートとするプロジェクトを想定しています。対話形式で変更するには、次の項目を設定します。

• module_path — コンポーネントの配置場所（例：src/components、app/_components）
• route_path — Server Component のページの配置場所（例：app/、src/routes/）
• hooks_path — カスタムフックの配置場所（例：src/hooks）
• test_runner — vitest（デフォルト）または jest（テストテンプレート内のインポートを変更します）

既存コードの規約準拠（複数ファイルのリファクタリング）

ユーザーが新しいコードの生成ではなく、複数のファイルにわたって既存コンポーネントをこのスキルの規約に準拠させる、モダナイズする、または整合させるよう求めた場合は、ファイルごとに作業を進めず、references/_conform-algorithm.md に従ってください。

このドキュメントにある、譲れない点は次の 2 つです。

1. grep より判断を優先する。 各規約は構文上のマーカー（forwardRef、<Context.Provider>、react-helmet、onSubmit=、react-dom/test-utils）を基準にしています。grep で簡単なケースは見つかりますが、見せかけを見落とします。たとえば、作者が forwardRef を避けたために手動でコールバック ref を渡しているケース、名前は付いていないものの実質 useActionState である独自の useState({ pending, error })、document.title を手動で設定する処理などです。grep は全体把握と事後の網羅性確認にのみ使い、主な検出手段にはしないでください。
2. ファイル単位ではなく、規約単位で進める。 まず対象ファイルをすべて読み込み、次に優先順位に沿って（まず ref／context／フォーム、最後に命名／インポート）規約を 1 つずつ、すべてのファイルに適用してください。レポートは規約ごとにまとめ、複数ファイルにまたがる関連箇所を示します。

新しいスキャフォールドを作成する場合は、これらの手順を省略してテンプレートに進んでください。

このスキルが生成しない React 19 のパターン

• forwardRef(...) ラッパー — 代わりに function Name({ ref, ...props }) を出力します
• <Context.Provider value={...}> — 代わりに <Context value={...}> を出力します
• useFormState — 代わりに useActionState を出力します
• 更新処理用の onSubmit ハンドラー — 代わりに <form action={serverAction}> を出力します
• 引数を指定しない useRef<T>() — 代わりに useRef<T>(null) を出力します
• 派生状態、親への通知、または状態変更時の POST に useEffect を使うこと — 一切生成しません（規約：状態の導出を参照）
• react-dom/test-utils — 代わりに import { act } from '@testing-library/react' を出力します
• 手動の <link rel="preload"> JSX — 代わりに react-dom の preload() を出力します
• react-helmet／react-helmet-async — 代わりにインラインの <title>／<meta>／<link> を出力します

注意点

gotchas.md を参照してください。初回リリース時は空で、スキルの使用に伴って注意点が蓄積されます。

関連スキル

• react — React 19 のベストプラクティスをまとめた決定版（44 のルール）です。このスキルのテンプレートは、それらのルールに準拠するコードを生成します。