Server Actions
優先度: P1(高)
[!WARNING] プロジェクトが App Router ではなく
pages/ディレクトリを使用している場合、このスキルは完全に無視してください。
API エンドポイントを作成せずに、フォームの送信とミューテーションを処理します。
実装ガイドライン
-
ディレクティブ: ファイルまたは関数の先頭を必ず
'use server'で開始します。型付きフォームフィールドにはformData.get('title')でアクセスします。ミューテーション用の非同期関数をエクスポートします。 -
フォーム処理:
<form>のactionプロパティを使用して、action={createPost}のようにアクションをトリガーします。useFormStatus()を使用してpending状態をハンドリングし、ボタンにdisabled={pending}を設定します。React 19 / Next.js 15 以降では、useActionStateを使用してaction={action}フォームの状態を管理します(<form action={action}>と併用)。 -
データ更新: ミューテーション成功後に、
revalidatePath('/')またはrevalidateTag('tag-name')を使用して UI を更新します。 -
インタラクティビティ: フォーム以外のトリガーでは、
useTransitionフックを使用してアクションを呼び出し、ローディング UI を表示してページがブロックされるのを防ぎます。 -
楽観的更新:
useOptimisticを使用して、サーバーがミューテーションを確定する前に、期待される UI 状態を即座に表示します。 -
セキュリティ:
FormDataからのすべての入力をサニタイズします。すべてのアクション内で認証チェックを実行します(await auth())。ファイルアップロードはサイズと MIME タイプで制限します。 -
フォーム:
<form action={createPost}>(プログレッシブエンハンスメントは JavaScript なしでも動作します)。 -
イベントハンドラ:
onClick={() => createPost(data)}。 -
保留状態:
useFormStatusフックを使用します(フォーム内でレンダリングされるコンポーネント内に配置する必要があります)。
P1: 運用基準
1. セキュリティとバリデーション
処理前に、z.object({ スキーマと safeParse を使用して入力を必ず検証します。アクション内で認可を確認します。セキュアアクションの例 を参照してください。
2. 保留状態
状態管理には useActionState(React 19 / Next.js 15+)を、ボタンのローディング状態には useFormStatus を使用します。
制約
- クロージャ: 隠れたクロージャの暗号化オーバーヘッドやシリアライゼーションのバグを防ぐため、コンポーネント内でアクションを定義しないでください。
- リダイレクト: 成功時のナビゲーションには
redirect()を使用します。これはエラーをスローし、Next.js がそれをキャッチしてリダイレクトを処理します。
アンチパターン
- 未検証の Server Action 入力は禁止: 処理前に必ず Zod で検証すること。
- 認証チェックの省略禁止: ミドルウェアだけでなく、すべてのアクション内でセッション/ユーザーを確認すること。
- コンポーネント内でのアクション定義禁止: クロージャのバグを避けるため、
actions.tsで定義すること。 - try/catch 内での
redirect()禁止:redirect()はエラーをスローします。catch するとリダイレクトが抑制されます。