Form Actions：ミューテーションのAPI Routesを置き換える

従来のNext.jsアプリケーションでは、フォーム送信にクライアントコンポーネントが必要です。その中のonSubmitハンドラーからfetch()を呼び出し、API RouteへデータをPOSTします。このパターンは動作しますが、クライアント側のfetchロジックとサーバー側のRouteハンドラーを別々に記述して保守する必要があります。

Server Actionsを使うと、fetch呼び出しとAPI Routeを1つの関数に置き換えられます。フォーム要素には、actionプロパティとしてServer Actionを指定します：<form action={serverAction}>。Reactが送信をインターセプトし、フォームデータを渡してActionを自動的に呼び出します。

フォームから呼び出された場合、Server Actionは引数としてFormDataオブジェクトを自動的に受け取ります。個々のフィールドにはformData.get('email')でアクセスでき、値は文字列として返されます。複数選択フィールドに使用するgetAll()など、FormDataの標準メソッドをすべて利用できます。

Server Actionは、クライアントで利用できるシリアライズ可能な値を返せます。{ error: 'Email already exists' }のようなエラーオブジェクトや、{ success: true }のような成功フラグを返すことで、ページ全体を再読み込みせずにクライアント側でUIを適切に更新できます。

フォームのactionがServer Actionであるため、フォームを配置するページコンポーネントをClient Componentにする必要はありません。サーバーがフォームを静的HTMLとしてレンダリングし、エラー表示などのインタラクティブな部分だけがクライアント側のJavaScriptを必要とします。これにより、クライアントバンドルを大幅に小さくできます。

action={serverAction}を指定したフォームは、JavaScriptが有効でなくても動作します。ブラウザーは標準のHTMLフォームPOSTを実行し、サーバーがActionを実行して更新後のページを返します。この真のプログレッシブエンハンスメントにより、あらゆる環境でフォームが適切に機能します。

Server Actionでデータを変更した後は、キャッシュされたページデータを更新する必要があります。Action内でrevalidatePath('/dashboard')を呼び出すと、そのパスに対するNext.jsのキャッシュが無効化され、次のリクエストで最新のデータが取得されます。これは、ミューテーション後にサーバーレンダリングされたページを最新の状態に保つ標準的な方法です。

revalidateTag('user-data')を使うと、revalidatePathよりきめ細かくキャッシュを無効化できます。next: { tags: ['user-data'] }を指定してfetch呼び出しにタグを付け、Server Action内からタグ付けされたすべてのデータを一度に無効化します。そのデータを表示するパスがどれであるかは問いません。

Server Actionsでは、ミューテーションが成功した後にnext/navigationモジュールのredirect('/success')を呼び出して、ユーザーを新しいページへリダイレクトできます。このリダイレクトはサーバー側で処理されるため、ブラウザーはクライアント側のリダイレクトではなく、適切なナビゲーションレスポンスを受け取ります。

Server Actionsはフォーム送信に限定されません。ボタンのクリックなどフォーム以外のトリガーでは、Actionの呼び出しをstartTransition(() => action(arg))でラップします。これによりナビゲーションがトランジションとして扱われ、サーバー上でActionが実行されている間もReactは現在のUIを表示し続けられます。

サーバー側のバリデーションにはServer Actionsが適しています。FormDataのフィールドを検証し、検証に失敗した場合はエラーを返し、すべてのフィールドが有効な場合にだけミューテーションを実行します。Zodのようなライブラリも適しています。FormDataを型付きスキーマにパースし、失敗時にはエラーマップを返せます。

フォーム送信によって呼び出された場合、Server Actionは引数として何を受け取りますか。

Server Actionsは、フォームのミューテーションで使われてきたfetch + API Routeパターンに置き換わるものです。フォームのactionプロパティにはServer Actionを直接指定でき、ActionはFormDataオブジェクトを受け取ります。ActionはクライアントUIの更新に使えるシリアライズ可能な結果を返し、キャッシュ無効化のためのrevalidatePathとrevalidateTagをサポートします。また、JavaScriptがなくてもプログレッシブに動作します。